npm package: @funspectre/wharf
Description: Docker migration tool for backing up and restoring images and volumes
Author: Tobalase
Latest version: 0.1.5

# Wharf

A Docker migration tool for backing up and restoring Docker images and volumes
between platforms.

## Overview

Wharf enables complete Docker installation migration between platforms (e.g.,
Docker Desktop to Rancher Desktop, or between machines) by backing up and
restoring both **images** and **volumes**.

## Installation

### Package Managers

```bash
# pnpm (recommended)
pnpm add -g @funspectre/wharf

# npm
npm install -g @funspectre/wharf

# JSR (Deno)
deno install -A jsr:@funspectre/wharf
```

### Pre-built Binaries

Download the latest binary for your platform from the
[GitLab Releases](https://gitlab.com/tobalase/wharf/-/releases) page.

| Platform | Architecture          | Binary                    |
| -------- | --------------------- | ------------------------- |
| macOS    | Apple Silicon (arm64) | `wharf-macos-arm64`       |
| macOS    | Intel (x64)           | `wharf-macos-x64`         |
| Linux    | arm64                 | `wharf-linux-arm64`       |
| Linux    | x64                   | `wharf-linux-x64`         |
| Windows  | arm64                 | `wharf-windows-arm64.exe` |
| Windows  | x64                   | `wharf-windows-x64.exe`   |

After downloading, make the binary executable (macOS/Linux):

```bash
chmod +x wharf-*
```

### From Source

```bash
# Clone the repository
git clone https://gitlab.com/tobalase/wharf.git
cd wharf

# Run with Deno
deno run --allow-all index.mjs

# Or compile your own binary
deno compile --allow-all --output=wharf index.mjs
```

## Requirements

- [Docker](https://docs.docker.com/get-docker/)
- [zstd](https://github.com/facebook/zstd) (for compression)

## Quick Start

```bash
# Backup all images and volumes
wharf backup

# Restore on another machine
wharf restore
```

## Usage

```bash
./wharf <command> [options]
```

### Commands

| Command   | Description                                               |
| --------- | --------------------------------------------------------- |
| `backup`  | Backup Docker images and volumes to `./data` directory    |
| `restore` | Restore Docker images and volumes from `./data` directory |

### Options

| Option                   | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `-p, --pretend`          | Show what would be done without making changes |
| `-v, --verbose`          | Show detailed output                           |
| `--commit`               | Commit running containers before backup        |
| `-f, --filter <pattern>` | Only backup/restore items matching pattern     |
| `--include-anonymous`    | Include anonymous volumes (64-char hex names)  |

## Examples

```bash
# Preview what would be backed up
./wharf backup --pretend

# Backup with verbose output
./wharf backup --verbose

# Backup only nginx-related images/volumes
./wharf backup --filter nginx

# Restore all images and volumes
./wharf restore

# Restore only postgres-related items
./wharf restore --filter postgres
```

## Migration Workflow

1. **On source machine:**
   ```bash
   ./wharf backup
   ```

2. **Copy data/ directory to target machine**

3. **On target machine:**
   ```bash
   ./wharf restore
   ```

## Data Format

Backups are stored in the `data/` directory:

```
data/
  metadata.json           # Backup metadata and filename mappings
  images/
    <image>.tar.zst       # Compressed image archives
  volumes/
    <volume>.tar.zst      # Compressed volume data
    <volume>.meta.json    # Volume metadata (driver, labels, options)
```

## Documentation

See the `docs/` directory for detailed documentation:

- [Getting Started](docs/getting-started.md)
- [Backup Command](docs/backup.md)
- [Restore Command](docs/restore.md)
- [Migration Guide](docs/migration-guide.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Architecture](docs/architecture.md)

## License

MIT