jms-gitea

# 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:
```
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):

# 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:

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):

# 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):

# 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:

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):

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):

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):

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.

README.md Unescape Escape

OVHCloud VPS deploy

Rendering: Mermaid + Jupyter notebooks

Version upgrades

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

README.md