Deployment
Backup and restore
Back up application data, uploaded files, and required configuration before upgrades, migrations, or infrastructure changes.
Docker Compose
Review persistent resources and Compose project identity.
Environment variables
Identify deployment configuration and stable security values.
Upgrades
Use backups as the recovery point for version changes.
Troubleshooting
Diagnose recovery and persistent-storage failures.
What to back up
| Resource | Why it matters |
|---|---|
| PostgreSQL | Stores community records, memberships, settings, events, audit information, message metadata, and other persistent application data. |
| Uploads | Stores avatars, event and task files, and encrypted chat attachment objects referenced by database records. |
| Deployment configuration | Preserves `.env`, the selected release, the public hostname, and stable security values needed by restored data. |
| Caddy state | Optionally preserves certificate and proxy state; certificates can normally be issued again when DNS and public access are correct. |
| Redis state | Contains queued and temporary operational state, not the authoritative community database. Preserve it only as part of a coordinated recovery plan. |
Stable security values
Protect the `.env` backup as sensitive data. Restore the values that were active when the backup was created; never print them in support logs or documentation.
| Value | Recovery consequence |
|---|---|
| PASSWORD_PEPPER and PASSWORD_PEPPER_PREVIOUS | Required to verify existing account passwords, including an in-progress pepper rotation. |
| EMAIL_ENCRYPTION_KEY | Required to decrypt protected SMTP and registration-provider credentials saved in the database. |
| JWT_SECRET and session settings | Changing them invalidates existing signed sessions and may also affect protected credentials when EMAIL_ENCRYPTION_KEY was not set separately. |
| REGISTRATION_KEY_HASH_SECRET | Preserves continuity for privacy-safe registration rate-limit identifiers when configured. |
| OWNER_BREAK_GLASS_SECRET | Preserve it only when the operator intends to keep the same optional server-side recovery control. |
Create a consistent backup
PostgreSQL supports an online logical backup. For the most consistent database-and-uploads recovery point, use a maintenance window and pause services that accept writes before capturing both resources. PE Community does not provide a built-in maintenance mode.
docker compose stop caddy web worker apiBack up PostgreSQL
Create a PostgreSQL custom-format archive. Store the resulting file outside the production server and protect it as personal data.
docker compose exec -T postgres pg_dump -U pe -d pe_community --format=custom > pe-community.dumpBack up uploads
Archive the mounted uploads directory through a temporary application container. This reads the named volume without editing Docker volume files directly.
After the PostgreSQL and uploads archives complete successfully, run `docker compose up -d` to end the maintenance window.
docker compose run --rm --no-deps -T api tar -C /app/uploads -czf - . > pe-community-uploads.tar.gzRestore an installation
- 1. Select the application release that matches the backup, or another release explicitly documented as compatible.
- 2. Restore `.env`, including the original stable security values, and keep the Compose project name unchanged.
- 3. Start PostgreSQL and Redis without starting the application services.
- 4. Restore the PostgreSQL archive into a new or intentionally prepared target database.
- 5. Restore the matching uploads archive into a new or intentionally prepared uploads volume.
- 6. Start the complete deployment. Pending migrations run during application startup when moving through a supported upgrade path.
- 7. Validate sign-in, account security, uploaded files, realtime features, background work, and configured email delivery.
docker compose up -d postgres redis
docker compose exec -T postgres pg_restore -U pe -d pe_community --no-owner < pe-community.dump
docker compose run --rm --no-deps -T api tar -C /app/uploads -xzf - < pe-community-uploads.tar.gz
docker compose up -dRecovery boundaries
- Restore a backup into a compatible release, then follow release-specific upgrade guidance before moving to a newer version.
- Server backups do not contain members’ browser private chat keys or recovery passwords. Members must preserve their own encrypted chat-key backups.
- Keep the Compose project name unchanged; Docker Compose explains how project identity selects persistent resources.
Verify and retain backups
- A backup is not verified until it has been restored successfully in a controlled environment.
- Keep multiple restore points and store copies separately from the production server.
- Encrypt backups that contain secrets, personal data, or protected operational configuration.
- Test recovery periodically and record the compatible application release for each restore point.