Backup & Restore

📋 Before You Begin

📦 What to Back Up

Two things hold your Tymeslot data, and they need backing up at different intervals. Keep a copy of your .env as well: a restored database is only useful with the same DATA_ENCRYPTION_KEY (or SECRET_KEY_BASE, if you never set one), because stored calendar and video credentials cannot be decrypted without it.

1 Back Up the Database

Run pg_dump inside the container and redirect the output to a timestamped file on the host. The --clean flag makes the dump replace existing tables when you restore it:

docker exec tymeslot su - postgres -c "pg_dump --clean --if-exists tymeslot" \
  > backup-$(date +%Y%m%d-%H%M%S).sql

# Separate database container (docker-compose.with-postgres.yml):
# docker exec tymeslot-postgres pg_dump -U tymeslot --clean --if-exists tymeslot > backup.sql

The command prints nothing, because the dump goes to the file. Confirm the backup is non-empty: ls -lh backup-*.sql.

grep POSTGRES_DB .env
# Then rerun with that database name, e.g.:
docker exec tymeslot su - postgres -c "pg_dump --clean --if-exists mydb" > backup.sql

2 Automate Database Backups

Add a cron job to run the backup every day at 02:00. Open the crontab editor with crontab -e and add the following line. It addresses the container by name, so it works from any directory, whether you started Tymeslot with docker run or Compose:

0 2 * * * docker exec tymeslot \
  su - postgres -c "pg_dump --clean --if-exists tymeslot" \
  > /backups/tymeslot-$(date +\%Y\%m\%d).sql 2>&1

The 2>&1 at the end sends errors to the same file, so a failed dump is still visible: the file holds the error message instead of SQL. Create the /backups directory first: mkdir -p /backups.

Prune old backups automatically

Add a second cron entry that deletes backups older than 30 days, so they do not fill the disk:

0 3 * * * find /backups -name 'tymeslot-*.sql' -mtime +30 -delete

3 Back Up the Data Volume

The tymeslot_data volume holds the uploads directory along with timezone data. Mount it in a temporary Alpine container and create a compressed archive:

docker run --rm \
  -v tymeslot_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/data-$(date +%Y%m%d).tar.gz -C /data .

The archive is written to the current directory, and the command prints nothing when it succeeds. Verify: ls -lh data-*.tar.gz

4 Restore the Database

The database runs inside the Tymeslot container, so the application stays up during the restore. The restore runs as a single transaction: the database switches to the backup's contents in one step, and a restore that fails changes nothing. Restart the container afterwards so the application starts fresh against the restored data. With a separate database container, run the same psql command in tymeslot-postgres as psql -U tymeslot instead.

docker exec tymeslot bin/tymeslot version

docker exec -i tymeslot \
  su - postgres -c "psql -v ON_ERROR_STOP=1 --single-transaction tymeslot" \
  < backup-20260101-020000.sql

docker exec tymeslot su - postgres -c "psql -c 'DROP DATABASE tymeslot WITH (FORCE);'"
docker exec tymeslot su - postgres -c "psql -c 'CREATE DATABASE tymeslot OWNER tymeslot;'"
docker exec -i tymeslot su - postgres -c "psql -v ON_ERROR_STOP=1 --single-transaction tymeslot" < backup-20260101-020000.sql

docker restart tymeslot

5 Restore the Data Volume

Extract the archive back into the Docker volume with a temporary Alpine container:

docker run --rm \
  -v tymeslot_data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/data-20260101.tar.gz -C /data

No output means success. Verify that the files are back by listing the uploads directory: docker run --rm -v tymeslot_data:/data alpine ls /data/uploads

🧪 Test Your Backups

A backup you have never restored is a backup you cannot trust. Automated jobs fail silently: the file exists but holds an error message instead of SQL, or the dump stopped halfway. You do not want to find that out on the day you need it.

Once a month, restore the latest backup into a separate, throwaway container:

1. Start an isolated Postgres container

docker run -d \
  --name tymeslot-restore-test \
  -e POSTGRES_USER=tymeslot \
  -e POSTGRES_PASSWORD=testpassword \
  -e POSTGRES_DB=tymeslot \
  postgres:17-alpine

Wait a few seconds for Postgres to initialise inside the container.

2. Restore the backup into the test container

docker exec -i tymeslot-restore-test \
  psql -U tymeslot tymeslot \
  < backup-20260101-020000.sql

3. Spot-check critical data

Query a key table to confirm data is present:

docker exec -it tymeslot-restore-test \
  psql -U tymeslot tymeslot \
  -c "SELECT COUNT(*) AS user_count FROM users;"

The count should match the number of users on your instance. Zero means the restore failed or the backup holds no users.

4. Clean up the test container

docker rm -f tymeslot-restore-test

❓ Frequently Asked Questions

Verify Your Setup

• Manual backup completes without errors. Run the pg_dump command manually and confirm the output file is non-empty.
• Cron job is scheduled. Run crontab -l and confirm the backup entry is present.
• A test restore succeeds. Follow the test procedure above and confirm the users table contains the expected row count.
• Backups are stored off-server. At least the most recent backup is copied to a remote location outside the production server.
• Old backups are pruned automatically. Confirm the cleanup cron entry is in place, or verify that your off-site storage has a retention policy configured.