Legacy Wiki.js local dev and prod sync (buckyverse.org)

Legacy notes for the old Wiki.js deployment, kept for reference after the wiki migration to llm-wiki/.

Why

• Production sync is slow — editing and syncing on the droplet can be slow and fragile.
• Local mirror — pull the prod DB (and optionally wiki data) once, work locally at full speed.
• Controlled push — when ready, push DB (and optionally data) back to DigitalOcean.

Architecture

• Local: Docker Compose in dev/wikijs/: Wiki.js 2 + PostgreSQL. Data in Docker volumes buckyverse-wikijs-db-data and buckyverse-wikijs-data.
• Production: Wiki.js on a DigitalOcean droplet, run with Docker Compose (PostgreSQL + wiki service).
• Sync: Scripts use SSH to run pg_dump on prod and restore locally (pull), or the reverse (push). Optional: sync the wiki data volume with --data.

Production setup (from inspect)

As of the last inspect-prod.sh run:

PROD_COMPOSE_DIR is optional. Pull and push use docker exec by container name (db, wiki), so they work without it. If you set PROD_COMPOSE_DIR, you can use push-to-prod.sh --switch to have the script point Wiki.js at the new DB automatically. (The stack may have been started by root from e.g. /etc/wiki or /root/wiki; r26d often cannot read those paths.)

Related

• Synergetics Dictionary: Content is synced from the elib-synergetics-dictionary repo via GraphQL; see that doc for the sync script and options.
• Sync to another dev machine: To copy the Wiki.js DB to a second dev environment on the same network, see wikijs-sync-to-other-dev.md.
• Change favicon on the droplet: Wiki.js has no admin setting for favicon; see wikijs-favicon-droplet.md for mounting custom favicons in Docker on production.

Prerequisites

• Docker and Docker Compose on your machine.
• SSH access as r26d@buckyverse.org (see ssh-keys-audit.md if needed).
• On the droplet: Wiki.js run via Docker Compose with services db (PostgreSQL) and wiki.

One-time setup

1. Clone/navigate to repo

   cd /path/to/buckyverse.org
   

2. Configure local env

   cd dev/wikijs
   cp .env.example .env
   

   Edit .env:

   • PROD_SSH (required): r26d@buckyverse.org.
   • PROD_DB_USER: wiki (production Postgres user; local uses wikijs).
   • PROD_SSH_KEY (optional): path to SSH key if not default (e.g. ~/.ssh/id_rsa_r26d_2048).
   • PROD_WIKI_VOLUME (optional): only for --data sync; use volume ID e061d18871d73252bbef2d76f92ecd83933c39c7b99aca43a48bfb8431059fec.
     PROD_COMPOSE_DIR (optional): set if you want push-to-prod.sh --switch to update the prod Wiki.js DB and recreate the container from your machine.

3. Start local stack

   docker compose up -d
   

   Open http://localhost:3000 and complete the initial Wiki.js wizard once (this will be overwritten when you pull from prod).

4. Pull production

   chmod +x scripts/pull-from-prod.sh scripts/push-to-prod.sh
   ./scripts/pull-from-prod.sh
   

   This dumps the prod PostgreSQL DB, restores it locally, and restarts the local wiki. Reload http://localhost:3000 — you should see production content.

Daily workflow

1. Refresh from prod (optional)
   To get latest production state:

   cd dev/wikijs
   ./scripts/pull-from-prod.sh
   

2. Edit locally
   Use http://localhost:3000. No dependency on production sync speed.

3. Push to production
   When ready to publish:

   ./scripts/push-to-prod.sh
   

   The script creates a new database on prod (e.g. wiki_20260217_143022), restores your local dump into it, and leaves the current prod DB unchanged. You then point Wiki.js at the new DB; if anything goes wrong, rollback is instant by pointing back. See wikijs-push-rollback.md for switch and rollback steps.

Syncing the wiki data volume (optional)

Wiki.js stores uploads and cache in a data volume. If you need that mirrored:

• Find prod volume name on the droplet: docker volume ls (often wikijs_wiki-data or <compose_project>_wiki-data).
• Set in .env: PROD_WIKI_VOLUME=that_volume_name.
• Pull including data: ./scripts/pull-from-prod.sh --data
• Push including data: ./scripts/push-to-prod.sh --data

Use --data only when you need uploads/cache in sync; DB-only is usually enough for content.

Production compose path

If Wiki.js on the droplet is not in /root/wikijs, set in .env:

PROD_COMPOSE_DIR=/opt/wikijs

Scripts run docker compose in that directory on the remote host.

Excluding large tables from pull

The assetData table (Wiki.js asset blobs) can be large and cause the connection to drop during pg_dump. The pull script excludes that table’s data by default (schema is still dumped). Your local wiki will have the table but no asset rows; page content and structure are unchanged. To include it (and risk the same failure), set in .env:

PROD_DUMP_EXCLUDE_TABLE_DATA=

To include assetData in the dump (may fail if the table is large), set PROD_DUMP_EXCLUDE_TABLE_DATA= (empty) in .env. Default is "public"."assetData".

Troubleshooting

• “Set PROD_SSH in .env” — create .env from .env.example and set PROD_SSH.
• SSH connection refused / timeout — check droplet IP, firewall (port 22), and SSH key.
• Permission denied (publickey) — use PROD_SSH_KEY in .env or ssh -i <key> $PROD_SSH to test.
• No such service “db” / “wiki” — confirm prod runs Docker Compose with services named db and wiki; adjust prod or script if your names differ.
• Restore fails locally — ensure local stack is up (docker compose up -d), then run pull again. If the prod DB is very large, dump/restore may take a few minutes.
• Prod slow after push — first load after DB restore can be heavy; give it a minute. If you use --data, ensure the droplet has enough disk and memory.

Files reference

Security notes

• Do not commit .env (it’s in dev/wikijs/.gitignore).
• Prefer SSH keys over passwords for PROD_SSH.
• Backups in dev/wikijs/backups/ may contain sensitive wiki content; keep that directory local and out of version control.