Skip to content

Upgrade Guide

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

Upgrade Guide

Standard upgrade (data preserved):

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

This is safe for any v0.14.0 → newer transition. For older versions see the per-version notes below.

Version-specific notes

v1.4.x → v1.5.0 (Android keystore management — additive bind-mount)

v1.5.0 introduces a new persistent volume:

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

If you wrote your own compose.yml (rather than the bundled one) you must add this line by hand before pulling v1.5.0. Then:

cd ~/vibe-coder
docker compose pull
docker compose up -d --force-recreate

The host directory ./vibe-coder-data/dev-tools/keystores/ is created on first boot (empty). Open Settings → Keystores in the admin UI to create your first keystore. Pre-fill keystore.defaults in server.yml (CN / organization / unit / country / state / city / default password / validity years) so every new keystore only requires the package name.

⚠️ Critical: back up ./vibe-coder-data/dev-tools/keystores/ after creating each release keystore. Losing the file blocks Play Store updates for that package permanently.

v1.2.0 / v1.3.0 → v1.3.1 (entrypoint regression hotfix)

v1.2.0 introduced eager SSH key auto-generation in the entrypoint, but both v1.2.0 and v1.3.0 shipped without the openssh-client package. On startup ssh-keygen failed and set -euo pipefail killed the entrypoint, leaving the container stuck in a Restarting (1) loop. Symptoms:

  • docker ps shows Restarting (1) indefinitely.
  • Port 17880 never reaches LISTEN → reverse proxies return 502 Bad Gateway to clients (Android app, browser).
  • docker logs vibe-coder-server ends with error: exec: "ssh-keygen": executable file not found in $PATH.
  • PostgreSQL sidecar stays healthy in isolation.

Fix (v1.3.1):

  1. openssh-client is now bundled in the image.
  2. The entrypoint's SSH key block degrades gracefully — missing ssh-keygen or a generation failure now logs a warning and lets the server boot anyway.

Upgrade:

cd ~/vibe-coder
docker compose pull            # pulls 1.3.1 (sha256:72ed6a53…)
docker compose up -d
docker compose logs -f vibe-coder-server
# Expect: "[entrypoint] SSH 키 (ED25519) 자동 생성 — /home/vibe/.ssh/id_ed25519"
#   on first boot if no key existed yet, then the normal server startup banner.

If you'd been on v1.2.0 / v1.3.0 long enough that the entrypoint never finished, no SSH key was created — v1.3.1's first successful boot generates one. Open Settings → SSH Key in the admin UI to copy the public key and register it on Gitea / GitHub.

v1.1.x → v1.2.0 (SSH key bind-mount — additive)

v1.2.0 added a new bind mount:

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

If you wrote your own compose.yml (not the one shipped in this repo), add the line by hand. Then docker compose down && docker compose up -d re-creates the container with the new mount; the entrypoint generates an ED25519 keypair into the new directory on first boot. See Git-Integration.

See also: v1.3.1 regression hotfix above — if you upgraded directly from v1.1.x to v1.2.0 you may want to skip straight to v1.3.1 to avoid the restart-loop window.

v0.13.x → v0.14.0 (PostgreSQL — Breaking)

v0.14.0 swaps the embedded SQLite database for a sidecar postgres:17-alpine container. Existing SQLite data is not carried over (fresh start for admin / projects / build history), but workspace files are preserved because they live in vibe-coder-data/workspace/ and are independent of the database.

Why the change

  • SQLite is single-writer; future features such as conversation history and full-text search would hit lock contention as the server scales beyond one active user.
  • PostgreSQL's JSONB column gives a clean home for varied tool_use input/output shapes (Claude Code stream-json).
  • Standard ops tooling (pg_dump, monitoring, replication) is broader.

Step-by-step

# 1. Stop everything
cd ~/vibe-coder
docker compose down

# 2. (Optional) keep the old SQLite file as a forensic backup
mv vibe-coder-data/server/.vibecoder/vibecoder.db ./vibecoder-v0.13-backup.sqlite 2>/dev/null || true

# 3. Fetch the new compose + env templates
curl -fsSL https://raw.githubusercontent.com/siamakerlab/vibe-coder-server/main/docker/compose.yml -o compose.yml
curl -fsSL https://raw.githubusercontent.com/siamakerlab/vibe-coder-server/main/docker/.env.example -o .env

# 4. CRITICAL: set VIBECODER_DB_PASSWORD to a strong value.
#    compose REFUSES to start with empty password.
${EDITOR:-nano} .env

# 5. Start both containers (postgres + vibe-coder-server)
docker compose up -d

# 6. http://<IP>:17880/setup → re-create the admin user
#    Then /projects → re-register existing projects (the workspace folders
#    still exist on disk under vibe-coder-data/workspace/<projectId>/).

