Skip to content

Deployment (VPS) & docs publishing

App — Docker Compose

# on the VPS (e.g. Ubuntu 22.04, OVH)
sudo apt update && sudo apt install -y docker.io docker-compose-plugin   # or get.docker.com
git clone https://github.com/Nisseya/nexora.git ~/nexora && cd ~/nexora

# root .env (prod)
cat > .env <<'EOF'
ORIGIN=https://<app-domain>
BETTER_AUTH_SECRET=<secret_32+_chars>
PUBLIC_DOCS_URL=https://<docs-domain>
EOF

docker compose up --build -d
docker compose ps          # db healthy, seed/import done, app up
docker compose logs -f app

Update:

cd ~/nexora
git pull
docker compose up --build -d

Videos: send them to web/static/videos/original/ (rsync from your machine) — no restart needed, the volume is hot-mounted.

Documentation — automatic CI/CD

The docs (this site) live in docs/ of the monorepo, are built with MkDocs Material (Docker container nexora-docs, port 8080) and are deployed automatically to the VPS by GitHub Actions:

flowchart LR
   G["push master (docs/**)"] --> A["GitHub Actions<br/>build MkDocs (Docker)"]
   A --> S["SSH → VPS<br/>git pull + compose build docs"]
   S --> N["nginx :443 → 127.0.0.1:8080 (container)"]

1. The workflow

.github/workflows/deploy-docs.yml — triggers:

  • push on master modifying docs/**;
  • workflow_dispatch (manual run in “Actions”).

It builds the MkDocs site (Docker) to verify it compiles, then SSHs to the VPS (git pull + docker compose build docs + docker compose up -d docs) via sshpass + the VPS_PASSWORD secret (or VPS_SSH_KEY).

2. On the VPS (once)

The nginx config is generated programmatically (no more hand editing):

cd ~/nexora
node scripts/nexora-nginx.mjs --yes        # generates nexora-app.conf + nexora-docs.conf
node scripts/nexora-nginx.mjs --install    # copies into /etc/nginx + nginx -t + reload
sudo certbot --nginx -d <app-domain> -d <docs-domain>

The docs are served by the nexora-docs container (8080):

docker compose up docs --build -d

3. GitHub secrets (repo → Settings → Secrets)

Secret Value
VPS_HOST 57.131.25.253
VPS_USER ubuntu
VPS_PASSWORD SSH password (or VPS_SSH_KEY = private key)

4. Result

  • The tooltip “?” links of the app point to PUBLIC_DOCS_URL (= https://<docs-domain>) — configurable in the app .env.
  • Every git push in docs/ updates the site within tens of seconds.

Prod recommendations

  • HTTPS: serve the app and the docs behind nginx (certificates managed by Certbot — see scripts/nexora-nginx.mjs): <app-domain> → 127.0.0.1:5173, <docs-domain> → 127.0.0.1:8080, then set ORIGIN/PUBLIC_DOCS_URL to https.
  • BETTER_AUTH_SECRET: always a real 32+ char secret.
  • The gold/media data persists in Docker volumes / the lake (processing/lake) — back them up.