Skip to main content
Production checklist

​
Upgrade from v0.1.0 to v0.2.0

v0.2.0 has no upgrade.sh, automated upgrade tooling, or automatic rollback. This is the last release without automated upgrade tooling. Releases after v0.2.0 upgrade with the distribution manifest. This is a source upgrade. The db-migrations, app, and worker services are built from the checked-out source; only third-party service images are pulled.
Run the backup before fetching or replacing any source:
This command still works after v0.2.0 stops publishing the PostgreSQL port. docker compose exec reaches the container through the Docker daemon, not through a published network port.
v0.2.0 stops exposing PostgreSQL on 5432 and Valkey on 6379 to the host. Connections from another host will lose access after the upgrade. Identify those clients now; apply the host-access option only after the v0.2.0 files are present.
For an existing Git checkout:
For a tarball install, download the v0.2.0 source tarball from the release assets, preserve the old source directory for rollback, and extract the new source under the same directory name:
Keeping the bisibility directory name also keeps the default Compose project name and its existing volumes.
If the Docker host must reach PostgreSQL or Valkey, use the debug overlay shipped in v0.2.0 as the upgrade command:
This binds both services to 127.0.0.1. Use a hand-written docker-compose.override.yml only for other requirements, and keep the loopback prefix on every mapping, such as 127.0.0.1:5432:5432. A mapping such as 5432:5432 binds to all interfaces and reverses this release’s protection.If you run the overlay command above, do not run the base-only command in the next step; the overlay command performs the same rebuild and startup.
If you do not need the debug overlay, run:
Migrations apply automatically: the one-shot db-migrations service runs before the app, and the app waits for it to finish successfully. v0.2.0 includes a schema migration.--build performs a full Next.js build on this machine; it does not pull a prebuilt bisibility image. Expect sustained CPU use, several GB of RAM or swap, and free disk space for Docker layers. A small VPS can exhaust RAM and fail mid-build.
The migration service must show a successful exit, the app must be running, and the health request must succeed. Prisma must report that the database schema is up to date. Adjust 3000 if APP_HOST_PORT is set. On the base stack, both docker compose port commands should report no published port. With the debug overlay, they should report only 127.0.0.1 mappings.
There is no automatic rollback. For a Git checkout, return to the old source and rebuild it:
Security warning: Rolling back restores the v0.1.0 Compose file, which publishes PostgreSQL 5432 and Valkey 6379 on all host interfaces by default. If v0.1.0 will remain running beyond immediate recovery, check it out without starting Compose, then remove the ports blocks from postgres and redis when host access is not needed. Otherwise, change the mappings to 127.0.0.1:${POSTGRES_HOST_PORT:-5432}:5432 and 127.0.0.1:${REDIS_HOST_PORT:-6379}:6379 before running docker compose up -d --build.
For the tarball path above, restore the retained source directory:
If the migration did not start or completed successfully, rebuild v0.1.0 now:
If the v0.2.0 migration applied only partially, first restore the v0.1.0 source with git checkout v0.1.0 or the tarball directory swap above. Do not start the old app yet. Stop application writes, restore the backup from step 1, and then rebuild v0.1.0: