jms-gitea/README.md

### OVHCloud VPS deploy
VPS name: vps-123c23bd.vps.ovh.net
IPv4 address: 51.91.109.47
IPv6 address: 2001:41d0:42b:61::1
Username: ubuntu
Password: <PASSWORD>

- `ssh ubuntu@vps-123c23bd.vps.ovh.net`
```
# 1. Update the system repository
sudo apt update && sudo apt upgrade -y

# 2. Grab the required security certificates and curl
sudo apt install ca-certificates curl -y
sudo install -m 0755 -d /etc/apt/keyrings

# 3. Download Docker's official GPG keying for package verification
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 4. Inject Docker's official repository into your system's source list
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. Update your system packages using the new official source
sudo apt update

# 6. Install the official Docker Engine and modern Compose Plugin
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Give your 'ubuntu' user permission to use Docker without typing 'sudo' every time
sudo usermod -aG docker $USER
```

- `mkdir -p ~/gitea`
- `cd ~/gitea`
- `docker compose up -d`
- `docker compose logs`
- `scp -r /Users/jamestwose/Coding/jms-gitea/gcloud-version/gitea-dump/* ubuntu@vps-123c23bd.vps.ovh.net:~/gitea/gitea_data/`

### Rendering: Mermaid + Jupyter notebooks

- **Mermaid** renders out of the box in any `.md` / issue / wiki — just use a fenced block:
  ```mermaid
  flowchart LR
      A[Notebook] --> B(Gitea) --> C[Rendered]
  ```
  No config needed (on by default, `markup.MERMAID_MAX_SOURCE_CHARACTERS = 50000`).

- **Jupyter** (`.ipynb`) renders via an external `nbconvert` renderer, built into the
  custom image (`Dockerfile` extends `gitea/gitea:1.26.4`) and configured through env
  vars in `docker-compose.yml` (`GITEA__markup.jupyter__*`). The env vars are merged
  into the existing `app.ini` on container start — they do **not** overwrite the
  instance's secrets/INTERNAL_TOKEN.

### Version upgrades

Gitea is pinned via the `FROM` line in `Dockerfile` (and the `image:` tag in
`docker-compose.yml`). Bumping versions is a two-file change, then a rebuild.

**Pre-flight** — check the target version is a stable release (not `-rc`):
- Latest stable list: https://github.com/go-gitea/gitea/releases (look for the non-“Pre-release” tag)
- Skim the release notes for BREAKING / SECURITY entries that affect this setup
  (SQLite, reverse-proxy/Caddy, no Actions/packages/OAuth in use here).

**1. Bump the version in the repo** (on your Mac):
```bash
# edit Dockerfile:  FROM gitea/gitea:<NEW_VERSION>
# edit docker-compose.yml:  image: gitea-jms:<NEW_VERSION>   (the build tag, cosmetic)
```

**2. Ship the two files to the VPS:**
```bash
scp Dockerfile docker-compose.yml ubuntu@vps-123c23bd.vps.ovh.net:~/gitea/
```

**3. On the VPS, from `~/gitea`** (where `docker-compose.yml`, `Dockerfile`, `gitea_data/` live):
```bash
# 0. Back up the SQLite DB first — every version bump runs DB migrations
#    db path = /data/gitea.db, bind-mounted to ./gitea_data/gitea.db
sudo cp -a gitea_data/gitea.db gitea_data/gitea.db.bak.$(date +%F)

# 1. Rebuild the custom image (nbconvert baked in) and recreate just the server
#    --build forces a fresh image; Caddy is unchanged so it stays up
sudo docker compose up -d --build
sudo docker compose logs -f server
```

