ArmoredGate/volt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4f507335ecd75d449dd7f5456c7e1b216314f62f
volt/docs/compose.md
Karl Clinger 0ebe75b2ca Volt CLI: source-available under AGPSL v5.0 
Complete infrastructure platform CLI:
- Container runtime (systemd-nspawn)
- VoltVisor VMs (Neutron Stardust / QEMU)
- Stellarium CAS (content-addressed storage)
- ORAS Registry
- GitOps integration
- Landlock LSM security
- Compose orchestration
- Mesh networking

Copyright (c) Armored Gates LLC. All rights reserved.
Licensed under AGPSL v5.0
2026-03-21 02:08:15 -05:00

742 lines
15 KiB
Markdown
Raw Blame History

# Voltfile / Constellation Format
A **Constellation** is the definition of how containers, VMs, services, and resources form a coherent system. `volt compose` manages Constellations as declarative multi-service stacks — define containers, VMs, services, tasks, networks, and volumes in a single YAML file and deploy them together.
## File Discovery
`volt compose` looks for Constellation definitions in this order:
1. `-f <path>` flag (explicit)
2. `volt-compose.yaml` in current directory
3. `volt-compose.yml` in current directory
4. `Voltfile` in current directory (YAML format)
## Quick Example
```yaml
version: "1"
name: web-stack
containers:
web:
image: armoredgate/nginx:1.25
ports:
- "80:80"
networks:
- frontend
depends_on:
api:
condition: service_started
api:
image: armoredgate/node:20
ports:
- "8080:8080"
environment:
DATABASE_URL: "postgresql://app:secret@db:5432/myapp"
networks:
- frontend
- backend
vms:
db:
image: armoredgate/ubuntu-24.04
cpu: 2
memory: 4G
networks:
- backend
networks:
frontend:
subnet: 10.20.0.0/24
backend:
subnet: 10.30.0.0/24
internal: true
```
Deploy:
```bash
volt compose up -d # Create and start in background
volt compose ps # Check status
volt compose logs -f # Follow all logs
volt compose down # Tear down
```
## Top-Level Keys
| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `version` | string | Yes | File format version. Currently `"1"`. |
| `name` | string | No | Stack name. Used as prefix for workload names. |
| `description` | string | No | Human-readable description. |
| `containers` | map | No | Container definitions (Voltainer). |
| `vms` | map | No | VM definitions (Voltvisor). |
| `services` | map | No | systemd service definitions. |
| `tasks` | map | No | Scheduled task definitions. |
| `networks` | map | No | Network definitions. |
| `volumes` | map | No | Volume definitions. |
| `configs` | map | No | Configuration file references. |
| `secrets` | map | No | Secret file references. |
## Container Definition
```yaml
containers:
<name>:
image: <string> # Image name (required)
build: # Build configuration (optional)
context: <path> # Build context directory
file: <path> # Build spec file
ports: # Port mappings
- "host:container"
volumes: # Volume mounts
- host_path:container_path[:ro]
- volume_name:container_path
networks: # Networks to join
- network_name
environment: # Environment variables
KEY: value
env_file: # Load env vars from files
- .env
depends_on: # Dependencies
other_service:
condition: service_started|service_healthy|service_completed_successfully
restart: no|always|on-failure|unless-stopped
restart_max_retries: <int> # Max restart attempts (for on-failure)
resources:
cpu: "<number>" # CPU shares/quota
memory: <size> # e.g., 256M, 1G
memory_swap: <size> # Swap limit
healthcheck:
command: ["cmd", "args"] # Health check command
interval: <duration> # Check interval (e.g., 30s)
timeout: <duration> # Check timeout
retries: <int> # Retries before unhealthy
start_period: <duration> # Grace period on start
labels:
key: value
```
### Container Example
```yaml
containers:
app-server:
image: armoredgate/node:20
build:
context: ./app
file: build-spec.yaml
ports:
- "8080:8080"
volumes:
- app-data:/app/data
- ./config:/app/config:ro
networks:
- backend
environment:
NODE_ENV: production
DATABASE_URL: "postgresql://app:${DB_PASSWORD}@db:5432/myapp"
env_file:
- .env
- .env.production
depends_on:
db:
condition: service_healthy
cache:
condition: service_started
restart: on-failure
restart_max_retries: 5
resources:
cpu: "2"
memory: 1G
memory_swap: 2G
healthcheck:
command: ["curl", "-sf", "http://localhost:8080/health"]
interval: 15s
timeout: 3s
retries: 5
```
## VM Definition
```yaml
vms:
<name>:
image: <string> # Base image (required)
cpu: <int> # vCPU count
memory: <size> # Memory allocation (e.g., 4G)
disks: # Additional disks
- name: <string>
size: <size>
mount: <path> # Mount point inside VM
networks:
- network_name
ports:
- "host:vm"
provision: # First-boot scripts
- name: <string>
shell: |
commands to run
healthcheck:
command: ["cmd", "args"]
interval: <duration>
timeout: <duration>
retries: <int>
restart: no|always|on-failure
tune: # Performance tuning
cpu_pin: [<int>, ...] # Pin to physical CPUs
hugepages: <bool> # Use hugepages
io_scheduler: <string> # I/O scheduler
```
### VM Example
```yaml
vms:
db-primary:
image: armoredgate/ubuntu-24.04
cpu: 4
memory: 8G
disks:
- name: system
size: 40G
- name: pgdata
size: 200G
mount: /var/lib/postgresql/data
networks:
- backend
ports:
- "5432:5432"
provision:
- name: install-postgres
shell: |
apt-get update && apt-get install -y postgresql-16
systemctl enable postgresql
healthcheck:
command: ["pg_isready", "-U", "postgres"]
interval: 30s
timeout: 5s
retries: 3
restart: always
tune:
cpu_pin: [4, 5, 6, 7]
hugepages: true
io_scheduler: none
```
## Service Definition
Define systemd services managed by the Constellation:
```yaml
services:
<name>:
unit:
type: simple|oneshot|forking|notify
exec: <string> # Command to run (required)
user: <string>
group: <string>
restart: no|always|on-failure
networks:
- network_name
healthcheck:
command: ["cmd", "args"]
interval: <duration>
resources:
memory: <size>
depends_on:
other_service:
condition: service_started
```
### Service Example
```yaml
services:
cache-redis:
unit:
type: simple
exec: "/usr/bin/redis-server /etc/redis/redis.conf"
user: redis
group: redis
restart: always
networks:
- backend
healthcheck:
command: ["redis-cli", "ping"]
interval: 10s
resources:
memory: 512M
```
## Task Definition
Define scheduled tasks (systemd timers):
```yaml
tasks:
<name>:
exec: <string> # Command to run (required)
schedule:
on_calendar: <string> # systemd calendar syntax
every: <duration> # Alternative: interval
environment:
KEY: value
user: <string>
persistent: <bool> # Run missed tasks on boot
```
### Task Example
```yaml
tasks:
db-backup:
exec: "/usr/local/bin/backup.sh --target db-primary"
schedule:
on_calendar: "*-*-* 02:00:00"
environment:
BACKUP_DEST: /mnt/backups
cleanup:
exec: "/usr/local/bin/cleanup-old-logs.sh"
schedule:
every: 6h
```
## Network Definition
```yaml
networks:
<name>:
driver: bridge # Network driver (default: bridge)
subnet: <cidr> # e.g., 10.20.0.0/24
internal: <bool> # If true, no external access
options:
mtu: <int> # MTU (default: 1500)
```
### Network Examples
```yaml
networks:
# Public-facing network
frontend:
driver: bridge
subnet: 10.20.0.0/24
options:
mtu: 9000
# Internal only — no external access
backend:
driver: bridge
subnet: 10.30.0.0/24
internal: true
```
## Volume Definition
```yaml
volumes:
<name>:
driver: local # Storage driver
size: <size> # Optional size for file-backed volumes
```
### Volume Examples
```yaml
volumes:
web-static:
driver: local
app-data:
driver: local
size: 10G
pgdata:
driver: local
size: 200G
```
## Configs and Secrets
```yaml
configs:
<name>:
file: <path> # Path to config file
secrets:
<name>:
file: <path> # Path to secret file
```
### Example
```yaml
configs:
nginx-conf:
file: ./config/nginx.conf
app-env:
file: ./.env.production
secrets:
db-password:
file: ./secrets/db-password.txt
tls-cert:
file: ./secrets/server.crt
tls-key:
file: ./secrets/server.key
```
## Dependency Conditions
When specifying `depends_on`, the `condition` field controls when the dependent service starts:
| Condition | Description |
|-----------|-------------|
| `service_started` | Dependency has started (default) |
| `service_healthy` | Dependency passes its health check |
| `service_completed_successfully` | Dependency ran and exited with code 0 |
```yaml
depends_on:
db:
condition: service_healthy
migrations:
condition: service_completed_successfully
cache:
condition: service_started
```
## Environment Variable Interpolation
The Constellation definition supports shell-style variable interpolation:
```yaml
environment:
DATABASE_URL: "postgresql://app:${DB_PASSWORD}@db:5432/myapp"
APP_VERSION: "${APP_VERSION:-latest}"
```
Variables are resolved from:
1. Host environment variables
2. `.env` file in the same directory as the Constellation definition
3. Files specified in `env_file`
Unset variables with no default cause an error.
## Compose Commands
### Lifecycle
```bash
# Deploy the Constellation — create and start everything
volt compose up
# Detached mode (background)
volt compose up -d
# Specific Constellation file
volt compose -f production.yaml up -d
# Build images first
volt compose up --build
# Force recreate
volt compose up --force-recreate
# Tear down the Constellation
volt compose down
# Also remove volumes
volt compose down --volumes
```
### Status and Logs
```bash
# Stack status
volt compose ps
# All logs
volt compose logs
# Follow logs
volt compose logs --follow
# Logs for one service
volt compose logs api
# Last 50 lines
volt compose logs --tail 50 api
# Resource usage
volt compose top
# Events
volt compose events
```
### Operations
```bash
# Start existing (without recreating)
volt compose start
# Stop (without removing)
volt compose stop
# Restart
volt compose restart
# Execute command in a service
volt compose exec api -- node --version
# Pull images
volt compose pull
# Build images
volt compose build
# Validate Constellation
volt compose config
```
### Project Naming
```bash
# Override project name
volt compose --project my-project up
# This prefixes all workload names: my-project-web, my-project-api, etc.
```
## Full Example: Production Constellation
```yaml
# volt-compose.yaml — Production Constellation
version: "1"
name: production
description: "Production web application"
containers:
web-proxy:
image: armoredgate/nginx:1.25
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- web-static:/usr/share/nginx/html:ro
networks:
- frontend
- backend
depends_on:
app-server:
condition: service_healthy
restart: always
resources:
cpu: "0.5"
memory: 256M
healthcheck:
command: ["curl", "-sf", "http://localhost/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
app-server:
image: armoredgate/node:20
build:
context: ./app
file: build-spec.yaml
environment:
NODE_ENV: production
DATABASE_URL: "postgresql://app:${DB_PASSWORD}@db-primary:5432/myapp"
REDIS_URL: "redis://cache-redis:6379"
env_file:
- .env.production
ports:
- "8080:8080"
volumes:
- app-data:/app/data
networks:
- backend
depends_on:
db-primary:
condition: service_healthy
cache-redis:
condition: service_started
restart: on-failure
restart_max_retries: 5
resources:
cpu: "2"
memory: 1G
healthcheck:
command: ["curl", "-sf", "http://localhost:8080/health"]
interval: 15s
timeout: 3s
retries: 5
vms:
db-primary:
image: armoredgate/ubuntu-24.04
cpu: 4
memory: 8G
disks:
- name: system
size: 40G
- name: pgdata
size: 200G
mount: /var/lib/postgresql/data
networks:
- backend
ports:
- "5432:5432"
provision:
- name: install-postgres
shell: |
apt-get update && apt-get install -y postgresql-16
systemctl enable postgresql
healthcheck:
command: ["pg_isready", "-U", "postgres"]
interval: 30s
timeout: 5s
retries: 3
restart: always
tune:
cpu_pin: [4, 5, 6, 7]
hugepages: true
io_scheduler: none
services:
cache-redis:
unit:
type: simple
exec: "/usr/bin/redis-server /etc/redis/redis.conf"
user: redis
group: redis
restart: always
networks:
- backend
healthcheck:
command: ["redis-cli", "ping"]
interval: 10s
resources:
memory: 512M
log-shipper:
unit:
type: simple
exec: "/usr/local/bin/vector --config /etc/vector/vector.toml"
restart: on-failure
depends_on:
app-server:
condition: service_started
tasks:
db-backup:
exec: "/usr/local/bin/backup.sh --target db-primary"
schedule:
on_calendar: "*-*-* 02:00:00"
environment:
BACKUP_DEST: /mnt/backups
cleanup:
exec: "/usr/local/bin/cleanup-old-logs.sh"
schedule:
every: 6h
networks:
frontend:
driver: bridge
subnet: 10.20.0.0/24
options:
mtu: 9000
backend:
driver: bridge
subnet: 10.30.0.0/24
internal: true
volumes:
web-static:
driver: local
app-data:
driver: local
size: 10G
configs:
nginx-conf:
file: ./config/nginx.conf
secrets:
db-password:
file: ./secrets/db-password.txt
tls-cert:
file: ./secrets/server.crt
tls-key:
file: ./secrets/server.key
```
## Full Example: Developer Constellation
```yaml
# volt-compose.yaml — Developer Constellation
version: "1"
name: dev-environment
vms:
dev-box:
image: armoredgate/fedora-workstation
cpu: 4
memory: 8G
disks:
- name: system
size: 80G
volumes:
- ~/projects:/home/dev/projects
networks:
- devnet
ports:
- "2222:22"
- "3000:3000"
- "5173:5173"
provision:
- name: dev-tools
shell: |
dnf install -y git nodejs rust golang
npm install -g pnpm
containers:
test-db:
image: armoredgate/postgres:16
environment:
POSTGRES_PASSWORD: devpass
POSTGRES_DB: myapp_dev
volumes:
- test-pgdata:/var/lib/postgresql/data
networks:
- devnet
ports:
- "5432:5432"
mailhog:
image: armoredgate/mailhog:latest
networks:
- devnet
ports:
- "1025:1025"
- "8025:8025"
networks:
devnet:
subnet: 10.99.0.0/24
volumes:
test-pgdata:
driver: local
```
Reference in New Issue View Git Blame Copy Permalink