accessory

Manage accessory services like databases and caches.

Synopsis

odysseus accessory <command> [options]

Commands for managing auxiliary services. Most commands read target hosts from the accessory's hosts configuration in deploy.yml, similar to how deploy works.

Commands

boot

Start a specific accessory on all its configured hosts.

odysseus accessory boot --name <accessory>

Example

odysseus accessory boot --name db

Output:

Deploying accessory db to db.example.com...
Starting container myapp-db (postgres:16)...
Waiting for health check...
Accessory 'db' is running.

The target hosts are read from the accessory's hosts configuration in deploy.yml.

boot-all

Start all configured accessories on their respective hosts.

odysseus accessory boot-all

Example

odysseus accessory boot-all

Output:

=== Booting accessory: db ===
Deploying accessory db to db.example.com...
  db: starting... running

=== Booting accessory: redis ===
Deploying accessory redis to cache.example.com...
  redis: starting... running

All accessories running.

Each accessory is deployed to the hosts specified in its configuration.

status

Show status of all accessories across their configured hosts.

odysseus accessory status

Example

odysseus accessory status

Output:

Accessories:
  NAME    HOST              IMAGE         STATUS             HEALTH
  db      db.example.com    postgres:16   running (2 days)   healthy
  redis   cache.example.com redis:7       running (2 days)   healthy

logs

View accessory logs.

odysseus accessory logs <server> --name <accessory> [options]

Options

--name NAME

Accessory name (required).

-f, --follow

Follow log output in real-time.

-n, --lines N

Number of lines to show. Default: 100.

--since TIME

Show logs since timestamp or duration.

Examples

# Last 100 lines
odysseus accessory logs app.example.com --name db

# Follow logs
odysseus accessory logs app.example.com --name db -f

# Last 500 lines
odysseus accessory logs app.example.com --name db -n 500

# Since 1 hour ago
odysseus accessory logs app.example.com --name db --since 1h

restart

Restart an accessory on all its configured hosts.

odysseus accessory restart --name <accessory>

Example

odysseus accessory restart --name redis

Output:

Restarting accessory redis on cache.example.com...
Stopping container...
Starting container...
Waiting for health check...
Accessory 'redis' restarted.

upgrade

Pull latest image and restart on all configured hosts.

odysseus accessory upgrade --name <accessory>

Example

odysseus accessory upgrade --name db

Output:

Upgrading accessory db on db.example.com...
Pulling postgres:16...
Stopping old container...
Starting new container...
Waiting for health check...
Accessory 'db' upgraded.

remove

Stop and remove an accessory from all its configured hosts.

odysseus accessory remove --name <accessory>

Example

odysseus accessory remove --name redis

Output:

Removing accessory redis from cache.example.com...
Stopping container...
Removing container...
Accessory 'redis' removed.

exec

Execute a command in an accessory container.

odysseus accessory exec <server> --name <accessory> --command <cmd>

Example

# PostgreSQL query
odysseus accessory exec app.example.com \
  --name db \
  --command "psql -U myapp -d myapp_production -c 'SELECT count(*) FROM users;'"

# Redis CLI
odysseus accessory exec app.example.com \
  --name redis \
  --command "redis-cli INFO"

shell

Start an interactive shell in an accessory container.

odysseus accessory shell <server> --name <accessory>

Example

odysseus accessory shell app.example.com --name db

This opens an interactive bash shell inside the container.

# Now inside the container
psql -U myapp myapp_production
\dt  # List tables
\q   # Quit psql
exit # Exit container

Common options

--config FILE

Path to configuration file. Default: deploy.yml

odysseus accessory status app.example.com --config production.yml

Configuration

Define accessories in deploy.yml. Each accessory must specify hosts - the servers where it should run:

accessories:
  db:
    image: postgres:16
    hosts:
      - db.example.com
    volumes:
      - /var/lib/odysseus/myapp/postgres:/var/lib/postgresql/data
    env:
      clear:
        POSTGRES_USER: myapp
        POSTGRES_PASSWORD: secret
        POSTGRES_DB: myapp_production
    healthcheck:
      cmd: pg_isready -U myapp
      interval: 10
      timeout: 5

  redis:
    image: redis:7-alpine
    hosts:
      - cache.example.com
    volumes:
      - /var/lib/odysseus/myapp/redis:/data
    cmd: redis-server --appendonly yes

See Accessories for full configuration reference.

Exit codes