Backup and Restore

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/backup.sh
• deployment_guide.md
• README.md
• blueprint.md
• services/api/prisma/migrations/0002_abuse_controls/migration.sql

Introduction

The Email Platform includes a backup and restore mechanism primarily focused on safeguarding the PostgreSQL database, which contains all critical application data such as users, domains, inboxes, and message metadata. The core of this system is the scripts/backup.sh shell script, which leverages Docker and standard database tools to create portable backups.

This system is designed to be run manually or automated via cron jobs. It supports storing backups locally, uploading them to an S3-compatible object store, and performing automated cleanup of old files. The restore process is a manual operation requiring command-line access to the server. While the script handles the database, it's important to note that attachment files stored on disk or in an object store require a separate backup strategy.

Sources: README.md:121-123, deployment_guide.md:120-122, blueprint.md:144

Backup Process

The backup process is orchestrated by the scripts/backup.sh script. It identifies the running PostgreSQL Docker container, executes pg_dump to create a SQL dump of the email_service database, compresses it with gzip, and saves it to the backups/ directory.

Sources: scripts/backup.sh:68-75

Backup Flow

The following diagram illustrates the sequence of operations performed by the backup.sh script.

Configuration

The script's behavior can be modified using command-line arguments or environment variables.

Parameter	Environment Variable	Argument	Description	Default Value
Retention Period		--keep-days N	Number of days to retain local backup files.	7
S3 Upload		--upload-s3	A flag to enable uploading the backup file to S3.	false
S3 Bucket	S3_BACKUP_BUCKET		The name of the S3 bucket to upload backups to.	"" (empty)
Container Name			The name of the PostgreSQL container.	email-postgres-1

Sources: scripts/backup.sh:22-27, scripts/backup.sh:32-44

Manual Execution

To perform a manual backup, grant execute permissions to the script and run it.

# Grant execute permission
chmod +x scripts/backup.sh

# Run a manual backup
./scripts/backup.sh

# Run a backup with S3 upload
S3_BACKUP_BUCKET=my-backup-bucket ./scripts/backup.sh --upload-s3

Sources: deployment_guide.md:124-127, deployment_guide.md:136-139

Automation with Cron

For automated, periodic backups, a cron job can be configured to execute the backup.sh script. The example below sets up a backup to run every 6 hours.

1. Open the crontab editor:

   crontab -e
   

2. Add the following line, adjusting the path to your project directory:

   0 */6 * * * /path/to/email-platform/scripts/backup.sh >> /var/log/email-backup.log 2>&1
   

This configuration runs the backup script at the start of every 6th hour and appends the output to a log file.

Sources: deployment_guide.md:130-134

Restore Process

Restoring from a backup is a manual process that involves decompressing the backup file and importing it into the PostgreSQL database using psql.

Sources: README.md:124-125, deployment_guide.md:143-147

Restore Flow

The following diagram outlines the steps to restore the database from a backup file.

Restore Commands

Execute the following commands on the server hosting the application.

# 1. Decompress the backup file
gunzip backups/email_platform_YYYYMMDD_HHMMSS.sql.gz

# 2. Restore the database by piping the SQL file into the container
docker-compose exec -T postgres psql -U postgres -d email_service < backups/email_platform_YYYYMMDD_HHMMSS.sql

The -T flag for docker-compose exec is important as it disables pseudo-tty allocation, which is necessary when using input redirection.

Sources: deployment_guide.md:144-147

Data Under Backup

The backup.sh script is designed to back up the PostgreSQL database only. This includes all relational data critical to the application's operation.

Database Schema

The database contains tables for managing users, domains, messages, and system configurations. The diagram below shows the relationships between key entities.

Excluded Data: Attachments

The backup.sh script does not back up email attachments. Attachments are stored separately on the filesystem or in an S3-compatible object store. A complete disaster recovery plan must include a separate process for backing up the attachment storage location.

Sources: README.md:41, README.md:122-123

Summary

The email-platform provides a robust, script-based solution for PostgreSQL database backups. The backup.sh script is configurable, supports local and S3 storage, and can be easily automated with cron. The restore process is straightforward but manual. A comprehensive backup strategy must also account for backing up the attachment storage directory, which is outside the scope of the provided script.

Sources: README.md:121-123, deployment_guide.md:120-147