---
name: backup
description: Automated backup and restore using restic
metadata:
  version: "1.0.0"
  vibestack:
    main: false
---

# Backup Skill

Automated backup and restore for all VibeStack data using [restic](https://restic.net/).

## Features

- Incremental, encrypted backups
- Multiple backup targets (local, S3, B2, SFTP)
- Scheduled automatic backups via cron
- Retention policy management
- Point-in-time restore
- PostgreSQL-aware backups (pg_dump)

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `BACKUP_SCHEDULE` | `0 3 * * *` | Cron schedule (default: 3am daily) |
| `BACKUP_RETENTION` | `7d` | Retention period |
| `BACKUP_TARGET` | `/backups` | Local backup directory |
| `BACKUP_PASSWORD` | (required) | Encryption password |
| `BACKUP_S3_BUCKET` | (none) | S3 bucket URL (e.g., `s3:bucket-name/path`) |
| `BACKUP_S3_ACCESS_KEY` | (none) | S3 access key |
| `BACKUP_S3_SECRET_KEY` | (none) | S3 secret key |
| `BACKUP_B2_ACCOUNT_ID` | (none) | Backblaze B2 account ID |
| `BACKUP_B2_ACCOUNT_KEY` | (none) | Backblaze B2 account key |
| `BACKUP_B2_BUCKET` | (none) | B2 bucket name |
| `BACKUP_SFTP_HOST` | (none) | SFTP host for remote backup |
| `BACKUP_SFTP_USER` | (none) | SFTP username |
| `BACKUP_SFTP_PATH` | (none) | SFTP path |

## What Gets Backed Up

| Path | Description |
|------|-------------|
| `/data/postgres` | PostgreSQL data (via pg_dump) |
| `/data/redis` | Redis persistence files |
| `/data/duckdb` | DuckDB databases |
| `/data/loki` | Log data |
| `/data/caddy` | TLS certificates |
| `/personalities` | Agent personality configs |
| `/workspaces` | Agent workspaces |

## Usage

### Manual Backup

```bash
# Trigger immediate backup
/skills/backup/scripts/backup.sh

# Backup specific path
/skills/backup/scripts/backup.sh /data/postgres
```

### Manual Restore

```bash
# List available snapshots
/skills/backup/scripts/restore.sh --list

# Restore latest snapshot
/skills/backup/scripts/restore.sh --latest

# Restore specific snapshot
/skills/backup/scripts/restore.sh --snapshot abc123

# Restore specific path
/skills/backup/scripts/restore.sh --latest --path /data/postgres
```

### Check Backup Status

```bash
# Show backup stats
restic -r "$BACKUP_TARGET" stats

# List snapshots
restic -r "$BACKUP_TARGET" snapshots
```

## Backup Targets

### Local (default)

```bash
BACKUP_TARGET=/backups
BACKUP_PASSWORD=your-secret-password
```

### Amazon S3

```bash
BACKUP_TARGET=s3:my-bucket/vibestack-backups
BACKUP_S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
BACKUP_S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
BACKUP_PASSWORD=your-secret-password
```

### Backblaze B2

```bash
BACKUP_TARGET=b2:my-bucket:/vibestack-backups
BACKUP_B2_ACCOUNT_ID=your-account-id
BACKUP_B2_ACCOUNT_KEY=your-account-key
BACKUP_PASSWORD=your-secret-password
```

### SFTP

```bash
BACKUP_TARGET=sftp:user@host:/path/to/backups
BACKUP_SFTP_HOST=backup.example.com
BACKUP_SFTP_USER=backup
BACKUP_PASSWORD=your-secret-password
```

## Retention Policy

The `BACKUP_RETENTION` variable controls how long backups are kept:

| Format | Example | Description |
|--------|---------|-------------|
| `Xd` | `7d` | Keep backups for X days |
| `Xw` | `4w` | Keep backups for X weeks |
| `Xm` | `3m` | Keep backups for X months |

Restic's `forget` command with `--keep-within` is used to enforce retention.

## PostgreSQL Backups

When PostgreSQL is detected, the backup skill:
1. Runs `pg_dump` to create a consistent SQL dump
2. Stores the dump at `/data/postgres/backup.sql`
3. Includes it in the restic backup

This ensures database consistency during backup.

## Monitoring

Backup status is written to `/run/vibestack/backup-status.json`:

```json
{
  "last_backup": "2024-01-15T03:00:00Z",
  "last_status": "success",
  "snapshot_id": "abc123def",
  "duration_seconds": 45,
  "bytes_added": 1048576
}
```

## Security

1. **Always set a strong `BACKUP_PASSWORD`** - backups are encrypted with this
2. Store credentials securely (use environment variables, not files)
3. Test restore procedure regularly
4. Keep backup target separate from primary data