[turin-dev]

What and why

A new reader should be able to install Aven from the README without guessing ports, DNS, which files change, or how to undo it. The README and the Korean README now follow the installer. The long backup, upgrade, uninstall, and troubleshooting steps are in the self-hosting guides. A few first-run messages still told people to use Keel setting names.

How

Docs were written from install-server.sh, internal/api/install-agent.sh, server startup, the proxy container, the SQLite backup path, and aven pitr in docs/cli.md. They do not add a memory or disk minimum: the installer does not check one, so the old "2 vCPU and 4 GB" line is gone.

Small code changes, each covered by a test:

• The agent installer accepts AVEN_* and KEEL_* extra settings and writes AVEN_*. It still reads an old KEEL_* value. The unit stays keel-agent.service and the directories stay /etc/keel-agent and /var/lib/keel-agent, so a re-run still replaces an existing agent.
• The server installer passes AVEN_PRIVATE_ADDRESS and AVEN_JOIN_TOKEN, and no longer tells the operator to add KEEL_PRIVATE_ADDRESS.
• docker info failures include the command's own text. A permission denial is not reported as a stopped daemon.
• Join-token, GitHub webhook, and missing-Railpack errors name AVEN_* first and still mention the KEEL_* name.

Changes

• README.md and README.ko.md: prerequisites (OS, what Docker is checked, memory and disk not checked, ports, domain and DNS for on-demand TLS), read-the-script-then-run, files and services a main install and a region install create, how to check that it started, short troubleshooting, and pointers to the manual install and uninstall. Cron and app sleeping in the highlights point at the existing experimental rows. The comparison table and the GIF are unchanged.
• docs/self-hosting.md and docs/self-hosting.ko.md: the same path in full, including backups and restore of aven.db plus master.key, logical dumps, Postgres WAL and MySQL binlog PITR, upgrade and rollback, uninstall, and troubleshooting for ports in use, DNS or TLS, Docker permissions, firewall or IPv6, and an agent that does not join. Stale keel.db / docker logs keel-proxy commands for a new install now say aven.db and aven-proxy, and say when the old names still apply. The English guide uses the English admin labels.
• docs/selfhost.md and docs/selfhost.ko.md: docker ps --filter label=aven.self, with the old keel.self label called out for an install that still has it. The swap note names aven-proxy.
• Website copy in website/lang/en/site.php and website/lang/ko/site.php: the install section no longer says the install finishes in a few minutes, the closing line no longer calls Aven free, cron and sleeping apps are marked experimental, and the dashboard section says the UI has no component or end-to-end tests. home.blade.php prints that note.

Checklist

• go test ./... passed locally. cd web && npm run typecheck && npm run i18n:check && npm run build passed. i18n:check still prints pre-existing untranslated Korean strings and exits 0.
• Tests for the installer strings, the join-token 503, the webhook 403, and the Railpack error. Docs updated.
• No database migration. Configuration for a new agent env file is AVEN_SERVER_URL / AVEN_JOIN_TOKEN / AVEN_CA_FILE instead of the KEEL_* spellings. An existing KEEL_* value is still read, and a re-run rewrites the managed keys to AVEN_*. The systemd unit name did not change.
• No real credentials, private hostnames, or user data.

What was not verified

• The installer was not run on a host with systemd, Docker, free ports 80/443, or a public domain. sh -n and the Go tests cover the script text. The failure text is from the source, not from a live ACME, firewall, or join attempt.
• go vet was run on the packages this change touches, not as go vet ./....
• The website PHP suite and the container image build were not run.
• Competitor cells in the README table were not re-fetched. The table, its 2026-10-27 check date, and the GIF are unchanged.
• No memory or disk figure was measured. The docs say the installer does not check either.

Follow-ups

• Give a new agent install aven-agent.service, /etc/aven-agent, and /var/lib/aven-agent, and migrate an existing keel-agent unit. That is a larger change than rewriting the env keys.
• install-agent.sh still calls die inside the --env pipeline. Without pipefail, a rejected key may not stop the parent shell. That was already true.
• The port check only warns, and it only looks for TCP listeners, so 443/udp is not part of the warning.
• Agent enrollment logs HTTP 401 and drops the API error body (invalid join token / invalid or expired join token).
• App sleeping and cron still have no test that fires the idle-sleep, wake, or scheduled run. The web dashboard still has no component or end-to-end tests.