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