123 lines
11 KiB
Markdown
123 lines
11 KiB
Markdown
# Runbook
|
|
|
|
How to deploy, update, back up and troubleshoot the sync server.
|
|
|
|
## What runs
|
|
|
|
- **One container**, from the image published to the Gitea registry (see [Publishing an image](#publishing-an-image)). 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 holds `sync.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_PORT` sets the port on the server (default 3000).
|
|
- **Health check:** `GET /healthz` answers `{"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 `Host` header on, which most do by default. Leave `ORIGIN` empty.
|
|
- **Plain HTTP** on the VPN, for example `http://sync-server:3000`. Set `ORIGIN` to exactly the address people will type, with no trailing slash. `ORIGIN` is fixed when the image is built, so the app only works at that one address: not by IP if `ORIGIN` uses a name, and not on a different port. So `ORIGIN` is set when [publishing an image](#publishing-an-image), not in Portainer.
|
|
|
|
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 |
|
|
| `HOST_PORT` | no | `3000` | Port on the server |
|
|
| `IMAGE` | no | latest published | Image to run. Set it to a commit tag to roll back (see [Rolling back](#rolling-back)) |
|
|
| `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.
|
|
|
|
## Publishing an image
|
|
|
|
Images are built on a developer's machine and pushed to the Gitea server's container registry as `primegit.primecontrols-dev.com/c.west/sharepoint-acc-sync`. Portainer only pulls and runs them.
|
|
|
|
Once per machine, log in to the registry with a Gitea access token that has the `write:package` scope (**User settings → Applications**). Docker asks for the username and the token:
|
|
|
|
```sh
|
|
docker login primegit.primecontrols-dev.com
|
|
```
|
|
|
|
Then, from a clone with everything committed:
|
|
|
|
```sh
|
|
npm run image:publish
|
|
```
|
|
|
|
It stops at the first failure. In order, it:
|
|
|
|
1. refuses to go on if there are uncommitted changes, so the image always matches a commit;
|
|
2. runs lint, type check and tests;
|
|
3. builds the image from the `Dockerfile`, pulling the newest Node base image;
|
|
4. pushes it tagged with the commit's short hash (for example `1a2b3c4`), then as `latest`.
|
|
|
|
Over plain HTTP, set `ORIGIN` in the same shell first, for example in PowerShell `$env:ORIGIN = 'http://sync-server:3000'`, or in bash `ORIGIN=http://sync-server:3000 npm run image:publish`. The script prints the `ORIGIN` it's using before it starts. It ignores `.env`, so a local `ORIGIN=http://localhost:3000` never ends up in a published image.
|
|
|
|
## First deploy (Portainer)
|
|
|
|
1. [Publish an image](#publishing-an-image), so there's one to pull.
|
|
2. If the image isn't public, add the registry under **Registries → Add registry → Custom registry**: URL `primegit.primecontrols-dev.com`, with a Gitea access token that has the `read:package` scope.
|
|
3. **Stacks → Add stack**, give it a name such as `sharepoint-acc-sync`, and choose **Repository**.
|
|
4. Enter the repository URL and the branch (`refs/heads/main`). The compose path is `docker-compose.yml`. If the repository is private, turn on authentication and use a read-only access token.
|
|
5. Under **Environment variables**, add the settings above.
|
|
6. **Deploy the stack.**
|
|
7. Check it's working:
|
|
- the container shows as **healthy** in Portainer;
|
|
- the logs show `Sync server started` with the expected `backend`;
|
|
- 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` in a clone of the repository, with the settings in `.env`. `docker compose up -d --build` builds the image locally instead of pulling it.
|
|
|
|
## Updating
|
|
|
|
[Publish an image](#publishing-an-image), then open the stack in Portainer and use **Pull and redeploy**. Every deploy pulls the newest image, so a redeploy never runs an old one.
|
|
|
|
On the command line: `git pull`, then `docker compose up -d`.
|
|
|
|
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.
|
|
|
|
## Rolling back
|
|
|
|
Every published image is kept under its commit's short hash. Find the hash of the last good one under **Packages** on the repository owner's Gitea page, set the stack's `IMAGE` variable to `primegit.primecontrols-dev.com/c.west/sharepoint-acc-sync:<hash>`, and redeploy. Remove `IMAGE` again to go back to following `latest`.
|
|
|
|
A rollback doesn't undo database changes, and an older image may not work with a database a newer one has changed. Before deploying a release that adds a migration (a new file in `drizzle/`), take a [backup](#backups), and restore it if you roll back past that release.
|
|
|
|
## 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:
|
|
|
|
```sh
|
|
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. Publish again with the right `ORIGIN` |
|
|
| 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. Publish again with `ORIGIN` set |
|
|
| Container is unhealthy or keeps restarting | Check the logs. Bad settings are reported by name at startup |
|
|
| Deploy fails pulling the image ("unauthorized" or "not found") | The registry isn't added in Portainer, its token lacks `read:package`, or no image has been published yet. See First deploy |
|
|
| `npm run image:publish` fails pushing ("unauthorized" or "denied") | Not logged in to the registry on this machine, or the token lacks `write:package` or has expired. Run `docker login` again |
|
|
| Push fails with "failed commit on ref index-sha256:... 404 Not Found" | The image was built without `--provenance=false`, so Docker Desktop wrapped it in an index Gitea rejects. Use `npm run image:publish`, which sets it |
|
|
| A new version was published but the old one is still running | The stack wasn't redeployed. Use **Pull and redeploy** in Portainer |
|
|
| 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 |
|