Updates & backups

Back up PostgreSQL and GradePush’s keys together. A database backup alone is not enough to restore encrypted GitHub credentials.

#Make a backup

Run these commands from your installation directory. Check that every command succeeds and that the dump is not empty before relying on the backup.

umask 077
mkdir -p backups
docker compose up -d db
docker compose exec -T db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump --format=custom --no-owner --username="$POSTGRES_USER" "$POSTGRES_DB"' > backups/gradepush.dump
docker compose exec -T app cat /var/lib/gradepush/secret_key_base > backups/secret_key_base
docker compose exec -T app cat /var/lib/gradepush/credential_encryption_key > backups/credential_encryption_key

Store the backup files encrypted with access limited to authorized operators. Keep a copy outside the server. Preserve .env, compose.yaml and the caddy_data and caddy_config volumes as part of your recovery plan.

If SECRET_KEY_BASE or CREDENTIAL_ENCRYPTION_KEY is supplied through an external secret manager, back up that exact value there instead of relying on the generated volume file. A new credential key cannot decrypt an existing database.

#Restore to a separate instance first

The following restore replaces existing objects and data in the configured database. Test it on a separate instance. Use the intended Compose project and its environment, and stop if any command fails.

Place the backup files in backups/ in the recovery installation directory. Use a compatible GradePush image and PostgreSQL version, and restore any externally supplied keys through their secret manager before starting the application.

docker compose up -d db
docker compose stop app
cat backups/gradepush.dump | docker compose exec -T db sh -c 'PGPASSWORD="$POSTGRES_PASSWORD" pg_restore --clean --if-exists --exit-on-error --single-transaction --no-owner --username="$POSTGRES_USER" --dbname="$POSTGRES_DB"'
cat backups/secret_key_base | docker compose run --rm --no-deps --entrypoint sh app -c 'umask 077; cat > /var/lib/gradepush/secret_key_base.tmp && mv /var/lib/gradepush/secret_key_base.tmp /var/lib/gradepush/secret_key_base'
cat backups/credential_encryption_key | docker compose run --rm --no-deps --entrypoint sh app -c 'umask 077; cat > /var/lib/gradepush/credential_encryption_key.tmp && mv /var/lib/gradepush/credential_encryption_key.tmp /var/lib/gradepush/credential_encryption_key'
docker compose up -d app

After restoring, check that you can sign in, open a classroom and access its GitHub repositories.

#Update GradePush

1. Review the release notes and any migration instructions.
2. Take and verify a fresh backup.
3. Update GRADEPUSH_IMAGE in .env to the intended published version. The installation uses a pinned image, so pulling alone does not select a new release.
4. Pull and restart using the same Compose project, files and environment:

docker compose pull
docker compose up -d --wait
docker compose logs --tail=100 app

Startup runs database migrations and stops if a migration fails. Do not delete volumes or change the existing database environment during an update. An older application image may not support the migrated schema; a rollback can require restoring the database and matching keys.