**4. Sanity check** in the web UI: push a test commit, open a `.ipynb`, view a
` ```mermaid ` block. Watch `sudo docker compose logs server` for migration output
or nbconvert/CSP errors.

**Rollback** (if the new version misbehaves):
```bash
# restore the previous DB, then revert the two files and rebuild
sudo cp -a gitea_data/gitea.db.bak.<DATE> gitea_data/gitea.db
# (re-edit Dockerfile / docker-compose.yml back to the old version, scp them over)
sudo docker compose up -d --build
```
Note: restoring an older DB onto a newer Gitea binary is not supported — always
restore the DB backup that matches the version you’re rolling back to.

**Gotchas**
- `docker compose down` is unnecessary — `up -d --build` recreates only the `server`
  container; Caddy keeps serving.
- Config is delivered via env vars (`GITEA__*`), which the Docker entrypoint *merges*
  into the existing `app.ini` on start. Your `SECRET_KEY` / `INTERNAL_TOKEN` / DB are
  not touched, so upgrades never log you out or re-trigger the installer.
- The Mermaid size cap (`GITEA__markup__MERMAID_MAX_SOURCE_CHARACTERS=50000`) and the
  Jupyter renderer env vars carry forward unchanged across versions.
- Major Gitea versions occasionally change bundled git requirements; the official
  image ships its own git, so host git version is irrelevant here.

### Actions runner, CORS & OAuth (for the ever-near site)

The `ever-near` site uses Sveltia CMS backed by this Gitea instance. That needs three
things Gitea didn't have before: **Actions** (to build + deploy on push), **CORS**
(so the CMS in the browser can call the Gitea API), and an **OAuth2 app** (so editors
sign in with PKCE instead of a personal token). `docker-compose.yml` now enables the
first two via env vars and adds a `runner` service behind a `runner` profile.

**1. Ship the updated compose file and runner config to the VPS:**
```bash
scp docker-compose.yml runner_config.yaml ubuntu@vps-123c23bd.vps.ovh.net:~/gitea/
```

**2. Rebuild the server.** The compose network is now pinned to the literal name `gitea`
(so job containers can join it — see `runner_config.yaml`), which is a one-time network
change, so do a clean `down`/`up` (~10s downtime; Caddy restarts too):
```bash
cd ~/gitea
sudo docker compose down
sudo docker compose up -d --build
sudo docker compose logs -f server   # watch for actions/cors config lines on boot
```

**3. Enable Actions on the repo** (one-off, in the web UI):
`gitea.jms.rocks/jameshtwose/ever-near` → Settings → Actions → Enable Actions.

**4. Get a runner registration token** (pick one):
- Web UI: Site Administration → Actions → Runners → copy the **Registration token**.
- Or CLI: `sudo docker exec gitea_server gitea --config /data/gitea/conf/app.ini actions generate-runner-token`

**5. Put the token in `~/gitea/.env`** (gitignored, never committed):
```bash
printf 'GITEA_RUNNER_REGISTRATION_TOKEN=%s\n' '<TOKEN>' >> ~/gitea/.env
```

**6. Start the runner** (separate profile so it only runs once the token is set):
```bash
sudo docker compose --profile runner up -d runner
sudo docker compose logs -f runner   # should log "Runner registered successfully"
```
The first workflow run pulls the job image `docker.gitea.com/runner-images:ubuntu-latest`
(Node, git, Docker CLI) — give it a minute. `runner_config.yaml` attaches each job
container to the `gitea` network so `actions/checkout` can resolve `server:3000`.

**7. Register the OAuth2 app for Sveltia CMS** (web UI, no server restart):
- Site Administration → OAuth2 Applications → **Add a new OAuth2 application**.
- Application name: `ever-near CMS`
- Redirect URI: `https://ever-near.web.app/admin/index.html`
- **Uncheck "Confidential client"** (PKCE needs a public client).
- Copy the **Client ID** into `ever-near/public/admin/config.yml` as `app_id`, commit,
  and push — the Gitea Action rebuilds + redeploys the site with it.

**Gotchas**
- **Job containers must join the `gitea` network** or `actions/checkout` fails with
  `Could not resolve host: server`. That's what `runner_config.yaml`
  (`container.network: gitea`) does — don't remove it. The compose network is pinned to
  the literal name `gitea` via `networks.gitea.name` so the config matches regardless of
  the compose project name.
- `uses: actions/checkout@v4` / `actions/setup-node@v4` resolve through Gitea's default
  actions mirror (`gitea.com/actions/*`). If a job can't find an action, set
  `GITEA__actions__DEFAULT_ACTIONS_URL=https://gitea.com` (already the default) or
  reference the action fully: `uses: https://gitea.com/actions/checkout@v4`.
- CORS is scoped to `ever-near.web.app` only. Add more origins to
  `GITEA__cors__ALLOW_DOMAINS` (comma-separated) if you connect a custom domain later.
- The runner is behind the `runner` profile; a plain `docker compose up -d` won't start
  it. Use `docker compose --profile runner up -d runner`.