Configuration Reference

Complete reference for all Haloy configuration options.

Root Configuration Options

Key	Type	Required	Description
`name`	string	Yes	Unique application name
`image`	object	No	Docker image configuration (see Image Configuration)
`server`	string	No	Haloy server API URL
`api_token`	object	No	API token configuration (see Authentication)
`deployment_strategy`	string	No	Deployment strategy: “rolling” (default) or “replace”
`domains`	array	No	Domain configuration
`acme_email`	string	No	Let’s Encrypt email (required with domains)
`replicas`	integer	No	Number of container instances (default: 1)
`port`	string/integer	No	Container port to expose (default: “8080”). The port your application listens on inside the container.
`health_check_path`	string	No	Health check endpoint (default: ”/“)
`env`	array	No	Environment variables (see Environment Variables)
`volumes`	array	No	Volume mounts (see Volumes)
`pre_deploy`	array	No	Commands to run before deploy
`post_deploy`	array	No	Commands to run after deploy
`global_pre_deploy`	array	No	Commands to run once before all deployments (multi-target only)
`global_post_deploy`	array	No	Commands to run once after all deployments (multi-target only)
`targets`	object	No	Multiple deployment targets with overrides (see Multi-Server Deployments)
`secret_providers`	object	No	Secret provider configuration (see Secret Providers)
`network`	string	No	Docker network for the container. (default: `haloy`)

Deployment Strategies

Rolling Deployment (Default)

Gradually replaces old containers with new ones, ensuring zero downtime:

name: "my-app"
deployment_strategy: "rolling"
replicas: 3
name: "my-app"
deployment_strategy: "rolling"
replicas: 3

Replace Deployment

Stops all old containers before starting new ones:

name: "my-app"
deployment_strategy: "replace"
replicas: 3
name: "my-app"
deployment_strategy: "replace"
replicas: 3

Deployment Hooks

Important: All deployment hooks (pre_deploy, post_deploy, global_pre_deploy, and global_post_deploy) are executed by the haloy CLI tool on the machine where you run the deployment command, not on the server. This means:

Hooks run in your local environment with access to your local filesystem, environment variables, and installed tools
They do not have direct access to the server’s filesystem or environment
Use hooks for local preparation tasks like building assets, running tests, or sending notifications
For server-side operations, consider using container initialization scripts or application startup logic

Run custom commands before or after deployment:

name: "my-app"
pre_deploy:
  - "npm run migrate"
  - "echo 'Starting deployment'"
post_deploy:
  - "curl -X POST https://status.example.com/notify"
  - "echo 'Deployment complete'"
name: "my-app"
pre_deploy:
  - "npm run migrate"
  - "echo 'Starting deployment'"
post_deploy:
  - "curl -X POST https://status.example.com/notify"
  - "echo 'Deployment complete'"

For multi-target deployments, use global hooks:

name: "my-app"
global_pre_deploy:
  - "npm run build"
  - "docker build -t my-app ."
global_post_deploy:
  - "echo 'All deployments complete'"
targets:
  production:
    server: prod.haloy.com
    pre_deploy:
      - "npm run test:production"
  staging:
    server: staging.haloy.com
    pre_deploy: - "npm run test:staging"
name: "my-app"
global_pre_deploy:
  - "npm run build"
  - "docker build -t my-app ."
global_post_deploy:
  - "echo 'All deployments complete'"
targets:
  production:
    server: prod.haloy.com
    pre_deploy:
      - "npm run test:production"
  staging:
    server: staging.haloy.com
    pre_deploy: - "npm run test:staging"

Target Configuration

When using multi-target deployments, each target can override base configuration:

Key	Type	Description
`server`	string	Override the server for this target
`api_token`	object	Override the API token configuration
`image`	object	Override image configuration (repository, tag, etc.)
`domains`	array	Override domain configuration
`acme_email`	string	Override ACME email
`env`	array	Override environment variables
`replicas`	integer	Override number of replicas
`port`	string	Override container port
`health_check_path`	string	Override health check path
`volumes`	array	Override volume mounts
`pre_deploy`	array	Override pre-deploy hooks
`post_deploy`	array	Override post-deploy hooks
`network`	string	Override docker network

Inheritance Rules:

Base configuration provides defaults for all targets
Most target-specific values completely override base values (no merging)
Only specified fields in targets override the base
Exception: Environment variables (env) are merged - target values override base values with the same name, while preserving other base variables
global_pre_deploy and global_post_deploy run once regardless of targets

Example

# Base configuration - inherited by all targets
name: "my-app"
image:
  repository: "ghcr.io/my-org/my-app"
  tag: "latest"
replicas: 2
port: "8080"
env:
  - name: "LOG_LEVEL"
    value: "info"
# Targets
targets:
  production: # Inherits: replicas=2, port="8080", base env (LOG_LEVEL) # Overrides: image.tag, adds domains, adds/overrides env variables
    server: "prod.haloy.com"
    image:
      tag: "v1.2.3"
    domains:
      - domain: "my-app.com"
    env: # Merges with base env
      - name: "NODE_ENV"
        value: "production"
      # LOG_LEVEL="info" is inherited from base
  staging: # Inherits: image (repository + tag), replicas=2, port="8080", base env # Overrides: server, changes replicas, adds domains, overrides LOG_LEVEL
    server: "staging.haloy.com"
    replicas: 1
    domains:
      - domain: "staging.my-app.com"
    env:
      - name: "LOG_LEVEL"
        value: "debug"
      # FEATURE_FLAG is inherited from base
# Base configuration - inherited by all targets
name: "my-app"
image:
  repository: "ghcr.io/my-org/my-app"
  tag: "latest"
replicas: 2
port: "8080"
env:
  - name: "LOG_LEVEL"
    value: "info"
# Targets
targets:
  production: # Inherits: replicas=2, port="8080", base env (LOG_LEVEL) # Overrides: image.tag, adds domains, adds/overrides env variables
    server: "prod.haloy.com"
    image:
      tag: "v1.2.3"
    domains:
      - domain: "my-app.com"
    env: # Merges with base env
      - name: "NODE_ENV"
        value: "production"
      # LOG_LEVEL="info" is inherited from base
  staging: # Inherits: image (repository + tag), replicas=2, port="8080", base env # Overrides: server, changes replicas, adds domains, overrides LOG_LEVEL
    server: "staging.haloy.com"
    replicas: 1
    domains:
      - domain: "staging.my-app.com"
    env:
      - name: "LOG_LEVEL"
        value: "debug"
      # FEATURE_FLAG is inherited from base

Custom Docker Network

By default, containers are attached to the haloy network. You can override this:

name: "my-app"
network: "my-custom-network"
name: "my-app"
network: "my-custom-network"

Important: If you override the default network (haloy), the Haloy proxy will not be able to discover your containers. This means:

Your application containers will not be included in the HAProxy configuration
Traffic will not be routed to your application
Your domains will not work, even though the containers are running
The containers will be completely ignored by the routing system after they start

Only change the network if you have a specific networking requirement and understand that you’ll need to handle routing separately.

Validation

Validate your configuration file:

haloy validate-config
haloy validate-config --config path/to/config.yaml
haloy validate-config --show-resolved-config  # Display with secrets (use with caution)
haloy validate-config
haloy validate-config --config path/to/config.yaml
haloy validate-config --show-resolved-config  # Display with secrets (use with caution)