Host on AWS Lightsail as boards.watersmedia.org
Deploy Waters Boards to AWS / deploy (push) Canceled after 0s
Deploy Waters Boards to AWS / deploy (push) Canceled after 0s
Replace the planned Synology deploy with one Lightsail box: Caddy in front of the app for automatic HTTPS (deploy/aws/docker-compose.yml, Caddyfile), a deploy script that rsyncs server/ and rebuilds in place without touching data/ or .env, and a Gitea workflow that runs the same script from the nas runner over SSH. README documents the box, DNS, .env, deploys and restore. Allow both church Google Workspace domains to sign in. Drop the NAS-only compose file. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5.1
@@ -2,7 +2,8 @@
|
||||
|
||||
A self-hosted work-management app for the Waters Church team: boards, groups, items, statuses,
|
||||
people, dates, updates and automations. It covers the parts of monday.com the team uses and
|
||||
runs on the NAS beside the checklist app, so there's no monthly subscription.
|
||||
runs on a small AWS Lightsail server for a few dollars a month, covered by the church's AWS
|
||||
credits for now.
|
||||
|
||||
It's one Node server (Express + SQLite) and a front end with no build step. It runs on desktop
|
||||
browsers and on phones, and a phone can install it to the home screen like an app.
|
||||
@@ -48,14 +49,13 @@ Data goes to `server/data/` (`boards.db`, `uploads/`, `backups/`). The folder is
|
||||
|
||||
## Set up Google sign-in (once)
|
||||
|
||||
Google only allows sign-in from **https** addresses (or `localhost`), so the app needs a
|
||||
hostname behind the NAS reverse proxy, for example `https://boards.watersmedia.org`, set up the
|
||||
same way as `check.watersmedia.org`.
|
||||
Google only allows sign-in from **https** addresses (or `localhost`), so the app lives at
|
||||
**`https://boards.watersmedia.org`**, behind Caddy on the AWS box (see *Deploy to AWS* below).
|
||||
|
||||
1. Go to <https://console.cloud.google.com/> and sign in with the church Google Workspace admin account.
|
||||
2. Create a project (e.g. "Waters Boards").
|
||||
3. **APIs & Services → OAuth consent screen**: choose **Internal**, so only
|
||||
`@waterschurch.org` accounts can ever use it. Fill in the app name and support email, then save.
|
||||
3. **APIs & Services → OAuth consent screen**: choose **Internal**, so only accounts in the
|
||||
church's Google Workspace can ever use it. Fill in the app name and support email, then save.
|
||||
4. **APIs & Services → Credentials → Create credentials → OAuth client ID**
|
||||
- Application type: **Web application**
|
||||
- Authorized JavaScript origins: `https://boards.watersmedia.org` (and `http://localhost:3100` for local testing)
|
||||
@@ -70,32 +70,95 @@ Google sign-in is ever misconfigured.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to the NAS
|
||||
## Deploy to AWS (Lightsail)
|
||||
|
||||
This follows the same pattern as the checklist app: Docker on the NAS, and Gitea Actions
|
||||
redeploys on every push to `main` that touches `server/`.
|
||||
Waters Boards runs on one AWS Lightsail server. Docker runs two containers there: the app, and
|
||||
Caddy in front of it. Caddy gets and renews the Let's Encrypt certificate itself, so TLS ends at
|
||||
Caddy and the app speaks plain HTTP on the private Docker network. Only ports 80 and 443 are
|
||||
public.
|
||||
|
||||
**One-time setup on the NAS** (`10.1.1.5`):
|
||||
**The box:** Ubuntu 24.04, 2 GB RAM, `us-east-1`, a static IPv4 address, Docker Engine with the
|
||||
compose plugin. Lightsail snapshots the disk every day at 07:00 UTC.
|
||||
|
||||
```bash
|
||||
mkdir -p /volume2/docker/waters-boards
|
||||
cp server/.env.example /volume2/docker/waters-boards/.env # then fill it in
|
||||
**Folder on the box** (owned by `ubuntu`):
|
||||
|
||||
```
|
||||
/opt/waters-boards/
|
||||
.env settings and secrets. Made by hand once, never in git
|
||||
data/ database, uploads, nightly backups
|
||||
Caddyfile copied from deploy/aws/
|
||||
docker-compose.yml copied from deploy/aws/
|
||||
server/ the app source, copied from this repo's server/
|
||||
```
|
||||
|
||||
1. In the act_runner `config.yaml` on the NAS, add `/volume2/docker/waters-boards` to
|
||||
`container.valid_volumes`, then restart the runner. The runner refuses host mounts that
|
||||
aren't listed there.
|
||||
2. Add a reverse-proxy rule: `https://boards.watersmedia.org` → `http://localhost:3100`.
|
||||
Allow WebSocket/streaming headers, because the live updates use a long-lived HTTP response.
|
||||
3. In the Gitea repo, set **Settings → Actions → Variables → `DEPLOY_ENABLED` = `true`**. Until it's
|
||||
set, the deploy job is skipped, so pushes made before the NAS was ready don't show as failures.
|
||||
4. Push to `main`, or run the workflow by hand from the Gitea Actions tab.
|
||||
**One-time setup**
|
||||
|
||||
The workflow (`.gitea/workflows/deploy.yml`) never writes `data/` or `.env`. It rebuilds the
|
||||
container in place without taking it down first, and fails loudly if `.env` is missing.
|
||||
1. **DNS.** `watersmedia.org` is served by the church's own nameservers (`ns1` and
|
||||
`ns2.waterschurch.org`), so there's no registrar panel to use. The zone is *not* in the
|
||||
`watersch` cPanel account; it belongs to whichever cPanel/WHM account owns `watersmedia.org`
|
||||
(its SOA contact is `nick@waterschurch.org`). In that account's **Zone Editor**, add an `A`
|
||||
record `boards` → the box's static IP, TTL 300. Caddy can't get a certificate until that
|
||||
record resolves, and ports 80 and 443 must be open in the Lightsail firewall.
|
||||
2. **`.env`.** Copy `server/.env.example` to `/opt/waters-boards/.env` and fill it in. The deploy
|
||||
script refuses to run without it, so do this from your laptop before the first deploy:
|
||||
|
||||
**Manual deploy**, without Gitea: copy `server/` (minus `data/`, `.env` and `node_modules/`) to the
|
||||
NAS folder, then run `docker compose up -d --build` there.
|
||||
```bash
|
||||
scp server/.env.example boards-aws:/opt/waters-boards/.env
|
||||
ssh boards-aws nano /opt/waters-boards/.env
|
||||
```
|
||||
|
||||
Set `ADMIN_EMAILS` and `ADMIN_PASSWORD`. `ADMIN_PASSWORD` is the break-glass login until
|
||||
Google sign-in is configured. Add `GOOGLE_CLIENT_ID` once you have it (see above).
|
||||
3. **First deploy**, as below. When it finishes, <https://boards.watersmedia.org> should load.
|
||||
|
||||
**Deploy from a laptop.** Needs the `boards-aws` SSH alias (user `ubuntu`) in `~/.ssh/config`.
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
deploy/aws/deploy.sh
|
||||
```
|
||||
|
||||
It checks the server code for syntax errors, confirms `.env` exists on the box, copies `server/`,
|
||||
`docker-compose.yml` and `Caddyfile` over, rebuilds the containers in place, waits for the
|
||||
healthcheck, and prints what `https://boards.watersmedia.org/healthz` returns. Set `BOARDS_HOST`
|
||||
to deploy to a host other than `boards-aws`.
|
||||
|
||||
**Deploy from Gitea Actions.** The Gitea server is only reachable from inside the church network,
|
||||
so AWS can't pull from it. Instead the `nas` runner, which is inside the network and can reach
|
||||
the internet, runs the same `deploy.sh` and pushes to the box over SSH. The workflow
|
||||
(`.gitea/workflows/deploy.yml`) runs on every push to `main` that touches `server/` or
|
||||
`deploy/aws/`, or by hand from the Gitea Actions tab. One-time setup:
|
||||
|
||||
1. Make a deploy-only SSH key. Add its public half to `/home/ubuntu/.ssh/authorized_keys` on
|
||||
the box.
|
||||
2. In the Gitea repo, **Settings → Actions → Secrets**, add:
|
||||
- `DEPLOY_SSH_KEY`: the private key.
|
||||
- `DEPLOY_KNOWN_HOSTS`: the output of `ssh-keyscan -t ed25519 <static IP>`.
|
||||
3. In **Settings → Actions → Variables**, add `DEPLOY_HOST` (the static IP) and
|
||||
`DEPLOY_ENABLED` = `true`. Until `DEPLOY_ENABLED` is `true`, the deploy job is skipped, so
|
||||
pushes made before the box was ready don't show as failures.
|
||||
4. The `nas` runner must be registered where it can see this repo (user- or instance-level, not
|
||||
only on the checklist repo).
|
||||
|
||||
**What a deploy never touches:** `data/` and `.env`. It deletes nothing on the box. It rebuilds
|
||||
without taking the running container down first, so a failed build leaves the old version
|
||||
serving.
|
||||
|
||||
**Restore**
|
||||
|
||||
- *From a Lightsail snapshot* (the whole box): in the Lightsail console, create a new instance
|
||||
from the latest snapshot, then move the static IP to it. The folder, `.env`, data and SSH host
|
||||
key all come back as they were, so nothing else changes.
|
||||
- *From `data/backups/`* (the database only): `data/` is owned by root, hence `sudo`.
|
||||
|
||||
```bash
|
||||
ssh boards-aws
|
||||
cd /opt/waters-boards
|
||||
docker compose stop boards
|
||||
sudo rm -f data/boards.db-wal data/boards.db-shm
|
||||
sudo cp data/backups/boards-YYYY-MM-DD.db data/boards.db
|
||||
docker compose start boards
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -128,9 +191,11 @@ Inbox, Search). Pickers open as bottom sheets.
|
||||
## Backups
|
||||
|
||||
- Every night after 2am the app writes `data/backups/boards-YYYY-MM-DD.db` and keeps 14.
|
||||
- For off-site copies, back up the whole `data/` folder (database + `uploads/`) the same way
|
||||
the checklist data is backed up.
|
||||
- To restore, stop the container, copy a snapshot over `data/boards.db`, and start it again.
|
||||
- Lightsail takes an automatic snapshot of the whole disk every day and keeps 7. That covers
|
||||
`data/` (database + `uploads/`), `.env` and everything else on the box.
|
||||
- To restore a database snapshot, follow *Restore* under *Deploy to AWS* above. Don't just copy
|
||||
the file over `boards.db`: the database runs in WAL mode, and a stale `boards.db-wal` beside a
|
||||
restored file corrupts it.
|
||||
|
||||
---
|
||||
|
||||
@@ -155,4 +220,8 @@ server/
|
||||
js/item.js Item panel: updates, info, files, activity
|
||||
js/kanban.js · calendar.js · timeline.js · chart.js
|
||||
js/pages.js Home, My work, Inbox, Search, Team, Admin
|
||||
deploy/aws/
|
||||
docker-compose.yml The app and Caddy containers, as run on the Lightsail box
|
||||
Caddyfile Caddy config: HTTPS for boards.watersmedia.org, proxy to the app
|
||||
deploy.sh Deploys from a laptop or Gitea: check, copy, rebuild, wait for healthy
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user