Backup Management

Backups allow you to save snapshots of your server files for safekeeping. You can restore backups to recover from data loss, corruption, or mistakes.

Creating a Backup

Create a new backup of your server:

Create Backup

POST /api/client/servers/{server}/backups
Content-Type: application/json

{
  "name": "Pre-Update Backup",
  "is_locked": false,
  "ignored": "*.log\nnode_modules/\ncache/"
}

Response

{
  "object": "backup",
  "attributes": {
    "uuid": "3e8e8f18-25fa-4f9e-a13d-4d1c8e8b8f9e",
    "name": "Pre-Update Backup",
    "is_successful": false,
    "is_locked": false,
    "ignored_files": [
      "*.log",
      "node_modules/",
      "cache/"
    ],
    "checksum": null,
    "bytes": 0,
    "created_at": "2025-01-15T10:30:00+00:00",
    "completed_at": null
  }
}

Navigate to Backups

Go to the Backups tab in your server panel.

Start Backup

Click “Create Backup” and optionally provide a name.

Configure Ignored Files

Specify files/folders to exclude (logs, caches, etc.) to reduce backup size.

Wait for Completion

The backup runs in the background. Monitor progress in the backups list.

Backup Process

Wings daemon creates a tar.gz archive of server files
Excluded files are skipped based on ignore patterns
Archive is stored locally or uploaded to S3 (based on config)
Checksum is calculated for integrity verification
Backup marked as successful when complete

Backups run in the background and don’t interrupt server operation. Large servers may take several minutes.

Ignoring Files

Exclude files from backups to save space and time:

Example Ignored Files

*.log
*.tmp
cache/
node_modules/
logs/
crash-reports/
backups/
*.jar.old

Patterns use standard glob syntax:

