Skip to content

Upgrade Guide

Jump to bottom
Sia edited this page May 31, 2026 · 5 revisions

Upgrade Guide

Upgrading is a pull-and-recreate in your ops compose directory. All data under ./vibe-coder-data/ is preserved across image upgrades.

Standard upgrade

cd ~/vibe-coder
docker compose pull
docker compose up -d --force-recreate
docker compose logs -f vibe-coder-server   # watch boot output

The slim image carries only the Ktor server + Claude CLI + JDK + Node. The build environment — Android SDK, Gradle cache, MCP servers, Claude credentials, SSH key, keystores — lives in the ./vibe-coder-data/ bind mounts and survives every image upgrade. You never re-download the SDK or re-authenticate Claude just because you pulled a newer image.

Backup before upgrading

docker compose stop
sudo tar czf vibe-coder-data-pre-upgrade-$(date +%F).tar.gz vibe-coder-data/
sudo chown $(id -u):$(id -g) vibe-coder-data-pre-upgrade-*.tar.gz
docker compose start

sudo is needed because the PostgreSQL data directory (vibe-coder-data/postgres/) is owned by UID 70 inside the container. For a running-server alternative (logical PG dump + workspace tar) see Data Volumes & Backup.

Compose file changes

If you maintain your own compose.yml (rather than using the bundled one), re-check it against the repo's docker/compose.yml after each upgrade so you pick up any new bind mounts or environment variables. The bundled compose already maps every persistent path:

- ./vibe-coder-data/dev-tools/ssh:/home/vibe/.ssh
- ./vibe-coder-data/dev-tools/keystores:/home/vibe/keystores

New host directories are created empty on first boot. The entrypoint generates an ED25519 SSH key into the .ssh mount on first boot if none exists and never overwrites it afterwards — register the public key on your Git host via Settings → SSH Key. Create signing keystores via Settings → Keystores.

Data-volume compatibility caveats

  • Back up ./vibe-coder-data/dev-tools/keystores/ after creating each release keystore. Losing a release key blocks Play Store updates for that package permanently.
  • The PostgreSQL data directory (vibe-coder-data/postgres/) must keep its UID 70 ownership. When copying data to another host, restore with sudo tar and leave that directory's ownership alone — fixing PUID/PGID on the other top-level dirs is fine, but never chown the postgres dir.
  • VIBECODER_DB_PASSWORD must stay the same across a restore of the PostgreSQL data directory, or the restored data won't authenticate.

Rollback

If a release misbehaves, pin the previous version and recreate:

cd ~/vibe-coder
sed -i 's|siamakerlab/vibe-coder-server:.*|siamakerlab/vibe-coder-server:<previous-version>|' compose.yml
docker compose pull
docker compose up -d --force-recreate

The unified ./vibe-coder-data/ layout keeps rollback data-safe. Restore from a pre-upgrade snapshot if needed:

docker compose down
sudo rm -rf vibe-coder-data/
sudo tar xzf vibe-coder-data-pre-upgrade-*.tar.gz
docker compose up -d

Pinning versions

By default compose.yml ships with :latest. To pin a specific tag:

image: siamakerlab/vibe-coder-server:<version>

Pinning is recommended for production-leaning installs — bump deliberately after reading the CHANGELOG. The published image set on Docker Hub keeps older tags available indefinitely.

Clone this wiki locally