Tusile does not ship a one-click backup UI. Operators use standard tools: PostgreSQL dumps for the database and a copy of uploaded files (Docker volume or S3 bucket). Match database and files to the same point in time when possible so attachment paths stay valid.

What to back up

• Database — Channels, messages, roles, invites, and metadata live in Postgres. A logical dump (pg_dump) is enough for backup and migration.
• Files (local storage) — With the default STORAGE_BACKEND=local, uploads are in the Docker volume mounted at /app/uploads inside the community-server container (see Configuration for STORAGE_LOCAL_PATH).
• Files (S3) — If you use STORAGE_BACKEND=s3, uploads are in your bucket. Use your provider’s replication, versioning, or export tools; the community-uploads volume is not the source of truth.

Compose project and volume names

The project name comes from COMPOSE_PROJECT_NAME in .env, which the setup script writes for new installs as community-<hash>. Named volumes are therefore prefixed with it: community-<hash>_community-pgdata, community-<hash>_community-uploads. Run docker volume ls to see the exact names.

Deployments installed before that change have no COMPOSE_PROJECT_NAME line, and compose falls back to community-${SERVER_TOKEN} — so their volumes look like community-<token>_community-pgdata. That fallback is kept on purpose: the project name decides which volumes the stack attaches to, so adding the line to an existing .env would orphan your database and uploads. Leave it alone.

Either way, run all docker compose commands from the same directory and .env you use in production so the project name matches.

Default Postgres credentials in the sample compose are user tusile_community, database tusile_community. If you changed the password or user in compose, use those values in the commands below.

Backup (export)

Database

From the directory that contains your docker-compose.yml, with the stack running:

Custom format (recommended for restore with pg_restore):

docker compose exec -T postgres pg_dump -U tusile_community -d tusile_community -Fc > tusile_community.dump

Plain SQL (restore with psql):

docker compose exec -T postgres pg_dump -U tusile_community -d tusile_community --clean --if-exists > tusile_community.sql

Store dump files securely; they contain community data. On Windows PowerShell, > file.dump works with -T on docker compose exec; alternatively run the same commands from Git Bash or WSL.

Local uploads volume

Replace community-YOURTOKEN_community-uploads with the volume name from docker volume ls:

docker run --rm -v community-YOURTOKEN_community-uploads:/data -v "$(pwd):/backup" alpine tar czf /backup/uploads.tgz -C /data .

On Windows without a Unix shell, use docker volume inspect to find the mountpoint and archive that folder with your preferred tool, or run the one-liner from WSL/Git Bash.

Restore on a fresh install

1. Deploy a new host or directory with the same configuration as before: especially SERVER_TOKEN, COMMUNITY_PUBLIC_URL, CORE_SERVER_URL, and LiveKit keys, so the server re-registers as the same community.
2. Bring up Postgres only, or stop the community-server service so nothing writes to the database during restore:

   docker compose up -d postgres

3. Custom-format dump: copy the file into the container (or use stdin), then restore:

   docker compose cp tusile_community.dump postgres:/tmp/tusile_community.dump
   docker compose exec postgres pg_restore --clean --if-exists -U tusile_community -d tusile_community /tmp/tusile_community.dump

4. Plain SQL:

   docker compose exec -T postgres psql -U tusile_community -d tusile_community < tusile_community.sql

5. Restore uploads into the new community-uploads volume (empty the volume first if you recreated the stack). Example using a temporary container:

   docker run --rm -v community-YOURTOKEN_community-uploads:/data -v "$(pwd):/backup" alpine sh -c "cd /data && tar xzf /backup/uploads.tgz"

6. Start the full stack: docker compose up -d. The community server runs migrations on startup; with a restored DB, migrations should be no-ops or incremental fixes.

Moving between versions

Community server (application)

Pull a newer image (for example karolrzotki/tusile-community-server:latest), then docker compose up -d. Schema migrations run automatically when the process starts. Always take a fresh database dump (and file backup) before upgrading.

PostgreSQL major version

Upgrading the Postgres container major version (for example 16 → 17) is not a simple image tag change. Prefer: dump with the old major version, start a new empty data directory with the new major version, restore the dump, then point compose at the new volume. Test in a copy of your environment first.

Last updated: 2026-03-22.