Operations And Upgrades

Run these commands from the same installation directory and with the same received Compose file and environment file used at installation. Substitute your received filenames if they differ from the examples. If you use external S3, include -f compose.external-s3.yml after the base Compose file in every command.

Health And Logs

docker compose --env-file .env.self-host -f compose.self-host.yml ps -a
docker compose --env-file .env.self-host -f compose.self-host.yml logs --tail 100 web worker migrate

The application readiness endpoint is /api/health/ready. It checks PostgreSQL, Valkey, and access to the configured storage backend. Web and worker wait for migrations to succeed and for the queue and storage services to become healthy.

The migrate container exits with code 0 when its work succeeds. An exited migration container is normal. If it exits with an error, inspect its logs before restarting the application.

Named volumes retain data across normal container replacement. Do not use docker compose down -v on an installation you intend to keep: it removes the Compose volumes.

Back Up The Whole Installation

For a consistent backup of the default single-host stack, stop web and worker, then stop storage and Valkey. Keep PostgreSQL running for the database export:

docker compose --env-file .env.self-host -f compose.self-host.yml stop web worker
docker compose --env-file .env.self-host -f compose.self-host.yml stop storage valkey
docker compose --env-file .env.self-host -f compose.self-host.yml exec -T postgres \
  pg_dump -U archflow -d archflow -Fc > archflow.dump

For external S3, stop only valkey in the second command; there is no bundled storage container to stop. Capture the bucket backup while web and worker remain stopped.

Store the database export securely together with:

Docker Compose cp works with stopped containers and can copy their /data directories into your backup location. Copy the directories before restarting their services.

Restart the installation after the backup:

docker compose --env-file .env.self-host -f compose.self-host.yml start

Restore-test into a separate empty stack using the matching version. Restore the database, storage, queue state, and environment before starting web and worker. Verify sign-in, images, source documents, and background jobs. Restoring only PostgreSQL is incomplete.

Project export is an interchange format, not a complete installation backup. It does not include every file or all operational state.

Upgrade Deliberately

1. Read the target version's release and migration notes.
2. Make a complete backup and record the current application version.
3. Stop web and worker before applying schema changes.
4. Put the new release's received Compose files in the existing installation directory and review any configuration changes. Preserve .env.self-host, its secrets, the Compose project name, and the existing data volumes.
5. Pull the images referenced by the new Compose file, or load the supplied image archives as described in setup.
6. Start the supplied version:

docker compose --env-file .env.self-host -f compose.self-host.yml up -d --no-build --pull never

The migration service applies pending migrations before the new web and worker services start. Check logs and readiness, then verify sign-in and representative project operations.

There is no automatic updater in the application. Use the image references and upgrade instructions supplied with each release. Keep local copies or an internal registry mirror of versions you may need to restore. No source checkout or local image build is needed.

Schema migrations can make an image-only rollback unsafe. Restore the matching database, files, and queue backup when a schema change requires a full rollback.

Troubleshooting

SeaweedFS mini is a single-node service. Persistent volumes survive container replacement, but they do not provide redundancy or replace tested backups.