Restore Backup

Restore a server from a backup archive

Endpoint

POST /api/servers/:server/backup/:backup/restore

Authentication

Requires Bearer token authentication via the Authorization header.

Path Parameters

server · string · required

The UUID of the server

backup · string · required

The UUID of the backup to restore

Request Body

adapter · string · required

Backup storage adapter. Valid values: wings (local) or s3

truncate_directory · boolean · default: "false"

Whether to delete all existing files before restoring the backup

download_url · string

Required for S3 backups. Pre-signed URL to download the backup from S3.

Response

Returns 202 Accepted immediately. The restoration process continues asynchronously in the background.

Example Request

cURL - Local Backup

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup/550e8400-e29b-41d4-a716-446655440000/restore" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter": "wings",
    "truncate_directory": true
  }'

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup/550e8400-e29b-41d4-a716-446655440000/restore" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter": "s3",
    "truncate_directory": true,
    "download_url": "https://s3.amazonaws.com/bucket/backup-550e8400.tar.gz?presigned-params"
  }'

await fetch(
  'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup/550e8400-e29b-41d4-a716-446655440000/restore',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      adapter: 'wings',
      truncate_directory: false
    })
  }
);

import requests

requests.post(
    'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/backup/550e8400-e29b-41d4-a716-446655440000/restore',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'adapter': 'wings',
        'truncate_directory': True
    }
)

Restoration Process

1. Server State Update

   Server is marked as “restoring” to prevent modifications during restoration.

2. Optional Truncation

   If truncate_directory: true, all existing files in the server directory are deleted.

   This is irreversible. All current server data will be lost.

3. Backup Retrieval

   Local (wings) adapter:

   • Locates backup in configured backup directory
   • Verifies backup file exists

   S3 adapter:

   • Downloads backup from provided download_url
   • Streams download directly to extraction (no disk buffering)
   • Validates Content-Type is application/x-gzip or application/gzip
4. Archive Extraction

   • Extracts tar.gz archive to server directory
   • Preserves file permissions and timestamps
   • Overwrites existing files
5. Completion

   • Server state updated to normal
   • WebSocket event published
   • Panel notified of completion

WebSocket Events

Restoration progress is published via WebSocket:

{
  "event": "daemon message",
  "args": ["Starting restoration process for server backup using local driver"]
}

{
  "event": "backup restore completed",
  "args": [""]
}

Behavior

• Restoration runs asynchronously in the background
• Server state is set to “restoring” during the process
• Existing files are preserved unless truncate_directory: true
• Files in the backup overwrite existing files with the same path
• Directory structure from backup is recreated
• Server remains stopped during restoration (if running, stop it first)

The restoration endpoint returns immediately with 202 Accepted. Use WebSocket events to monitor progress.

Error Responses

400 Bad Request

Missing download_url for S3 backup or invalid Content-Type

401 Unauthorized

Missing or invalid Bearer token

404 Not Found

Server or backup does not exist

500 Internal Server Error

Failed to restore backup (corrupted archive, disk full, etc.)

Best Practices

1. Always stop the server before restoring to prevent file conflicts
2. Use truncate_directory: true for complete restoration to avoid mixing old and new files
3. Create a backup before restoring to have a rollback option
4. Monitor disk space - restoration requires temporary space for extraction
5. Verify backup integrity in the Panel before restoring

Source Reference

Implementation: router/router_server_backup.go:68-172 (postServerRestoreBackup function)