Backup & Restore

FlatRun provides comprehensive backup functionality for your deployments, including scheduled backups, selective file inclusion, and one-click restoration.

Backup Overview

Backups in FlatRun capture:

• Configuration files — docker-compose.yml, service.yml, .env files
• Application data — Mounted volumes and data directories
• Database dumps — MySQL, PostgreSQL exports (when configured)

Backup Storage

Backups are stored within the deployments directory structure. No separate configuration is required — backups are enabled by default.

Storage Location

Backups are stored at:

${deployments_path}/.flatrun/backups/

For example, if your deployments_path is /var/flatrun/deployments, backups will be stored in:

/var/flatrun/deployments/.flatrun/backups/
├── my-wordpress/
│   ├── my-wordpress_20240115_120000.tar.gz
│   └── my-wordpress_20240114_120000.tar.gz
└── my-laravel/
    └── my-laravel_20240115_140000.tar.gz

Backup Features

• Automatic compression — All backups use gzip compression
• Pre/post hooks — Execute commands before and after backups
• Selective backup — Choose which components to include
• Async operations — Backups run in the background

Creating Backups

Via API

curl -X POST "http://localhost:8090/api/backups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "my-wordpress"
  }'

Response

{
  "job_id": "backup-123456",
  "message": "Backup job started"
}

Backups run asynchronously. Use the job ID to check status:

curl "http://localhost:8090/api/backups/jobs/backup-123456" \
  -H "Authorization: Bearer $TOKEN"

Backup Options

Customize what's included in a backup:

curl -X POST "http://localhost:8090/api/backups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "my-wordpress",
    "include_files": true,
    "include_database": true,
    "exclude_patterns": ["*.log", "cache/*"],
    "description": "Pre-upgrade backup"
  }'

Listing Backups

# List all backups
curl "http://localhost:8090/api/backups" \
  -H "Authorization: Bearer $TOKEN"

# List backups for specific deployment
curl "http://localhost:8090/api/deployments/my-wordpress/backups" \
  -H "Authorization: Bearer $TOKEN"

Backup Storage

Backups are stored as compressed archives:

/var/flatrun/backups/
├── my-wordpress/
│   ├── backup-2024-01-15-120000.tar.gz
│   ├── backup-2024-01-14-120000.tar.gz
│   └── backup-2024-01-13-120000.tar.gz
└── my-laravel/
    └── backup-2024-01-15-140000.tar.gz

Backup Archive Contents

backup-2024-01-15-120000.tar.gz
├── metadata.json       # Backup metadata
├── docker-compose.yml  # Compose file
├── service.yml         # Service configuration
├── .env               # Environment variables
├── data/              # Application data
└── database.sql       # Database dump (if applicable)

Restoring from Backup

Via API

curl -X POST "http://localhost:8090/api/backups/backup-123/restore" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_name": "my-wordpress",
    "restore_database": true,
    "restore_files": true
  }'

Restore Options

Scheduled Backups

Configure automatic backups using the scheduler. See Cron Jobs for details.

Example: Daily Backup Schedule

curl -X POST "http://localhost:8090/api/scheduler/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "my-wordpress",
    "task_type": "backup",
    "cron_expr": "0 2 * * *",
    "description": "Daily backup at 2 AM"
  }'

Deployment Backup Configuration

Configure backup settings per deployment:

curl -X PUT "http://localhost:8090/api/deployments/my-wordpress/backup-config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "schedule": "0 2 * * *",
    "retention": 7,
    "include_database": true,
    "exclude_patterns": ["*.log", "cache/*"]
  }'

Downloading Backups

Download a backup archive:

curl -o backup.tar.gz \
  "http://localhost:8090/api/backups/backup-123/download" \
  -H "Authorization: Bearer $TOKEN"

Deleting Backups

curl -X DELETE "http://localhost:8090/api/backups/backup-123" \
  -H "Authorization: Bearer $TOKEN"

Database Backup Integration

When include_databases is enabled, FlatRun automatically detects and dumps databases:

MySQL/MariaDB

Uses mysqldump via the database container.

PostgreSQL

Uses pg_dump via the database container.

Backup Best Practices

• Test restores regularly — Verify backups are working before you need them
• Exclude unnecessary files — Logs and caches don't need to be backed up
• Off-site storage — Copy critical backups to external storage
• Pre-upgrade backups — Always backup before major changes
• Monitor backup jobs — Check job status to ensure backups complete

Monitoring Backup Jobs

# List all backup/restore jobs
curl "http://localhost:8090/api/backups/jobs" \
  -H "Authorization: Bearer $TOKEN"

# Get specific job status
curl "http://localhost:8090/api/backups/jobs/backup-123456" \
  -H "Authorization: Bearer $TOKEN"

Job statuses:

• pending — Job is queued
• running — Job is in progress
• completed — Job finished successfully
• failed — Job encountered an error