*.log - All .log files
cache/ - Entire cache directory
**/temp/* - Temp directories at any level

Be careful not to exclude important files. When in doubt, include it in the backup.

Listing Backups

View all backups for a server:

List Backups

GET /api/client/servers/{server}/backups?per_page=20

Response

{
  "object": "list",
  "data": [
    {
      "object": "backup",
      "attributes": {
        "uuid": "3e8e8f18-25fa-4f9e-a13d-4d1c8e8b8f9e",
        "name": "Pre-Update Backup",
        "is_successful": true,
        "is_locked": false,
        "checksum": "sha256:a1b2c3d4...",
        "bytes": 456789012,
        "created_at": "2025-01-15T10:30:00+00:00",
        "completed_at": "2025-01-15T10:35:42+00:00"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 5,
      "count": 5,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1
    },
    "backup_count": 5
  }
}

Backup Status

is_successful: false, completed_at: null - In progress
is_successful: true, completed_at: set - Completed successfully
is_successful: false, completed_at: set - Failed

Downloading Backups

Get a download link for a backup:

Get Download URL

GET /api/client/servers/{server}/backups/{backup}/download

Response

{
  "object": "signed_url",
  "attributes": {
    "url": "https://node.example.com:8080/download/backup?token=eyJ0eX..."
  }
}

For S3-stored backups:

S3 Backup

{
  "object": "signed_url",
  "attributes": {
    "url": "https://s3.amazonaws.com/bucket/backups/backup.tar.gz?X-Amz-Expires=..."
  }
}

Download URLs are valid for 15 minutes. Generate a new URL if it expires.

Download via cURL

curl -L -o backup.tar.gz "https://node.example.com:8080/download/backup?token=eyJ0eX..."

Restoring Backups

Restore a backup to your server:

Restore Backup

POST /api/client/servers/{server}/backups/{backup}/restore
Content-Type: application/json

{
  "truncate": true
}

Success

HTTP/1.1 204 No Content

Restoring a backup with truncate: true deletes all existing server files before extracting the backup. This cannot be undone.

Restore Options

Truncate Mode (Clean Restore)

{
  "truncate": true
}

Deletes all files, then extracts backup. Use for full server restoration.

Merge Mode

{
  "truncate": false
}

Extracts backup over existing files. Existing files not in backup are kept.

Confirm Restoration

Ensure you want to restore. This will change server files.

Server Goes Offline

The server status changes to restoring_backup and becomes inaccessible.

Files Extracted

Wings extracts the backup archive to the server directory.

Server Available

Status returns to normal when restoration completes. Start the server.

Restoration Requirements

Server must not be installing or suspended
Backup must be completed successfully
Server will be inaccessible during restoration

If restoration is attempted on an invalid server:

Error Response

HTTP/1.1 400 Bad Request

{
  "errors": [
    {
      "code": "BadRequestHttpException",
      "detail": "This server is not currently in a state that allows for a backup to be restored."
    }
  ]
}

Locking Backups

Locked backups cannot be deleted:

Toggle Lock

POST /api/client/servers/{server}/backups/{backup}/lock

Response

{
  "object": "backup",
  "attributes": {
    "uuid": "3e8e8f18-25fa-4f9e-a13d-4d1c8e8b8f9e",
    "is_locked": true
  }
}

Lock important backups to prevent accidental deletion:

Pre-update backups
Known good states
Milestone backups

Requires backup.delete permission to lock/unlock backups. Users without this permission cannot set locks when creating backups.

Deleting Backups

Remove a backup permanently:

Delete Backup

DELETE /api/client/servers/{server}/backups/{backup}

Success

HTTP/1.1 204 No Content

Deleting a backup is permanent. The backup file is removed from storage and cannot be recovered.

Locked backups cannot be deleted:

Locked Backup Error

HTTP/1.1 400 Bad Request

{
  "errors": [
    {
      "detail": "Cannot delete a locked backup."
    }
  ]
}

Backup Limits

Servers have a maximum number of backups:

Check Limit

GET /api/client/servers/{server}

Response

{
  "attributes": {
    "feature_limits": {
      "backups": 3
    }
  }
}

Attempting to create more than allowed:

Error Response

HTTP/1.1 400 Bad Request

{
  "errors": [
    {
      "code": "TooManyBackupsException",
      "detail": "This server has reached its backup limit."
    }
  ]
}

Failed backups count toward the limit. Delete failed backups to free up slots.

Storage Adapters

Backups can be stored in different locations:

Wings Local Storage

{
  "attributes": {
    "disk": "wings"
  }
}

Stored on the node’s filesystem. Fast but limited by disk space.

AWS S3

{
  "attributes": {
    "disk": "s3"
  }
}

Stored in Amazon S3 bucket. Unlimited storage, slower uploads.

Storage adapter is configured by administrators. Users cannot choose where backups are stored.

Automated Backups

Create backups automatically using schedules: Schedule: 0 2 * * * (Daily at 2 AM) Task:

{
  "action": "backup",
  "payload": "",
  "time_offset": 0
}

See Task Scheduling for more details.

Backup Best Practices

Regular Backup Schedule

Set up automated daily or weekly backups. More frequent backups for active servers:

Production servers: Daily backups
Development servers: Weekly backups
Before updates: Manual backup

Test Restorations

Periodically test restoring backups to ensure they work:

Download a backup
Create a test server
Restore the backup
Verify files and functionality

Lock Important Backups

Lock backups of known good states:

Before major updates
After successful migrations
Milestone versions

Exclude Unnecessary Files

Reduce backup size and time by excluding:

Log files (*.log)
Cache directories
Temporary files
Old backup files

Download Critical Backups

Keep local copies of important backups:

# Download backup
curl -o backup-$(date +%Y%m%d).tar.gz "$DOWNLOAD_URL"

# Store on external storage
cp backup-*.tar.gz /mnt/external/backups/

Activity Logging

Backup operations are logged:

Example Logs

{
  "event": "server:backup.start",
  "properties": {
    "name": "Pre-Update Backup",
    "locked": false
  }
}

{
  "event": "server:backup.download",
  "properties": {
    "name": "Pre-Update Backup"
  }
}

{
  "event": "server:backup.restore",
  "properties": {
    "name": "Pre-Update Backup",
    "truncate": true
  }
}

{
  "event": "server:backup.delete",
  "properties": {
    "name": "Old Backup",
    "failed": false
  }
}

Troubleshooting

Backup Fails to Complete

Check available disk space on node
Verify Wings daemon is running
Review Wings logs for errors
Try excluding more files to reduce size
Check S3 credentials if using S3 storage

Cannot Download Backup

Verify backup completed successfully
Check network connectivity to node/S3
Generate a new download URL
For S3 backups, verify IAM permissions

Restoration Stuck

Check Wings daemon status
Review Wings logs for extraction errors
Verify backup file isn’t corrupted (checksum)
Ensure sufficient disk space
Contact administrator if issue persists

Backup Limit Reached

You’ve hit the maximum backups for your server:

Delete old or failed backups
Download important backups before deleting
Request limit increase from admin
Use automated cleanup (delete backups older than X days)

Advanced: Manual Backup Extraction

Backups are standard tar.gz archives:

# Extract backup locally
tar -xzf backup.tar.gz

# List contents without extracting
tar -tzf backup.tar.gz

# Extract specific file
tar -xzf backup.tar.gz path/to/file.txt

# Verify integrity
sha256sum backup.tar.gz

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

Creating a Backup

Backup Process

Ignoring Files

Listing Backups

Backup Status

Downloading Backups

Download via cURL

Restoring Backups

Restore Options

Truncate Mode (Clean Restore)

Merge Mode

Restoration Requirements

Locking Backups

Deleting Backups

Backup Limits

Storage Adapters

Wings Local Storage

AWS S3

Automated Backups

Backup Best Practices

Activity Logging

Troubleshooting

Advanced: Manual Backup Extraction

Build docs developers (and LLMs) love

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Creating a Backup

​Backup Process

​Ignoring Files

​Listing Backups

​Backup Status

​Downloading Backups

​Download via cURL

​Restoring Backups

​Restore Options

​Truncate Mode (Clean Restore)

​Merge Mode

​Restoration Requirements

​Locking Backups

​Deleting Backups

​Backup Limits

​Storage Adapters

​Wings Local Storage

​AWS S3

​Automated Backups

​Backup Best Practices

​Activity Logging

​Troubleshooting

​Advanced: Manual Backup Extraction

Build docs developers (and LLMs) love

Creating a Backup

Backup Process

Ignoring Files

Listing Backups

Backup Status

Downloading Backups

Download via cURL

Restoring Backups

Restore Options

Truncate Mode (Clean Restore)

Merge Mode

Restoration Requirements

Locking Backups

Deleting Backups

Backup Limits

Storage Adapters

Wings Local Storage

AWS S3

Automated Backups

Backup Best Practices

Activity Logging

Troubleshooting

Advanced: Manual Backup Extraction