dependency

Manage dependency services like databases and caches.

Synopsis

odysseus dependency <command> [options]

dep is accepted as shorthand for dependency.

Commands for managing auxiliary services. boot, boot-all, remove, restart, upgrade, and status read target hosts from the dependency's hosts configuration in deploy.yml, similar to how deploy works. logs, exec, and shell operate on one host and take it as a server argument instead.

Commands

boot

Start a specific dependency on all its configured hosts.

odysseus dependency boot --name <dependency>

Example

odysseus dependency boot --name db

Output:

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

The target hosts are read from the dependency's hosts configuration in deploy.yml. No server argument.

boot-all

Start all configured dependencies on their respective hosts.

odysseus dependency boot-all

Example

odysseus dependency boot-all

Output:

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

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

All dependencies running.

Each dependency is deployed to the hosts specified in its own configuration. No server argument.

status

Show status of all dependencies across their configured hosts.

odysseus dependency status

Example

odysseus dependency status

Output:

Dependencies:
  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

No server argument — status walks every dependency's own hosts list.

logs

View dependency logs.

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

Takes a server argument: logs are read from one host, not every host the dependency runs on.

Options

--name NAME

Dependency 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 dependency logs app.example.com --name db

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

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

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

restart

Restart a dependency on all its configured hosts.

odysseus dependency restart --name <dependency>

Example

odysseus dependency restart --name redis

Output:

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

No server argument.

upgrade

Pull latest image and restart on all configured hosts.

odysseus dependency upgrade --name <dependency>

Example

odysseus dependency upgrade --name db

Output:

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

No server argument.

remove

Stop and remove a dependency from all its configured hosts.

odysseus dependency remove --name <dependency>

Example

odysseus dependency remove --name redis

Output:

Removing dependency redis from cache.example.com...
Stopping container...
Removing container...
Dependency 'redis' removed.

No server argument.

exec

Execute a command in a dependency container.

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

Takes a server argument.

Example

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

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

shell

Start an interactive shell in a dependency container.

odysseus dependency shell <server> --name <dependency>

Takes a server argument.

Example

odysseus dependency 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 dependency status --config production.yml

Configuration

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

dependencies:
  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 Dependencies for full configuration reference.

Exit codes