diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..be335a3
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,4 @@
+FROM gitea/gitea:1.26.4
+# ponytail: nbconvert only (not full jupyter) — enough for the .ipynb external renderer
+RUN apk --no-cache add python3 py3-pip && \
+    pip3 install --break-system-packages --no-cache-dir nbconvert
\ No newline at end of file
diff --git a/README.md b/README.md
index 4d729b2..421dec7 100644
--- a/README.md
+++ b/README.md
@@ -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/`
\ No newline at end of file
+- `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.
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
index 797e025..3257454 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,7 +5,10 @@ networks:
 services:
   # 1. Gitea Core Engine (SQLite Variant)
   server:
-    image: gitea/gitea:1.22
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: gitea-jms:1.26.4
     container_name: gitea_server
     restart: always
     networks:
@@ -17,6 +20,8 @@ services:
     environment:
       - USER_UID=1000
       - USER_GID=1000
+      # Mermaid diagram size cap (older Gitea defaults to 5000; raise to modern default)
+      - GITEA__markup__MERMAID_MAX_SOURCE_CHARACTERS=50000
       # Force Gitea to lock right onto your imported database file
       - GITEA__database__DB_TYPE=sqlite3
       - GITEA__database__PATH=/data/gitea.db
@@ -25,6 +30,12 @@ services:
       - GITEA__server__ROOT_URL=https://gitea.jms.rocks/
       - GITEA__server__HTTP_PORT=3000
       - GITEA__server__SSH_PORT=2222
+      # External renderer: Jupyter notebooks (.ipynb) via nbconvert
+      - GITEA__markup.jupyter__ENABLED=true
+      - GITEA__markup.jupyter__FILE_EXTENSIONS=.ipynb
+      - GITEA__markup.jupyter__RENDER_COMMAND=jupyter-nbconvert --stdin --stdout --to html --template basic
+      - GITEA__markup.jupyter__IS_INPUT_FILE=false
+      - GITEA__markup.sanitizer.jupyter.img__ALLOW_DATA_URI_IMAGES=true
     ports:
       - "127.0.0.1:3000:3000"
       - "2222:22"