120 lines
5.3 KiB
Markdown
120 lines
5.3 KiB
Markdown
# Unraid deployment
|
|
|
|
MobilityOps is deployed from a committed source archive; the server does not need Gitea credentials. The portable `compose.yaml` is combined with `compose.unraid.yaml`. Of the MobilityOps-owned services, only the web application should be reachable from the trusted network. PostgreSQL and the API remain on the Compose network.
|
|
|
|
All hostnames, ports, paths and public domains below are operator-controlled configuration. Do not commit a production `.env`, SSH target or infrastructure inventory.
|
|
|
|
## Server layout
|
|
|
|
Define a local appdata root and URLs before following the examples:
|
|
|
|
```bash
|
|
export MOBILITYOPS_APPDATA_DIR=/mnt/user/appdata/mobilityops
|
|
export MOBILITYOPS_PUBLIC_URL=https://fleetops.example.com
|
|
export N8N_BASE_URL=https://automation.example.com
|
|
```
|
|
|
|
The `/mnt/user/appdata/...` value is an illustrative Unraid convention, not a repository requirement. Use a different persistent directory where appropriate.
|
|
|
|
- application directory: `${MOBILITYOPS_APPDATA_DIR}`;
|
|
- Compose project: `mobilityops`;
|
|
- public web URL: `${MOBILITYOPS_PUBLIC_URL}`;
|
|
- API and PostgreSQL: Compose network only;
|
|
- shared n8n: `${N8N_BASE_URL}`, outside the MobilityOps Compose project.
|
|
|
|
## Configure
|
|
|
|
Create `.env` from `.env.example`, replace every placeholder secret and set:
|
|
|
|
```dotenv
|
|
MOBILITYOPS_ENV=production
|
|
MOBILITYOPS_PUBLIC_URL=https://fleetops.example.com
|
|
MOBILITYOPS_API_PUBLIC_URL=https://fleetops.example.com/api
|
|
N8N_WEBHOOK_URL=https://automation.example.com/webhook/mobilityops-return
|
|
SESSION_COOKIE_SECURE=true
|
|
```
|
|
|
|
Configure `KNOWLEDGE_PROVIDER=ragcore` only after the RAGcore health and source-inventory checks pass. When RAGcore runs as a separate Compose project on the same host, keep its HTTP listener private and configure Fleet Ops through a shared Docker network, for example:
|
|
|
|
```dotenv
|
|
RAGCORE_BASE_URL=http://ragcore-app:8080
|
|
RAGCORE_DOCKER_NETWORK=ragcore-proxy
|
|
```
|
|
|
|
The release deployer takes non-secret integration URLs from the server `.env` on every promotion. Tokens and resolved API environment remain server-side and must not be printed.
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
cd "${MOBILITYOPS_APPDATA_DIR}"
|
|
./deploy/unraid/configure-env.sh \
|
|
"${MOBILITYOPS_PUBLIC_URL}" \
|
|
"${N8N_BASE_URL}/webhook/mobilityops-return"
|
|
|
|
git archive --format=tar.gz -o /tmp/mobilityops-source.tar.gz HEAD
|
|
sha256sum /tmp/mobilityops-source.tar.gz
|
|
# Copy the archive and run deploy-release.sh with its SHA-256 and full Git SHA.
|
|
```
|
|
|
|
`deploy-release.sh` stages a clean, commit-named release, builds OCI-labelled immutable API/web images, starts candidate replicas behind a stable gateway and removes previous replicas only after public readiness passes. It promotes without a seed/reset and leaves the database, backups and monitoring untouched during routine releases.
|
|
|
|
Run `python -m app.cli seed --reset` only for initial setup or an explicit synthetic-demo reset; it is never part of a routine deployment.
|
|
|
|
Refresh pinned stateful and monitoring containers explicitly after reviewing version and configuration changes:
|
|
|
|
```bash
|
|
./deploy/unraid/refresh-infrastructure.sh
|
|
```
|
|
|
|
Import and publish the MobilityOps workflow into an existing n8n container:
|
|
|
|
```bash
|
|
./deploy/unraid/setup-existing-n8n.sh \
|
|
n8n \
|
|
"${MOBILITYOPS_PUBLIC_URL}/api/v1/integrations/n8n/return-callback"
|
|
```
|
|
|
|
The callback token remains server-side and is never written to the repository. The bundled n8n service is a standalone fallback behind the explicit `bundled-n8n` Compose profile and is not started by the standard deployment.
|
|
|
|
## Operate
|
|
|
|
```bash
|
|
cd "${MOBILITYOPS_APPDATA_DIR}"
|
|
docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml ps
|
|
docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml logs --tail=200
|
|
docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec api alembic current
|
|
docker logs --tail=200 n8n
|
|
```
|
|
|
|
## Backup and restore
|
|
|
|
The `backup` service creates a backup immediately and every 24 hours. Each dump is checked by SHA-256 and `pg_restore --list`; at least weekly the newest dump is restored into a disposable database and its migration revision and core table counts are verified. Backups are retained for 30 days with at least seven copies protected from pruning. Health becomes unhealthy when the daily backup or eight-day restore-drill SLA is missed.
|
|
|
|
For a synthetic demo, an operator-configured rclone remote may be used as an off-site target. OAuth material belongs in an untracked, mode-0600 rclone configuration directory:
|
|
|
|
```bash
|
|
./deploy/unraid/configure-onedrive-backup.sh <rclone-remote>
|
|
docker inspect --format '{{.State.Health.Status}}' mobilityops-offsite-backup-1
|
|
```
|
|
|
|
Do not point `BACKUP_SECONDARY_DESTINATION` to another directory on the same storage system and describe it as off-site.
|
|
|
|
Create an on-demand backup, verify the newest backup or execute an isolated restore drill:
|
|
|
|
```bash
|
|
./deploy/unraid/backup-postgres.sh
|
|
./deploy/unraid/verify-postgres-backups.sh
|
|
docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec -T backup \
|
|
/opt/mobilityops/restore-drill-postgres.sh /backups/<backup>.dump
|
|
```
|
|
|
|
A restore is guarded and creates an additional safety backup before replacing the database:
|
|
|
|
```bash
|
|
./deploy/unraid/restore-postgres.sh \
|
|
backups/postgres/mobilityops-YYYYMMDDTHHMMSSZ.dump \
|
|
RESTORE-MOBILITYOPS
|
|
```
|
|
|
|
Test restores in a disposable environment before using a production backup for incident recovery.
|