bumping version and including nbconvert

2026-07-13 11:58:39 +01:00
parent 1edc9b8606
commit e20d31955c
3 changed files with 90 additions and 2 deletions
@@ -38,4 +38,77 @@ sudo usermod -aG docker $USER
 - `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/`
+- `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.