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:

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

  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.