Can I self-host Whimsical?

308 lines · 14,484 bytes

You are Claude Code on the user's machine. The user has completed Prompt Zero: `ssh vps` works,
Docker and Caddy are installed, the firewall is default-deny.

Run every command in this prompt on the server over `ssh vps` unless the step says otherwise.

Install draw.io 31.1.8 on that server, reachable at https://<DOMAIN>, behind the existing
Caddy with automatic TLS.

## 1. Preflight

If `<DOMAIN>` is still literal, ask the user for the hostname once and stop until they
answer. The A record for it must already point at this server.

Say this to the user before anything installs, because it is the reason to stop and think
rather than the reason to keep going. draw.io already runs a hosted editor at
https://app.diagrams.net that costs nothing and asks for no account: their own home page
says "No account required. No credit card." What this install buys is not the editor, it
is where the editor comes from. The page loads from a hostname the user controls, on a
machine they control, with no third-party origin serving the code, which is what an
offline network, an air-gapped site or a written company policy actually needs. If none of
those three describe the user, tell them plainly that the free hosted editor does the same
job and let them decide before step 2.

draw.io needs 1024 MB of RAM available and 5 GB free on /srv. It is a Tomcat on a JVM, and
the image publishes amd64 and arm64. Measure all four first:

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
```

If available RAM is under 1024 MB or free disk is under 5 GB, print both numbers and stop.
Do not install and hope. If `dig +short` prints nothing the A record does not exist yet, so
print that and stop: Caddy cannot get a certificate for a hostname that does not resolve.

## 2. Layout

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/drawio /srv/drawio/backups
ls -la /srv/drawio
```

Assert: `ls -la` shows `backups` owned by the login user. There is no `data` directory and
there is nothing to create one for. The container writes no diagram anywhere on this
server, so the only files under /srv/drawio are the two this prompt writes and the archive
step 8 makes of them.

## 3. Secrets

One secret, and it is not a login. draw.io has no accounts, so there is nothing to sign in
to and no admin page to protect. What this generates is `KEYSTORE_PASS`: the image builds a
self-signed certificate for its own port 8443 at every start, and when that variable is
unset it uses a password printed in its own public documentation. Port 8443 is never
published by this install, so nobody outside the container can reach that certificate, and
a documented default is still a documented default. Generate the value, do not print it, do
not repeat it in your summary, and do not put it in any log line.

```bash
umask 077
cat > /srv/drawio/.env <<EOF
DRAWIO_SERVER_URL=https://<DOMAIN>/
KEYSTORE_PASS=$(openssl rand -hex 32)
EOF
chmod 600 /srv/drawio/.env
umask 022
ls -l /srv/drawio/.env
```

Assert: the file exists with mode `-rw-------`. `DRAWIO_SERVER_URL` is upstream's variable
for the public deployment URL and it wants the trailing slash, which is why the line ends
in one. Tell the user this file holds no credential they will ever be asked to type.

## 4. compose.yml

