volt/docs/bundles.md

# Volt Bundles

`volt bundle` manages portable, self-contained application bundles. A bundle packages everything needed to deploy a stack — container images, VM disk images, a Constellation definition, configuration, and lifecycle hooks — into a single `.vbundle` file.

## Quick Start

```bash
# Create a bundle from your Constellation
volt bundle create -o my-stack.vbundle

# Inspect a bundle
volt bundle inspect my-stack.vbundle

# Deploy a bundle
volt bundle import my-stack.vbundle

# Export a running stack as a bundle
volt bundle export my-stack -o my-stack.vbundle
```

## Bundle Format

A `.vbundle` is a ZIP archive with this structure:

```
my-stack.vbundle
├── bundle.json           # Bundle manifest (version, platforms, service inventory, hashes)
├── compose.yaml          # Constellation definition / Voltfile (service topology)
├── images/               # Container/VM images per service
│   ├── web-proxy/
│   │   ├── linux-amd64.tar.gz
│   │   └── linux-arm64.tar.gz
│   ├── api-server/
│   │   └── linux-amd64.tar.gz
│   └── db-primary/
│       └── linux-amd64.qcow2
├── config/               # Per-service configuration overlays (optional)
│   ├── web-proxy/
│   │   └── nginx.conf
│   └── api-server/
│       └── .env.production
├── signatures/           # Cryptographic signatures (optional)
│   └── bundle.sig
└── hooks/                # Lifecycle scripts (optional)
    ├── pre-deploy.sh
    └── post-deploy.sh
```

## Bundle Manifest (`bundle.json`)

The bundle manifest describes the bundle contents, target platforms, and integrity information:

```json
{
  "version": 1,
  "name": "my-stack",
  "bundleVersion": "1.2.0",
  "created": "2025-07-14T15:30:00Z",
  "platforms": [
    { "os": "linux", "arch": "amd64" },
    { "os": "linux", "arch": "arm64" },
    { "os": "android", "arch": "arm64-v8a" }
  ],
  "services": {
    "web-proxy": {
      "type": "container",
      "images": {
        "linux/amd64": {
          "path": "images/web-proxy/linux-amd64.tar.gz",
          "format": "oci",
          "size": 52428800,
          "digest": "blake3:a1b2c3d4..."
        }
      }
    }
  },
  "integrity": {
    "algorithm": "blake3",
    "files": { "compose.yaml": "blake3:1234...", "..." : "..." }
  }
}
```

## Multi-Architecture Support

A single bundle can contain images for multiple architectures. During import, Volt selects the right image for the host:

```bash
# Build a multi-arch bundle
volt bundle create --platforms linux/amd64,linux/arm64,android/arm64-v8a -o my-stack.vbundle
```

### Supported Platforms

| OS | Architecture | Notes |
|----|-------------|-------|
| Linux | `amd64` (x86_64) | Primary server platform |
| Linux | `arm64` (aarch64) | Raspberry Pi 4+, ARM servers |
| Linux | `armv7` | Older ARM SBCs |
| Android | `arm64-v8a` | Modern Android devices |
| Android | `armeabi-v7a` | Older 32-bit Android |
| Android | `x86_64` | Emulators, Chromebooks |

## Image Formats

| Format | Extension | Type | Description |
|--------|-----------|------|-------------|
| `oci` | `.tar`, `.tar.gz` | Container | OCI/Docker image archive |
| `rootfs` | `.tar.gz` | Container | Plain filesystem tarball |
| `qcow2` | `.qcow2` | VM | QEMU disk image |
| `raw` | `.raw`, `.img` | VM | Raw disk image |

## CAS Integration

Instead of embedding full images, bundles can reference Stellarium CAS hashes for deduplication:

```bash
# Create bundle with CAS references (smaller, requires CAS access to deploy)
volt bundle create --cas -o my-stack.vbundle
```

In the bundle manifest, CAS-referenced images have `path: null` and a `casRef` field:

```json
{
  "path": null,
  "format": "oci",
  "digest": "blake3:a1b2c3d4...",
  "casRef": "stellarium://a1b2c3d4..."
}
```

During import, Volt resolves CAS references from the local store or pulls from remote peers.

## Commands

### `volt bundle create`

Build a bundle from a Voltfile or running composition.

```bash
# From Constellation in current directory
volt bundle create -o my-stack.vbundle

# Multi-platform, signed
volt bundle create \
  --platforms linux/amd64,linux/arm64 \
  --sign --sign-key ~/.config/volt/signing-key \
  -o my-stack.vbundle

# From a running stack
volt bundle create --from-running my-stack -o snapshot.vbundle

# ACE-compatible (for Android deployment)
volt bundle create --format ace --platforms android/arm64-v8a -o my-stack.zip

# Dry run
volt bundle create --dry-run
```

