just going to build and push locally instead of gitea actions
This commit is contained in:
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user