Tip — preserve project metadata. When re-registering, use the same projectId as before so the source folder is reused as-is. Build history from the SQLite era is lost; APK files in vibe-coder-data/.vibecoder/<projectId>/artifacts/ are still on disk.

Rollback

If you must revert to v0.13.x:

docker compose down
sed -i 's|siamakerlab/vibe-coder-server:.*|siamakerlab/vibe-coder-server:0.13.0|' compose.yml
# Restore the SQLite backup
mkdir -p vibe-coder-data/server/.vibecoder
cp vibecoder-v0.13-backup.sqlite vibe-coder-data/server/.vibecoder/vibecoder.db
# Remove the postgres service block from compose.yml manually, or fetch the
# v0.13 compose.yml from the tagged release
docker compose up -d

v0.6.x → v0.7.0 (volume restructuring)

Pre-0.7.0 used Docker named volumes (vibe-android-sdk, vibe-gradle-cache) and put MCP servers in image layers. v0.7.0 routes everything to bind mounts under ./vibe-coder-data/. Existing users must migrate.

Option 1 — clean restart (recommended, 5-15 min)

cd ~/vibe-coder
docker compose down                      # named volumes preserved
curl -fsSL https://raw.githubusercontent.com/siamakerlab/vibe-coder-server/main/docker/compose.yml -o compose.yml
curl -fsSL https://raw.githubusercontent.com/siamakerlab/vibe-coder-server/main/docker/.env.example -o .env
# Edit .env to set VIBE_DATA_ROOT (default ./vibe-coder-data)
docker compose up -d
# Browser → /env-setup → "Install/update all"  (re-downloads SDK)

Option 2 — copy existing named-volume data (saves SDK re-download)

cd ~/vibe-coder
docker compose down

# Android SDK
docker run --rm \
    -v vibe-coder_vibe-android-sdk:/from \
    -v "$(pwd)/vibe-coder-data/dev-tools/android-sdk":/to \
    alpine sh -c 'cp -a /from/. /to/'

# Gradle cache
docker run --rm \
    -v vibe-coder_vibe-gradle-cache:/from \
    -v "$(pwd)/vibe-coder-data/dev-tools/gradle":/to \
    alpine sh -c 'cp -a /from/. /to/'

# Claude auth (if you had ~/.claude mounted, keep it; or migrate)
cp -a ~/.claude vibe-coder-data/claude

# New compose.yml + boot
curl -fsSL .../compose.yml -o compose.yml
docker compose up -d

# After confirming everything works, delete old named volumes
docker volume rm vibe-coder_vibe-android-sdk vibe-coder_vibe-gradle-cache

⚠ MCP servers must be reinstalled in both options — they used to live in the image's /usr/local/lib/node_modules/ and don't exist in named volumes. v0.8.0's MCP catalog UI makes this a one-click affair.

v0.7.x → v0.8.0 (MCP catalog)

Server-side change only. Existing MCPs registered in .mcp.json continue to work. The new /env-setup/mcp page reads existing entries and lets you add 60+ more.

v0.8.0 → v0.8.1 (Ubuntu noble base)

Just docker compose pull && up -d --force-recreate. New container is Ubuntu 24.04 LTS; vibe user UID/GID 1000 is preserved.

v0.8.x → v0.10.0 (wire change)

Two new APIs:

  • RegisterProjectRequestDto gained sourceType/cloneUrl/cloneBranch fields (all optional, default empty). Old clients still work.
  • 19 new /api/env-setup/* and /api/settings/git-integrations/* endpoints. Old clients ignore them.

Both v0.9 and v0.10 features are in 0.10.0. Update the Android client's shared/ copy to pick up the new constants/DTOs.

v0.13.x → v0.14.0 (wire change — turn cancel)

Added ApiPath.claudeConsoleCancel(projectId) = POST /api/projects/{projectId}/claude/console/cancel. Android shared/ copy needs the new constant. Old clients keep working — they just don't get the new turn-cancel button.

Rollback

If a new release misbehaves:

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

The unified ./vibe-coder-data/ layout means rollback is data-safe in either direction for v0.7.0 — v0.13.x. Crossing v0.14.0 requires restoring the SQLite backup (see the v0.14.0 section above).

Pinning versions

By default compose.yml ships with :latest. To pin:

image: siamakerlab/vibe-coder-server:0.14.0

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.

Backup before upgrading

For non-breaking upgrades (v0.7.0 — v0.13.x):

docker compose stop
sudo tar czf vibe-coder-data-pre-upgrade-$(date +%F).tar.gz vibe-coder-data/
docker compose start

For v0.13 → v0.14 (PG transition), use a logical dump as the rollback artifact (the SQLite file in step 2 of the v0.14.0 section above).

Roll back is then:

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

Clone this wiki locally