### `volt bundle import`

Deploy a bundle to the local system.

```bash
# Basic import
volt bundle import my-stack.vbundle

# With verification and hooks
volt bundle import --verify --run-hooks prod.vbundle

# With environment overrides
volt bundle import --set DB_PASSWORD=secret --set APP_ENV=staging my-stack.vbundle

# Import without starting
volt bundle import --no-start my-stack.vbundle

# Force overwrite existing
volt bundle import --force my-stack.vbundle
```

### `volt bundle export`

Export a running composition as a bundle.

```bash
# Export running stack
volt bundle export my-stack -o my-stack.vbundle

# Include volume data
volt bundle export my-stack --include-volumes -o full-snapshot.vbundle
```

### `volt bundle inspect`

Show bundle contents and metadata.

```bash
$ volt bundle inspect my-stack.vbundle
Bundle: my-stack v1.2.0
Created: 2025-07-14 15:30:00 UTC
Platforms: linux/amd64, linux/arm64
Signed: Yes (ed25519)

Services:
  NAME          TYPE        IMAGES            CONFIG FILES   SIZE
  web-proxy     container   2 (amd64, arm64)  1              95 MB
  api-server    container   1 (amd64)         1              210 MB
  db-primary    vm          1 (amd64)         1              2.1 GB

# Show full bundle manifest
volt bundle inspect my-stack.vbundle --show-manifest

# JSON output
volt bundle inspect my-stack.vbundle -o json
```

### `volt bundle verify`

Verify signatures and content integrity.

```bash
$ volt bundle verify prod.vbundle
✓ Bundle signature valid (ed25519, signer: karl@armoredgate.com)
✓ Manifest integrity verified (12 files, BLAKE3)
Bundle verification: PASSED

# Deep verify (check CAS references)
volt bundle verify --deep cas-bundle.vbundle
```

### `volt bundle push` / `volt bundle pull`

Registry operations.

```bash
# Push to registry
volt bundle push my-stack.vbundle --tag v1.2.0 --tag latest

# Pull from registry
volt bundle pull my-stack:v1.2.0

# Pull for specific platform
volt bundle pull my-stack:latest --platform linux/amd64
```

### `volt bundle list`

List locally cached bundles.

```bash
$ volt bundle list
NAME          VERSION   PLATFORMS         SIZE     CREATED              SIGNED
my-stack      1.2.0     amd64,arm64       1.8 GB   2025-07-14 15:30    ✓
dev-env       0.1.0     amd64             450 MB   2025-07-13 10:00    ✗
```

## Lifecycle Hooks

Hooks are executable scripts that run at defined points during deployment:

| Hook | Trigger |
|------|---------|
| `validate` | Before deployment — pre-flight checks |
| `pre-deploy` | After extraction, before service start |
| `post-deploy` | After all services are healthy |
| `pre-destroy` | Before services are stopped |
| `post-destroy` | After cleanup |

Hooks are **opt-in** — use `--run-hooks` to enable:

```bash
volt bundle import --run-hooks my-stack.vbundle
```

Review hooks before enabling:

```bash
volt bundle inspect --show-hooks my-stack.vbundle
```

## Signing & Verification

Bundles support Ed25519 cryptographic signatures for supply chain integrity.

```bash
# Create a signed bundle
volt bundle create --sign --sign-key ~/.config/volt/signing-key -o prod.vbundle

# Verify before deploying
volt bundle import --verify prod.vbundle

# Trust a signing key
volt config set bundle.trusted_keys += "age1z3x..."
```

Every file in a bundle is content-hashed (BLAKE3) and recorded in the bundle manifest's `integrity` field. Verification checks both the signature and all content hashes.

## ACE Compatibility

Volt bundles are an evolution of the ACE (Android Container Engine) project bundle format. ACE bundles (ZIP files with `compose.json` and `images/` directory) are imported transparently by `volt bundle import`.

```bash
# Import an ACE bundle directly
volt bundle import legacy-project.zip

# Create an ACE-compatible bundle
volt bundle create --format ace -o project.zip
```

## Configuration Overlays

The `config/` directory contains per-service configuration files applied after image extraction:

```
config/
├── web-proxy/
│   └── nginx.conf          # Overwrites /etc/nginx/nginx.conf in container
└── api-server/
    └── .env.production     # Injected via volume mount
```

Config files support `${VARIABLE}` template expansion, resolved from the Constellation's environment definitions, env_file references, or `--set` flags during import.

## Full Specification

See the complete [Volt Bundle Format Specification](/Knowledge/Projects/Volt-Bundle-Spec.md) for:

- Detailed `bundle.json` schema and JSON Schema definition
- Platform/architecture matrix
- CAS reference resolution
- Signature verification flow
- Registry HTTP API
- Error handling and recovery
- Comparison with OCI Image Spec