build & pussh

Build Docker images and transfer them to servers.

build

Build Docker images locally or on a remote host.

Synopsis

odysseus build [options]

Options

--config FILE

Path to configuration file. Default: deploy.yml

odysseus build --config production.yml --image v1.0.0

--image TAG

Docker image tag.

odysseus build --image v1.0.0
odysseus build --image $(git rev-parse --short HEAD)

--push

Push to registry after building.

odysseus build --image v1.0.0 --push

Requires registry configuration:

registry:
  server: ghcr.io
  username: myuser
  password: ${GITHUB_TOKEN}

--context PATH

Override build context path.

odysseus build --image v1.0.0 --context ./app

--verbose, -v

Show detailed build output.

odysseus build --verbose --image v1.0.0

Examples

# Build with default settings
odysseus build --image v1.0.0

# Build and push to registry
odysseus build --image v1.0.0 --push

# Build with custom context
odysseus build --image v1.0.0 --context ./backend

# Build for staging
odysseus build --config staging.yml --image staging-v1.0.0

pussh

Transfer Docker images directly to servers without a registry.

Synopsis

odysseus pussh [options]

How it works

1. Image is saved as a compressed tarball
2. Tarball is streamed over SSH to each server
3. Server loads the image into Docker

This is useful when:

• You don't have a Docker registry
• You want to avoid registry latency
• You're deploying to a single server

Options

--config FILE

Path to configuration file. Default: deploy.yml

odysseus pussh --config production.yml --image v1.0.0

--image TAG

Docker image tag to transfer.

odysseus pussh --image v1.0.0

--build

Build the image before transferring.

odysseus pussh --build --image v1.0.0

--verbose, -v

Show detailed transfer progress.

odysseus pussh --verbose --image v1.0.0

Examples

# Transfer existing image
odysseus pussh --image v1.0.0

# Build and transfer
odysseus pussh --build --image v1.0.0

# Verbose output
odysseus pussh --verbose --build --image v1.0.0

Output

Building image myapp:v1.0.0...
Build complete.

Transferring to servers:
  app1.example.com... 245 MB transferred (12.5 MB/s)
  app2.example.com... 245 MB transferred (10.2 MB/s)

Transfer complete.

Build strategies

Local builds

Build on the machine running Odysseus:

builder:
  strategy: local
  arch: amd64

odysseus build --image v1.0.0

Remote builds

Build on a dedicated server:

builder:
  strategy: remote
  host: build-server.example.com
  arch: amd64

odysseus build --image v1.0.0

Remote builds:

1. Sync source files to build server
2. Run Docker build remotely
3. Image is available on build server

Registry vs Pussh

With registry

registry:
  server: ghcr.io
  username: myuser
  password: ${GITHUB_TOKEN}

odysseus build --image v1.0.0 --push
odysseus deploy --image v1.0.0

Flow: Build → Push to registry → Servers pull → Deploy

Without registry (pussh)

odysseus pussh --build --image v1.0.0
odysseus deploy --image v1.0.0

Or combined:

odysseus deploy --build --image v1.0.0

Flow: Build → Transfer directly to servers → Deploy

Build configuration

Full configuration reference:

builder:
  strategy: local          # or 'remote'
  host: build.example.com  # for remote strategy
  arch: amd64              # or 'arm64'
  dockerfile: Dockerfile   # path to Dockerfile
  context: .               # build context
  build_args:              # build-time arguments
    RUBY_VERSION: "3.2"
    NODE_VERSION: "20"
  cache: true              # use Docker cache
  push: false              # push after build
  multiarch: false         # multi-architecture build
  platforms:               # for multiarch builds
    - linux/amd64
    - linux/arm64

Exit codes