sencho/docs/operations/backup.mdx

---
title: Backup & Restore
description: What to back up, how to restore it, and how to migrate Sencho to a new host.
---

Sencho stores all its state in two places: the **data directory** (SQLite database and encryption key) and your **compose directory** (your actual stack files). Both need to be backed up for a complete recovery.

<Note>
  Skipper and Admiral users also have access to [Fleet-Wide Backups](/features/fleet-backups), which snapshot compose files across all nodes directly from the dashboard. This page covers lower-level backup of the Sencho instance itself.
</Note>

---

## What to back up

### 1. Data directory (`DATA_DIR`)

Default path: `/app/data` inside the container, mapped to wherever you mounted it on the host (e.g. `./sencho-data`).

Contains:
- `sencho.db` - SQLite database with all settings, users, nodes, alerts, metrics history, and notification config
- `encryption.key` - Key used to encrypt sensitive values (registry credentials, node API tokens) stored in the database

<Warning>
  Both files are required for a full restore. If you restore `sencho.db` without the matching `encryption.key`, any encrypted values in the database will be unreadable and you will need to re-enter registry credentials and re-generate node API tokens.
</Warning>

### 2. Compose directory (`COMPOSE_DIR`)

The directory containing your stack subdirectories: your `compose.yaml` files, `.env` files, and any bind-mounted config files stored there.

This is your actual application data. It lives entirely outside Sencho and you almost certainly already back it up on a schedule, but include it in any Sencho backup plan.

---

## Backing up

### Simple file copy

```bash
# Stop Sencho to ensure no active transactions (recommended but not strictly required)
docker stop sencho

# Copy the data directory (includes both sencho.db and encryption.key)
cp -r /path/to/sencho-data /path/to/backup/sencho-data-$(date +%Y%m%d)

# Copy compose stacks
cp -r /opt/compose /path/to/backup/compose-$(date +%Y%m%d)

# Restart
docker start sencho
```

<Note>
  Sencho uses SQLite's default journal mode (not WAL), so you will not see `-wal` or `-shm` sidecar files alongside `sencho.db`. If a `-journal` file exists when you copy, it indicates an interrupted write. SQLite will automatically resolve it the next time the database is opened.
</Note>

### SQLite online backup (without stopping)

SQLite supports hot backups via its `.backup` command. This is safe to run while Sencho is running:

```bash
sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho.db'"
```

Remember to also copy `encryption.key` from the same directory.

### Automated daily backup (cron example)

```cron
0 3 * * * cp /path/to/sencho-data/encryption.key /backups/encryption.key && sqlite3 /path/to/sencho-data/sencho.db ".backup '/backups/sencho-$(date +\%Y\%m\%d).db'" && find /backups -name "sencho-*.db" -mtime +30 -delete
```

This copies the encryption key, backs up the database at 3 AM daily, and deletes database backups older than 30 days.

---

## Restoring

### Restore from backup

1. Stop Sencho:
   ```bash
   docker stop sencho
   ```

2. Replace the data directory with your backup:
   ```bash
   rm -rf /path/to/sencho-data/*
   cp /path/to/backup/sencho.db /path/to/sencho-data/sencho.db
   cp /path/to/backup/encryption.key /path/to/sencho-data/encryption.key
   ```

3. Restore your compose directory if needed:
   ```bash
   cp -r /path/to/backup/compose /opt/compose
   ```

4. Start Sencho:
   ```bash
   docker start sencho
   ```

Sencho will read the restored database and resume with all your previous settings, nodes, and alert rules intact.

---

## Migrating to a new host

### Step 1: Prepare the new host

Install Docker and Docker Compose on the new machine. Create the same directory structure you use for your compose files, following the [1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule).

### Step 2: Copy data

Transfer your backup files to the new host:

```bash
scp -r /path/to/sencho-data newhost:/path/to/sencho-data
scp -r /opt/compose newhost:/opt/compose
```

### Step 3: Deploy Sencho on the new host

Use the same `docker-compose.yml` you used on the old host (with the same `COMPOSE_DIR` and `DATA_DIR` paths):

```bash
docker compose up -d
```

### Step 4: Update remote node references

If other Sencho instances were pointing to your old host as a remote node, update their node config to use the new host's IP or hostname. Generate a new API token on the restored instance and distribute it.

### Step 5: Verify

- Log in and confirm your stacks, nodes, and alerts are all present
- Check that at least one stack deploys correctly
- Verify the node switcher shows the expected nodes with green status

---

## What is NOT backed up by this process

| Item | Location | Notes |
|------|----------|-------|
| Container data volumes | Wherever each stack's volumes are mounted on the host | Back these up separately per-application |
| Actual container images | Docker image cache | These are re-pulled on next deploy; no backup needed |
| Sencho logs (docker logs) | Container stdout | Not persisted beyond container lifetime |