8.3 KiB
Runbook
How to deploy, update, back up and troubleshoot the sync server.
What runs
- One container, built from the
Dockerfile. Never run more than one copy: the locks that stop two syncs of the same project overlapping live inside the process. - One volume,
sync-data, mounted at/data. It holdssync.db, the SQLite database with the projects, the record of which ACC item belongs to which SharePoint item, and the last 7 days of history. - Port 3000 inside the container.
HOST_PORTsets the port on the server (default 3000). - Health check:
GET /healthzanswers{"status":"ok"}once the server has started. Docker checks it every 30 seconds, and Portainer shows the result as healthy or unhealthy. - Logs: one JSON object per line on stdout. View them in Portainer under the container's logs.
Choose how people will reach it
Decide this before the first deploy, because it changes how the image is built.
- Behind an HTTPS reverse proxy (recommended). The proxy must pass the original
Hostheader on, which most do by default. LeaveORIGINempty. - Plain HTTP on the VPN, for example
http://sync-server:3000. SetORIGINto exactly the address people will type, with no trailing slash.ORIGINis fixed when the image is built, so the app only works at that one address: not by IP ifORIGINuses a name, and not on a different port.
If ORIGIN is wrong or missing over plain HTTP, pages still load, but every button that submits something fails with "Cross-site POST form submissions are forbidden".
Settings
Set these in the Portainer stack's Environment variables, or in a .env file next to docker-compose.yml when using the command line. Never put them in the repository.
| Variable | Required | Default | What it is |
|---|---|---|---|
ADMIN_USERNAME |
yes | Login for the admin pages | |
ADMIN_PASSWORD |
yes | Password for the admin pages | |
SESSION_SECRET |
yes | Signs admin logins. Any long random string, e.g. the output of node -e "console.log(crypto.randomBytes(32).toString('hex'))". Changing it logs admins out |
|
ORIGIN |
see above | The app's address when served over plain HTTP. Build time only | |
HOST_PORT |
no | 3000 |
Port on the server |
SYNC_BACKEND |
no | live |
simulated runs the in-memory demo instead (nothing is saved) |
TZ |
no | America/Chicago |
Time zone the status pages show times in |
POLL_INTERVAL_SECONDS |
no | 180 |
How often every project is checked for changes |
MANUAL_RUN_COOLDOWN_SECONDS |
no | 30 |
Minimum gap between "Run now" presses for one project |
MAX_ATTEMPTS |
no | 3 |
Failed tries before a file is reported as an issue |
HISTORY_RETENTION_DAYS |
no | 7 |
How long sync history is kept |
The Microsoft Graph and APS credentials will be added to this table when the live connections are built.
First deploy (Portainer)
- Stacks → Add stack, give it a name such as
sharepoint-acc-sync, and choose Repository. - Enter the repository URL and the branch (
refs/heads/main). The compose path isdocker-compose.yml. If the repository is private, turn on authentication and use a read-only access token. - Under Environment variables, add the settings above.
- Deploy the stack. Portainer builds the image from the
Dockerfile, which takes a few minutes the first time. - Check it's working:
- the container shows as healthy in Portainer;
- the logs show
Sync server startedwith the expectedbackend; - the projects page opens at the chosen address, and the admin login works.
From the command line on the Docker host, the equivalent is docker compose up -d --build in a clone of the repository, with the settings in .env.
Updating
- In Portainer, open the stack and use Pull and redeploy. Make sure the image is rebuilt, not reused: after the first update, check that the change is actually live.
- On the command line:
git pull, thendocker compose up -d --build.
When the container stops, a sync in progress gets up to 2 minutes to finish. If it doesn't finish in time, it's marked in the history as stopped by a restart, and the next sync picks up whatever was left. Nothing needs cleaning up by hand.
Backups
Back up sync.db. Losing it means the tool forgets which ACC files it created. It would then treat every SharePoint file as new, and could not tidy up the ACC copies it made before.
To take a copy while the server is running:
docker exec <container> node -e "require('better-sqlite3')('/data/sync.db').backup('/data/backup.db').then(() => console.log('backed up'))"
docker cp <container>:/data/backup.db ./sync-backup.db
To restore one: stop the stack, put the backup in the volume as sync.db, delete any sync.db-wal and sync.db-shm beside it, then start the stack.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| Deploy fails with "required variable … is missing a value" | A required setting isn't set. Add it to the stack's environment variables |
| Buttons fail with "Cross-site POST form submissions are forbidden" | Plain HTTP without the right ORIGIN, or the app was opened at a different address. Set ORIGIN and rebuild |
| Admin login appears to work but doesn't stick | Plain HTTP without ORIGIN: the login cookie is marked HTTPS-only, so the browser drops it. Set ORIGIN and rebuild |
| Container is unhealthy or keeps restarting | Check the logs. Bad settings are reported by name at startup |
| Times on the pages are off by some hours | TZ doesn't match the office's time zone |
| A project shows Paused | Its SharePoint folder was deleted or couldn't be found. Nothing was deleted in ACC. Fix the folder, then Resume it on the admin page |