```bash
cat > /srv/drawio/compose.yml <<'EOF'
# draw.io · the deterministic fallback. Authored by caniselfhostit from the
# upstream documentation, not copied from a repository:
#   image, ports, env vars .. https://github.com/jgraph/docker-drawio/blob/v31.1.8/README.md
#   entrypoint behaviour .... https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/docker-entrypoint.sh
#   image build ............. https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/Dockerfile
#
# One container: Tomcat 9 on JDK 11 serving the compiled draw.io editor at the
# root path on container port 8080, as a non-root tomcat user. There is no
# database and no account system, and this file mounts no volume, because the
# server holds no diagram. A diagram is written to the reader's own device or
# into the storage of the browser that drew it.
#
# The entrypoint switches every cloud backend off when its credentials are
# absent: with no DRAWIO_GOOGLE_CLIENT_ID, DRAWIO_MSGRAPH_CLIENT_ID or
# DRAWIO_GITLAB_ID it writes gapi, od and gl to 0, and it always writes db, gh
# and tr to 0. This file sets none of them, so none of them are on.
#
# KEYSTORE_PASS arrives from /srv/drawio/.env. Left alone, the image falls back
# to a keystore password printed in its own documentation and puts it on a
# self-signed certificate it regenerates at every start. Container port 8443 is
# never published here, so nothing outside can reach that certificate; the
# generated value is what keeps a documented default from standing behind it.
#
# Tag and digest read from Docker Hub on 2026-08-06; the manifest list covers
# linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  drawio:
    image: jgraph/drawio:31.1.8@sha256:0c8910ea14dfbccb17c784ee17d995317a8d753479f5ec0f21b2ab2213153100
    container_name: drawio
    restart: unless-stopped
    env_file: /srv/drawio/.env
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/ >/dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8158.
      - "127.0.0.1:8158:8080"
EOF
cd /srv/drawio && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. The container serves on 8080 inside itself and 8158 on
this host is bound to 127.0.0.1, so Caddy is the only route in.

## 5. Caddy and TLS

Append the site block below to the Caddyfile Prompt Zero installed, with `<DOMAIN>`
replaced by the real hostname. Copy the file first, because a syntax error here takes down
every other site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-drawio
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# draw.io · the Caddy site block for this service.
#
# Authored by caniselfhostit from https://caddyserver.com/docs/automatic-https
# and https://github.com/jgraph/docker-drawio/blob/v31.1.8/README.md
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed,
# with <DOMAIN> replaced by the hostname whose A record already points at this
# box. Caddy asks for the certificate on the first request and renews it on its
# own, so there is nothing to schedule. The container builds a self-signed
# certificate for its own port 8443 at every start; that port is not published,
# and Caddy is the only thing terminating TLS in front of this service.

<DOMAIN> {
	# The editor is several megabytes of JavaScript on a cold load, so
	# compression is the one setting here that changes what the user feels.
	encode zstd gzip

	# No Content-Security-Policy line on purpose. The container injects its own
	# CSP as a meta tag at start-up and a second policy sent as a header would
	# intersect with it, which fails as a blank editor rather than as an error.
	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8158 is the loopback port compose publishes on this host. It is not a
	# container port and it is not open in the firewall.
	reverse_proxy 127.0.0.1:8158
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Assert: `caddy validate` exits 0 and the reload exits 0. If validate fails, restore
/etc/caddy/Caddyfile.before-drawio, reload, and report what it objected to. Caddy requests
the certificate on the first request to the hostname and renews it without a cron job.

## 6. Firewall

Two ports open, both of them Caddy's, and neither 8158 nor 8443 is one of them. These
commands are idempotent, so on a box Prompt Zero already configured they change nothing:

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

80/tcp redirects to HTTPS and answers the ACME challenge, 443/tcp is the only way in, and
443/udp is HTTP/3, which Caddy offers by default. 8158 stays closed because it is bound to
127.0.0.1, and 8443 stays closed because compose never publishes it: the container's own
TLS port has no host port a rule could apply to. Assert: `ufw status verbose` prints
`Status: active`, shows 80, 443/tcp and 443/udp, and shows no rule for 8158 or 8443.

## 7. Start and verify

Tomcat rewrites the editor's configuration files from the environment at every start, so
the first boot is slower than the ones after it.

```bash
cd /srv/drawio
docker compose pull
docker compose up -d
for i in $(seq 1 20); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/); echo "$i $code"; [ "$code" = 200 ] && break; sleep 10; done
curl -sS https://<DOMAIN>/ | grep -c 'Flowchart Maker'
curl -sS https://<DOMAIN>/js/PreConfig.js | grep -cF "urlParams['gapi'] = '0'"
curl -sS https://<DOMAIN>/js/PreConfig.js | grep -cF "window.DRAWIO_SERVER_URL = 'https://<DOMAIN>/'"
```

Assert, all four, and print what you received for each. The loop ends printing `200`. The
second command prints `1`, because `Flowchart Maker` is in the title of the served
document. The third prints `1`, which is the security assert in this block: it proves the
container wrote `gapi` off, so the Google Drive backend is not offered to anyone who loads
this page. The fourth prints `1`, which proves the `.env` from step 3 reached the
container. If any of the four misses, stop, run `docker compose logs --tail 40 drawio`, and
say which earlier step is the likely cause: a `404` on PreConfig.js means the entrypoint
could not write into the webapp, and a first curl that never reaches `200` is usually DNS,
because a hostname whose A record was created minutes ago makes Caddy's first certificate
attempt fail and retry quietly. A running container is not success. Four asserts passing is
success.

The first screen at https://<DOMAIN>/?offline=1 is a dialog headed `Save diagrams to:` with
two buttons, `Device` and `Browser`, and a `Decide Later` link under them. There is no login
form and no sign-up link, because there are no accounts.

STOP: tell the user to open https://<DOMAIN>/?offline=1, confirm that dialog shows `Device`
and `Browser` and no Google Drive, OneDrive or GitHub button, and wait.
Do not continue until they confirm. No command can make that check for them, and it is the
difference between an editor that keeps their work on their own hardware and one that
offers to post it somewhere else.

## 8. First backup and restore

There is no database to dump and no data directory to archive, and saying so is more useful
than inventing one. The backup here is the configuration that rebuilds the service:

```bash
cd /srv/drawio
sudo tar -czf /srv/drawio/backups/drawio-config-$(date +%F).tar.gz -C /srv/drawio compose.yml .env -C /etc/caddy Caddyfile
ls -lh /srv/drawio/backups/
```

Assert: the archive exists and is non-empty. Print its size. Nothing is stopped, because
there is no write to catch halfway. A backup on the same disk is not a backup, so run this
one from the user's machine, not the server:

```bash
mkdir -p ~/backups/drawio
scp vps:/srv/drawio/backups/*.tar.gz ~/backups/drawio/
```

The diagrams are the other half, and no command on this server can reach them.

STOP: tell the user to open https://<DOMAIN>/?offline=1, draw one shape, and use File then
Save As to write the `.drawio` file somewhere on their own computer, and wait.
Do not continue until they confirm they have that file. Explain why: if they picked
`Browser` in that dialog the diagram is in one browser's local storage on one machine, and
no backup taken on this server would ever have contained it.

To restore the server: untar the archive into /srv/drawio, append the Caddy block from step
5 again, and run `docker compose up -d`. To restore a diagram, open the editor and use File
then Open to load the saved file. Tell the user that is two disaster plans, that the second
one holds the work, and that saving to their own disk is a habit rather than a step they
did once today.

## 9. Updating later

New versions are listed at https://github.com/jgraph/drawio/releases, and the Docker tag is
the release tag without its leading `v`. Take a backup first, then edit the image line in
/srv/drawio/compose.yml to the new tag and its digest:

```bash
cd /srv/drawio
docker compose pull
docker compose up -d
docker compose logs --tail 30 drawio
```

Then re-run all four asserts from step 7 before calling the update done. Nothing is
migrated in an upgrade here, because the container carries no state between versions.

## 10. What will probably go wrong

The first dialog. I clicked `Browser` because it sounded like the thing running on the
server, drew a diagram, and came back the next morning on a different laptop to an empty
canvas at the same hostname. Nothing was broken. `Browser` means that browser's local
storage on that machine, `Device` means a file on the computer in front of you, and neither
of them is the server. I spent several minutes reading Tomcat logs looking for a database
that has never existed. If the user reports a diagram has vanished, ask which browser and
machine they drew it on before you read a log line.

## 11. Out of scope

- Do not install the export server or set `DRAWIO_SELF_CONTAINED` or `EXPORT_URL`. That is
  a second container carrying its own headless Chromium, and this prompt installs one
  service. PNG and SVG export from the browser works without it.
- Do not set `DRAWIO_GOOGLE_CLIENT_ID`, `DRAWIO_MSGRAPH_CLIENT_ID` or `DRAWIO_GITLAB_ID`.
  Each one is an OAuth application registered with somebody else, and step 7 asserts that
  those backends are off.
- Do not set `ENABLE_DRAWIO_PROXY=1`. It opens a `/proxy` endpoint that fetches arbitrary
  external URLs on this server's behalf, which is a request forwarder pointed at the user's
  own network.
- Do not publish container port 8443 and do not set `LETS_ENCRYPT_ENABLED`. Caddy holds the
  certificate for this hostname, and a second one inside the container would be a second
  thing to renew.

This path is slower: you paste every command yourself, and there is nobody watching the
output but you. If you can run Claude Code, use the other tab.

You are installing draw.io 31.1.8 on a VPS where Prompt Zero is done: `ssh vps` works,
Docker and Caddy are installed, the firewall is default-deny. Run everything over `ssh vps`
unless a step says otherwise, and replace `<DOMAIN>` with the hostname whose A record
already points at the box.

Read this before step 1, because it is the reason to stop and think rather than the reason
to keep going. draw.io already runs a hosted editor at https://app.diagrams.net that costs
nothing and asks for no account: their own home page says "No account required. No credit
card." This install gives you the same editor. What it changes is where the page comes
from: it loads from a hostname you control, on a machine you control, and no third-party
origin ever serves the code. That is what an offline network, an air-gapped site or a
written company policy needs. If none of those three describe you, the free hosted editor
does this job and you can close this tab with nothing lost.

## 1. Preflight

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
```

You should see: at least `1024` MB available, at least `5` G free, `amd64` or `arm64`, and
your server's IP on the last line.

If you do not: an empty last line means the A record does not exist yet. Add it, wait a
minute, and run `dig +short <DOMAIN>` again. Caddy cannot get a certificate for a hostname
that does not resolve, and failed attempts count against a rate limit you cannot see. The
RAM floor is 1024 MB because this is a Tomcat on a JVM rather than a static file server; on
a 512 MB box the container starts and then dies during the first page load, which reads as
a broken install rather than as a memory problem.

## 2. Layout

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/drawio /srv/drawio/backups
ls -la /srv/drawio
```

You should see: `backups`, owned by you.

If you do not: there is no `data` directory in that command and that is deliberate. The
container writes no diagram anywhere on this server, so the only files that will ever live
under /srv/drawio are the two the next steps write and the archive step 8 makes of them.

## 3. Secrets

One secret, and it is not a login. draw.io has no accounts, so there is nothing to sign in
to and no admin page to protect. What this generates is `KEYSTORE_PASS`: the image builds a
self-signed certificate for its own container port 8443 at every start, and when that
variable is unset it uses a password printed in its own public documentation. Port 8443 is
never published by this install, so nobody outside the container can reach that
certificate, and a documented default is still a documented default.

```bash
umask 077
cat > /srv/drawio/.env <<EOF
DRAWIO_SERVER_URL=https://<DOMAIN>/
KEYSTORE_PASS=$(openssl rand -hex 32)
EOF
chmod 600 /srv/drawio/.env
umask 022
ls -l /srv/drawio/.env
```

You should see: mode `-rw-------`, your own username twice, and the path. Replace `<DOMAIN>`
on the first line with your real hostname before you paste, and keep the trailing slash:
`DRAWIO_SERVER_URL` is upstream's variable for the public deployment URL and it wants one.

If you do not: a mode of `-rw-r--r--` means `umask 077` did not take effect, which happens
if you pasted the lines separately in different shells. Run `chmod 600 /srv/drawio/.env` and
carry on. If the file already existed from an earlier attempt this block has overwritten
it, which costs nothing here, because the container regenerates its certificate at every
start anyway.

Do not paste that file, the generated value, or any command output containing it into this
chat window. Nothing in this install will ever ask you to type it back, so there is no
reason it should leave the server.

## 4. compose.yml

Paste the whole block at once, including the last two lines.

```bash
cat > /srv/drawio/compose.yml <<'EOF'
# draw.io · the deterministic fallback. Authored by caniselfhostit from the
# upstream documentation, not copied from a repository:
#   image, ports, env vars .. https://github.com/jgraph/docker-drawio/blob/v31.1.8/README.md
#   entrypoint behaviour .... https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/docker-entrypoint.sh
#   image build ............. https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/Dockerfile
#
# One container: Tomcat 9 on JDK 11 serving the compiled draw.io editor at the
# root path on container port 8080, as a non-root tomcat user. There is no
# database and no account system, and this file mounts no volume, because the
# server holds no diagram. A diagram is written to the reader's own device or
# into the storage of the browser that drew it.
#
# The entrypoint switches every cloud backend off when its credentials are
# absent: with no DRAWIO_GOOGLE_CLIENT_ID, DRAWIO_MSGRAPH_CLIENT_ID or
# DRAWIO_GITLAB_ID it writes gapi, od and gl to 0, and it always writes db, gh
# and tr to 0. This file sets none of them, so none of them are on.
#
# KEYSTORE_PASS arrives from /srv/drawio/.env. Left alone, the image falls back
# to a keystore password printed in its own documentation and puts it on a
# self-signed certificate it regenerates at every start. Container port 8443 is
# never published here, so nothing outside can reach that certificate; the
# generated value is what keeps a documented default from standing behind it.
#
# Tag and digest read from Docker Hub on 2026-08-06; the manifest list covers
# linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  drawio:
    image: jgraph/drawio:31.1.8@sha256:0c8910ea14dfbccb17c784ee17d995317a8d753479f5ec0f21b2ab2213153100
    container_name: drawio
    restart: unless-stopped
    env_file: /srv/drawio/.env
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/ >/dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8158.
      - "127.0.0.1:8158:8080"
EOF
cd /srv/drawio && docker compose config >/dev/null && echo "compose OK"
```

You should see: `compose OK` and nothing else.

If you do not: `env file /srv/drawio/.env not found` means step 3 did not write the file.
`services must be a mapping` means the indentation was lost between the page and your
terminal, so run `rm /srv/drawio/compose.yml` and paste again in one go. There is no
`volumes:` key in that file and nothing is missing: the container has nowhere to put a
document, which is the single most important fact about this install.

## 5. Caddy and TLS

This appends one site block to the Caddy config Prompt Zero installed. Replace `<DOMAIN>` in
the block with your hostname before you paste. The first line takes a copy, because a
syntax error here takes down every other site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-drawio
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# draw.io · the Caddy site block for this service.
#
# Authored by caniselfhostit from https://caddyserver.com/docs/automatic-https
# and https://github.com/jgraph/docker-drawio/blob/v31.1.8/README.md
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed,
# with <DOMAIN> replaced by the hostname whose A record already points at this
# box. Caddy asks for the certificate on the first request and renews it on its
# own, so there is nothing to schedule. The container builds a self-signed
# certificate for its own port 8443 at every start; that port is not published,
# and Caddy is the only thing terminating TLS in front of this service.

<DOMAIN> {
	# The editor is several megabytes of JavaScript on a cold load, so
	# compression is the one setting here that changes what the user feels.
	encode zstd gzip

	# No Content-Security-Policy line on purpose. The container injects its own
	# CSP as a meta tag at start-up and a second policy sent as a header would
	# intersect with it, which fails as a blank editor rather than as an error.
	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8158 is the loopback port compose publishes on this host. It is not a
	# container port and it is not open in the firewall.
	reverse_proxy 127.0.0.1:8158
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

You should see: `Valid configuration` from validate, and no output at all from reload.

If you do not: run `sudo cp /etc/caddy/Caddyfile.before-drawio /etc/caddy/Caddyfile`,
reload, and paste again. Do not add a `Content-Security-Policy` header of your own here.
The container writes its own CSP into the page as a meta tag at start-up, and a browser
enforces the intersection of the two, so a second policy usually shows up as an editor that
loads to a blank grey screen with errors in the browser console and nothing at all in the
Caddy log.

## 6. Firewall

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

You should see: `Status: active`, rules for `80/tcp`, `443/tcp` and `443/udp`, and no rule
mentioning `8158` or `8443`.

If you do not: delete anything for those two with `sudo ufw delete allow 8158`. 8158 is
bound to 127.0.0.1 by the compose file, and 8443 is never published at all, so the
container's own TLS port has no host port a firewall rule could apply to. `Status: inactive`
is a different problem: Prompt Zero left this firewall enabled, so something has turned it
off since, and `sudo ufw enable` puts it back before you go any further.

## 7. Start and verify

Tomcat rewrites the editor's configuration files from the environment at every start, so
the first boot is slower than the ones after it.

```bash
cd /srv/drawio
docker compose pull
docker compose up -d
for i in $(seq 1 20); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/); echo "$i $code"; [ "$code" = 200 ] && break; sleep 10; done
curl -sS https://<DOMAIN>/ | grep -c 'Flowchart Maker'
curl -sS https://<DOMAIN>/js/PreConfig.js | grep -cF "urlParams['gapi'] = '0'"
curl -sS https://<DOMAIN>/js/PreConfig.js | grep -cF "window.DRAWIO_SERVER_URL = 'https://<DOMAIN>/'"
```

You should see, in order: the loop reaching `200`, then `1`, then `1`, then `1`.

If you do not: the third command is the one worth understanding. It reads the configuration
file the container generated at start-up and checks that `gapi` is off, which means the
Google Drive backend is not offered to anyone who loads your editor. A `0` there means a
cloud storage button will appear in the app, and the cause is an environment variable that
should not be set. A `404` on PreConfig.js instead means the entrypoint could not write into
the webapp, which shows up in `docker compose logs --tail 40 drawio` as a `WARNING: No write
access` line. If the loop never reaches `200`, that is almost always DNS: a hostname whose
A record was created minutes ago makes Caddy's first certificate attempt fail and retry
quietly. A running container is not success. Four asserts passing is success.

The first screen at https://<DOMAIN>/?offline=1 is a dialog headed `Save diagrams to:` with
two buttons, `Device` and `Browser`, and a `Decide Later` link under them. There is no login
form and no sign-up link, because there are no accounts.

Open https://<DOMAIN>/?offline=1 now and confirm that dialog shows `Device` and `Browser`
and no Google Drive, OneDrive or GitHub button. That is the check no command can make for
you, and it is the difference between an editor that keeps your work on your own hardware
and one that offers to post it somewhere else.

## 8. First backup and restore

There is no database to dump and no data directory to archive, and saying so is more useful
than inventing one. The backup here is the configuration that rebuilds the service:

```bash
cd /srv/drawio
sudo tar -czf /srv/drawio/backups/drawio-config-$(date +%F).tar.gz -C /srv/drawio compose.yml .env -C /etc/caddy Caddyfile
ls -lh /srv/drawio/backups/
```

You should see: one file, a couple of kilobytes. Nothing goes offline, because there is no
write to catch halfway.

If you do not: an archive of about 45 bytes is an empty one, which means `tar` found none of
the three files. Check that you are in /srv/drawio and that step 3 and step 4 both wrote
their file.

A backup on the same disk as the data is not a backup. Run this one on your own machine,
not the server:

```bash
mkdir -p ~/backups/drawio
scp vps:/srv/drawio/backups/*.tar.gz ~/backups/drawio/
```

You should see: one file copied, and it listed by `ls -lh ~/backups/drawio/`.

If you do not: `Permission denied (publickey)` means you ran it on the server. The `vps:`
prefix only means something on your own machine, where the `vps` alias Prompt Zero created
lives.

Now the other half, and no command on that server can reach it. Open
https://<DOMAIN>/?offline=1, draw one shape, and use File then Save As to write the
`.drawio` file somewhere on your own computer. If you picked `Browser` in that first dialog
the diagram is in one browser's local storage on one machine, and the archive you took
above does not contain it and never will.

To restore the server: untar the archive into /srv/drawio, append the Caddy block from step
5 again, and run `docker compose up -d`. To restore a diagram, open the editor and use File
then Open to load the file you saved. That is two disaster plans, the second one holds your
work, and saving to your own disk is a habit rather than a step you did once today.

## 9. Updating later

New versions are listed at https://github.com/jgraph/drawio/releases, and the Docker tag is
the release tag without its leading `v`. Take the backup first, then edit the `image:` line
in /srv/drawio/compose.yml to the new tag and its digest.

```bash
cd /srv/drawio
docker compose pull
docker compose up -d
docker compose logs --tail 30 drawio
```

You should see: the entrypoint printing the configuration it wrote, then Tomcat starting,
and no repeating restart.

If you do not: put the old tag and digest back and run the same three commands. Then re-run
all four asserts from step 7 before you call the update done. Nothing is migrated in an
upgrade here, because the container carries no state between versions, which makes a
rollback the cheapest one in this catalogue.

## 10. What will probably go wrong

The first dialog. I clicked `Browser` because it sounded like the thing running on the
server, drew a diagram, and came back the next morning on a different laptop to an empty
canvas at the same hostname. Nothing was broken. `Browser` means that browser's local
storage on that machine, `Device` means a file on the computer in front of you, and neither
of them is the server. I spent several minutes reading Tomcat logs looking for a database
that has never existed. If a diagram disappears, ask which browser and machine you drew it
on before you read a log line.

## 11. Out of scope

- Do not install the export server or set `DRAWIO_SELF_CONTAINED` or `EXPORT_URL`. That is
  a second container carrying its own headless Chromium, and this install runs one service.
  PNG and SVG export from the browser works without it.
- Do not set `DRAWIO_GOOGLE_CLIENT_ID`, `DRAWIO_MSGRAPH_CLIENT_ID` or `DRAWIO_GITLAB_ID`.
  Each one is an OAuth application registered with somebody else, and step 7 asserts that
  those backends are off.
- Do not set `ENABLE_DRAWIO_PROXY=1`. It opens a `/proxy` endpoint that fetches arbitrary
  external URLs on your server's behalf, which is a request forwarder pointed at your own
  network.
- Do not publish container port 8443 and do not set `LETS_ENCRYPT_ENABLED`. Caddy holds the
  certificate for this hostname, and a second one inside the container would be a second
  thing to renew.

312 lines · 14,994 bytes

You are Claude Code on the user's own computer. There is no server and no Prompt Zero:
everything in this prompt runs on this machine and stays on it.

Run every command on this computer, in the shell you are already in. Nothing in this prompt
uses ssh.

Install draw.io 31.1.8 under ~/selfhost/drawio, answering at http://localhost:8158.

## 1. Preflight

Say both of these to the user before step 2 runs; together they decide whether this install
is worth doing.

First: draw.io already runs a hosted editor at https://app.diagrams.net that costs nothing
and asks for no account. Their own home page says "No account required. No credit card."
This prompt installs the same editor; what changes is where the page comes from. This copy
loads from a container here, so it works with the network unplugged and no third-party
origin serves the code. If neither matters, say plainly that the hosted editor does the
same job.

Second: nothing here stores a diagram. The container has no database and no document store,
so a drawing lives in the storage of the browser that drew it or in a file the user saves
themselves, and clearing site data loses work no backup could have held.

Detect the OS and measure the machine:

```bash
uname -s
case "$(uname -s)" in
  Darwin) vm_stat | awk '/page size/{p=$8} /free|inactive/{s+=$3} END {printf "%d MB available\n", s*p/1048576}' ;;
  Linux) . /etc/os-release && echo "$ID $VERSION_CODENAME"; free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}' ;;
  MINGW*|MSYS*) powershell -Command "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory" | awk '$1+0 {printf "%d MB available\n", $1/1024}' ;;
esac
df -h ~
```

`Darwin` is macOS, `Linux` is Linux, `MINGW` or `MSYS` is Windows under Git Bash. On Linux
the distribution ID and codename print next, for step 2. draw.io is a Tomcat on a JVM and
wants 1024 MB of RAM available and 5 GB free on the home disk; the image publishes amd64
and arm64. Every branch prints free memory, so one floor covers all three, and Docker
Desktop takes its allocation out of that number. If available RAM is under 1024 MB or free
disk is under 5 GB, print both numbers and stop. Do not install and hope.

## 2. Docker

Check before installing anything:

```bash
docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker MISSING"
docker compose version 2>/dev/null || true
```

If that printed `docker OK` and a compose version, skip to step 3.

Otherwise, install Docker for the OS step 1 detected:

- macOS: if `command -v brew` succeeds, run `brew install --cask docker`. If there is no
  Homebrew, STOP: tell the user to download Docker Desktop from
  https://www.docker.com/products/docker-desktop/ and install it, and wait until they
  confirm. Either way, then STOP: tell the user to open Docker Desktop once, accept its
  terms, and wait for the whale icon to say it is running. Do not continue until they
  confirm.
- Windows: run `winget install -e --id Docker.DockerDesktop`. If winget is missing or the
  install fails, STOP: tell the user to download Docker Desktop from the URL above and
  install it, and wait until they confirm. Docker Desktop configures WSL 2 itself and may
  ask for a reboot; if it does, STOP and tell the user to reboot and come back, this
  prompt resumes at this step. Then STOP: have the user open Docker Desktop, accept its
  terms, and confirm it says running.
- Linux, Debian or Ubuntu: install Docker Engine from download.docker.com's apt
  repository, with its signing key saved to a file first, never piped into a shell. The
  fence is guarded, a no-op on anything but a Linux with apt:

```bash
if [ "$(uname -s)" = "Linux" ] && command -v apt-get >/dev/null 2>&1; then
  sudo apt-get update
  sudo apt-get install -y ca-certificates curl
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo "$ID") $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
  sudo apt-get update
  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
  sudo usermod -aG docker "$USER"
fi
```

  Adding the user to the docker group is root-equivalent on this machine; say that to the
  user in one sentence, and tell them the group change lands at their next login.
- Linux, anything else: STOP. Tell the user to install Docker Engine and the compose
  plugin with their distribution's package manager, and to run this prompt again once
  `docker info` works.

Assert: `docker info` exits 0 and `docker compose version` prints a version. Do not
continue without both.

## 3. Layout

```bash
mkdir -p ~/selfhost/drawio/backups
ls -la ~/selfhost/drawio
```

Assert: `ls -la` shows `backups`, owned by the user. There is no `data` folder: the
container writes no diagram to disk, so step 5 mounts nothing and no ownership fix is
needed on any of the three systems.

## 4. Secrets

One secret, and it is not a login. draw.io has no accounts, so there is nothing to sign in
to. What this generates is `KEYSTORE_PASS`: the image builds a self-signed certificate for
its own container port 8443 at every start, and with that variable unset it uses a value
printed in its own public documentation. That port is never published here, so a documented
default would guard something unreachable, which is a reason to replace it rather than a
reason to keep it. Print it nowhere, and keep it out of your summary and out of any log.

```bash
umask 077
cat > ~/selfhost/drawio/.env <<EOF
DRAWIO_SERVER_URL=http://localhost:8158/
KEYSTORE_PASS=$(openssl rand -hex 32)
EOF
chmod 600 ~/selfhost/drawio/.env
umask 022
ls -l ~/selfhost/drawio/.env
```

Assert: the file exists with mode `-rw-------`. Git Bash ships openssl, so this runs the
same on all three systems. `DRAWIO_SERVER_URL` is upstream's variable for the deployment
URL and it wants the trailing slash, which is why the line ends in one.

On Windows those mode bits are advisory: NTFS does not enforce them, and the real boundary
is the user's own Windows account.

## 5. compose.yml

```bash
cat > ~/selfhost/drawio/compose.yml <<'EOF'
# draw.io · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   image, ports, env vars .. https://github.com/jgraph/docker-drawio/blob/v31.1.8/README.md
#   entrypoint behaviour .... https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/docker-entrypoint.sh
#   image build ............. https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/Dockerfile
#
# One container: Tomcat 9 on JDK 11 serving the compiled draw.io editor at the
# root path on container port 8080, as a non-root tomcat user. This file lives
# in ~/selfhost/drawio/ and holds no absolute path, so it works on all three.
#
# There is no volume here, and that is not an omission: a diagram is written to
# this computer's disk or into the browser that drew it, never to the server.
#
# The entrypoint switches every cloud backend off when its credentials are
# absent: with no DRAWIO_GOOGLE_CLIENT_ID, DRAWIO_MSGRAPH_CLIENT_ID or
# DRAWIO_GITLAB_ID it writes gapi, od and gl to 0, and it always writes db, gh
# and tr to 0. This file sets none of them, so none of them are on.
#
# KEYSTORE_PASS arrives from ./.env. Left alone, the image falls back to a
# keystore value printed in its own documentation, on a self-signed certificate
# it makes at every start for container port 8443, which this file never
# publishes. The generated value replaces a documented default.
#
# Tag and digest read from Docker Hub on 2026-08-06; the manifest list covers
# linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  drawio:
    image: jgraph/drawio:31.1.8@sha256:0c8910ea14dfbccb17c784ee17d995317a8d753479f5ec0f21b2ab2213153100
    container_name: drawio
    restart: unless-stopped
    env_file: ./.env
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/ >/dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    ports:
      # Loopback only: no other device on the wifi can reach 8158.
      - "127.0.0.1:8158:8080"
EOF
cd ~/selfhost/drawio && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. One service, one published port, no mounts.

## 6. Nothing is public

No reverse proxy, no certificate, no firewall rule. Each is a decision:

- No DNS. There is no hostname, so nothing to resolve and nothing to wait for.
- No TLS. A certificate attests a public name and nothing here has one. Browsers treat
  http://localhost as a secure context anyway.
- No firewall rule. Nothing is published beyond loopback, so no port needs closing.

8158 is bound to 127.0.0.1, this computer only: not the user's phone, not a laptop on the
same wifi, not anyone on the internet. Confirm it:

```bash
grep -c '"127.0.0.1:' ~/selfhost/drawio/compose.yml
```

Assert: that prints `1`, the single published port `- "127.0.0.1:8158:8080"`. Container
port 8443 is never published, so the certificate the image makes at start-up has no way in.

## 7. Start and verify

Tomcat rewrites the editor's configuration from the environment at every start, so the
first boot is the slow one.

```bash
cd ~/selfhost/drawio
docker compose pull
docker compose up -d
for i in $(seq 1 20); do code=$(curl -sS -o /dev/null -w '%{http_code}' http://localhost:8158/); echo "$i $code"; [ "$code" = 200 ] && break; sleep 10; done
curl -sS http://localhost:8158/ | grep -c 'Flowchart Maker'
curl -sS http://localhost:8158/js/PreConfig.js | grep -cF "urlParams['gapi'] = '0'"
curl -sS http://localhost:8158/js/PreConfig.js | grep -cF "window.DRAWIO_SERVER_URL = 'http://localhost:8158/'"
```

Assert all four, and print what you received for each. The loop ends on `200`. The second
command prints `1`, because `Flowchart Maker` is in the title of the served document. The
third prints `1`, the security assert here: it proves the container wrote `gapi` off, so
the Google Drive backend is not offered on this page. The fourth prints `1`, proving the
`.env` from step 4 reached the container. If any of the four misses, stop, run
`docker compose logs --tail 40 drawio`, and name the likely cause: a `404` on PreConfig.js
means the entrypoint could not write into the webapp, and a loop that never reaches `200`
usually means Tomcat is still starting, so give it another minute. If
`port is already allocated` came back, find what holds 8158 with
`lsof -nP -iTCP:8158 -sTCP:LISTEN` and stop until the user frees it. A running container is
not success. Four asserts is success.

The first screen at http://localhost:8158/?offline=1 is a dialog headed `Save diagrams to:`
with two buttons, `Device` and `Browser`, and a `Decide Later` link under them. There is no
login form and no sign-up link, because there are no accounts.

STOP: tell the user to open http://localhost:8158/?offline=1, confirm that dialog shows
`Device` and `Browser` and no Google Drive, OneDrive or GitHub button, and wait.
Do not continue until they confirm. That check is the difference between an editor that
keeps the work on this machine and one that offers to post it somewhere else.

## 8. First backup and restore

There is no database to dump and no data directory to archive. The backup here is the
configuration that rebuilds the service:

```bash
cd ~/selfhost/drawio
tar -C ~/selfhost/drawio -czf ~/selfhost/drawio/backups/drawio-config-$(date +%F).tar.gz compose.yml .env
ls -lh ~/selfhost/drawio/backups/
```

Assert: the archive exists and is non-empty. Print its size. Nothing is stopped, because
there is no write to catch halfway.

That archive sits on the same disk as everything else, which is not a backup, and on a
laptop the disk and the machine fail together. Ask the user for a destination that leaves
this computer, a folder their sync service watches or a USB stick, and copy it there with
`cp`. In Git Bash a Windows drive is written `/d/Backups`. Assert: the user confirms the
filename is listed there.

The diagrams are the other half, and no command here can reach them.

STOP: tell the user to open http://localhost:8158/?offline=1, draw one shape, and use File
then Save As to write the `.drawio` file into a folder they already back up, and wait.
Do not continue until they confirm they have that file. Explain why: pick `Browser` in
that dialog and the diagram is in one browser's local storage, which the archive above
does not contain.

To restore the service: untar the archive into ~/selfhost/drawio and run
`docker compose up -d`. To restore a diagram, open the editor and use File then Open. Tell
the user that is two disaster plans and the second one holds the work.

## 9. Updating later

New versions are listed at https://github.com/jgraph/drawio/releases, and the Docker tag is
the release tag without its leading `v`. Take the backup first, then edit the image line in
~/selfhost/drawio/compose.yml to the new tag and its digest:

```bash
cd ~/selfhost/drawio
docker compose pull
docker compose up -d
docker compose logs --tail 30 drawio
```

Then re-run all four asserts from step 7 before calling the update done. Nothing is
migrated, because the container carries no state between versions.

## 10. What will probably go wrong

I rebooted, opened http://localhost:8158 out of habit, and got a connection error that
looked like the install had evaporated. It had not: Docker Desktop had not started with the
session, so nothing was listening on 8158. `restart: unless-stopped` acts only once the
Docker daemon is up. Turn on its start-at-login setting, and after a reboot run
`cd ~/selfhost/drawio && docker compose up -d` before concluding anything is broken. The
diagrams were never at risk: they were in the browser and on the disk, not in the container.

## 11. Out of scope

- Do not expose this to the internet.
- Do not configure port forwarding on the router.
- Do not add a reverse proxy or TLS.
- Do not rebind 8158 to 0.0.0.0 so a phone or a colleague can reach it. That publishes an
  editor with no login on every network this machine joins.
- Do not install the export server or set `DRAWIO_SELF_CONTAINED` or `EXPORT_URL`. That is
  a second container carrying headless Chromium; PNG and SVG export from the browser works
  without it.
- Do not set `DRAWIO_GOOGLE_CLIENT_ID`, `DRAWIO_MSGRAPH_CLIENT_ID`, `DRAWIO_GITLAB_ID` or
  `ENABLE_DRAWIO_PROXY=1`. The first three are OAuth applications registered with somebody
  else, and step 7 asserts they are off; the last opens an endpoint that fetches arbitrary
  external URLs from inside this machine's network.

# draw.io · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   image, ports, env vars .. https://github.com/jgraph/docker-drawio/blob/v31.1.8/README.md
#   entrypoint behaviour .... https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/docker-entrypoint.sh
#   image build ............. https://github.com/jgraph/docker-drawio/blob/v31.1.8/main/Dockerfile
#
# One container: Tomcat 9 on JDK 11 serving the compiled draw.io editor at the
# root path on container port 8080, as a non-root tomcat user. This file lives
# in ~/selfhost/drawio/ and holds no absolute path, so it works on all three.
#
# There is no volume here, and that is not an omission: a diagram is written to
# this computer's disk or into the browser that drew it, never to the server.
#
# The entrypoint switches every cloud backend off when its credentials are
# absent: with no DRAWIO_GOOGLE_CLIENT_ID, DRAWIO_MSGRAPH_CLIENT_ID or
# DRAWIO_GITLAB_ID it writes gapi, od and gl to 0, and it always writes db, gh
# and tr to 0. This file sets none of them, so none of them are on.
#
# KEYSTORE_PASS arrives from ./.env. Left alone, the image falls back to a
# keystore value printed in its own documentation, on a self-signed certificate
# it makes at every start for container port 8443, which this file never
# publishes. The generated value replaces a documented default.
#
# Tag and digest read from Docker Hub on 2026-08-06; the manifest list covers
# linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  drawio:
    image: jgraph/drawio:31.1.8@sha256:0c8910ea14dfbccb17c784ee17d995317a8d753479f5ec0f21b2ab2213153100
    container_name: drawio
    restart: unless-stopped
    env_file: ./.env
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/ >/dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    ports:
      # Loopback only: no other device on the wifi can reach 8158.
      - "127.0.0.1:8158:8080"