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

Docker Compose sets the project name from SERVER_TOKEN (community-${SERVER_TOKEN}). Named volumes therefore look like community-<token>_community-pgdata and community-<token>_community-uploads. 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.