just going to build and push locally instead of gitea actions

This commit is contained in:
C-West8
2026-10-23 09:47:55 -05:00
parent 3d8b453428
commit 3617c1dc95
8 changed files with 120 additions and 126 deletions

View File

@@ -4,7 +4,7 @@ How to deploy, update, back up and troubleshoot the sync server.
## What runs
- **One container**, from the image CI builds (see [Continuous integration](#continuous-integration)). Never run more than one copy: the locks that stop two syncs of the same project overlapping live inside the process.
- **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.
@@ -15,7 +15,7 @@ How to deploy, update, back up and troubleshoot the sync server.
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. Because CI builds the image, `ORIGIN` is a variable in Gitea, not a Portainer setting (see below).
- **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".
@@ -29,7 +29,7 @@ Set these in the Portainer stack's **Environment variables**, or in a `.env` fil
| `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 from CI | Image to run. Set it to a commit tag to roll back (see [Rolling back](#rolling-back)) |
| `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 |
@@ -39,34 +39,40 @@ Set these in the Portainer stack's **Environment variables**, or in a `.env` fil
The Microsoft Graph and APS credentials will be added to this table when the live connections are built.
## Continuous integration
## Publishing an image
`.gitea/workflows/ci.yml` runs on Gitea Actions:
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.
- **Every pull request and every push to main:** lint, type check, tests and a production build. A pull request whose checks fail shouldn't be merged.
- **Pushes to main, once those pass:** builds the Docker image and pushes it to this Gitea server's container registry as `primegit.primecontrols-dev.com/c.west/sharepoint-acc-sync`, tagged `latest` and with the commit's short hash (for example `1a2b3c4`). It then asks Portainer to redeploy, if a webhook is set.
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:
One-time setup, in the repository's **Settings → Actions**:
```sh
docker login primegit.primecontrols-dev.com
```
| Name | Kind | Required | What it is |
| ----------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REGISTRY_TOKEN` | secret | yes | Gitea access token with the `write:package` scope, from **User settings → Applications**. Used to push the image |
| `REGISTRY_USERNAME` | variable | no | The account that owns `REGISTRY_TOKEN`. Defaults to the repository owner |
| `ORIGIN` | variable | no | Only for plain HTTP (see [above](#choose-how-people-will-reach-it)). Changing it takes effect from the next image built |
| `PORTAINER_WEBHOOK_URL` | secret | no | The stack's webhook URL (see [First deploy](#first-deploy-portainer)). Without it, the image is pushed but the stack has to be redeployed by hand |
Then, from a clone with everything committed:
The repository also needs Actions turned on (**Settings → Repository → Actions**) and a runner that can run Docker commands. Gitea's own runner does by default. If the image job fails at `docker login` with "command not found" or "Cannot connect to the Docker daemon", ask whoever looks after the runner.
```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. Push to main and wait for the CI run to finish, so there's an image to pull.
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. To redeploy automatically after each CI run, turn on **GitOps updates**, choose **Webhook** and turn on **Re-pull image**. Copy the webhook URL into the `PORTAINER_WEBHOOK_URL` secret in Gitea.
7. **Deploy the stack.**
8. Check it's working:
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.
@@ -75,7 +81,7 @@ From the command line on the Docker host, the equivalent is `docker compose up -
## Updating
Merge to main. Once CI passes, the new image is pushed and, with the webhook set, Portainer redeploys it. Without the webhook, open the stack in Portainer and use **Pull and redeploy**. Every deploy pulls the newest image, so a redeploy never runs an old one.
[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`.
@@ -83,7 +89,7 @@ When the container stops, a sync in progress gets up to 2 minutes to finish. If
## Rolling back
Every image CI pushes is kept under its commit's short hash. Find the hash of the last good commit in Gitea (or under **Packages** on the repository owner's 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`.
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.
@@ -102,14 +108,14 @@ To restore one: stop the stack, put the backup in the volume as `sync.db`, delet
## 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 the `ORIGIN` variable in Gitea and rerun CI |
| 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 the `ORIGIN` variable in Gitea and rerun CI |
| 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 CI hasn't pushed an image yet. See First deploy |
| CI's image job fails at "Log in to the registry" | `REGISTRY_TOKEN` is missing, expired or lacks `write:package`, or `REGISTRY_USERNAME` doesn't match the token's owner |
| A merge passed CI but the old version is still running | No webhook is set, or it failed (see the last step of the CI run). 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 |
| 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 |
| 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 |