Configuration

TurboCI uses a single config.yaml file in the .turboci directory to define all your deployments across multiple cloud providers.

Basic Structure

A TurboCI configuration file is an array of deployment objects, each containing services and their configurations.

# .turboci/config.yaml
- deployment_name: my_deployment
  provider: hetzner
  location: ash
  description: My first deployment
  services:
    web:
      instances: 2
      clusters: 1
      server_type: cpx21
      dir_mappings:
        - src: .
          dst: /app
      run:
        start:
          work_dir: /app
          cmds:
            - npm start

Deployment Fields

deployment_name (required)

Unique identifier for this deployment. Must contain only lowercase letters and underscores.

deployment_name: web_production

provider (required)

Cloud provider to use. Supported: hetzner, aws, gcp, azure.

provider: hetzner

location

Deployment location determined by provider. Use turboci spec to see available locations.

location: ash

description

Optional description for your deployment.

description: Production deployment on Hetzner

duplicate_deployment_name

Clone an existing deployment configuration. Specified fields will override the parent config.

duplicate_deployment_name: web_production

Service Fields

type

Service type: default, load_balancer, or docker. Defaults to default.

type: load_balancer

os

Operating system. Defaults to debian-11 for Hetzner, or equivalent for other providers.

os: debian-11

server_type

Server type as specified by provider. Use turboci spec to see options.

server_type: cpx21

enable_public_ip

Enable public IP addresses. Defaults to false except for load_balancer services.

enable_public_ip: true

instances

Number of servers in a cluster. Defaults to 1.

instances: 3

clusters

Number of clusters for high availability. Clusters update one at a time for zero downtime. Total servers = instances × clusters.

clusters: 2

duplicate_service_name

Clone an existing service configuration. Extra config will replace parent config.

duplicate_service_name: web_prod

Directory Mappings

Map local directories to server locations. Files are synced to the relay server, then distributed to service servers.

dir_mappings:
  - src: .
    dst: /app
  - src: ./secrets/prod.env
    dst: /app/.env
    ignore_file: .gitignore
    use_gitignore: true
    relay_ignore:
      - node_modules
      - .git

Dependencies

Install dependencies on target servers. Supports apt packages and TurboCI cross-platform packages.

dependencies:
  apt:
    - rsync
    - neofetch
  turboci:
    - docker
    - bun
    - node

Run Commands

Define commands to run during deployment: preflight (before start), start, and postflight (after start).

run:
  preflight:
    work_dir: /app
    cmds:
      - bun add -g pm2
      - bun install
      - bunx next build
  start:
    work_dir: /app
    cmds:
      - pm2 start "bunx next start"
  postflight:
    cmds:
      - pm2 list

Healthcheck

Verify service is working correctly. Deployment fails if healthcheck doesn't pass.

healthcheck:
  cmd: curl http://localhost:3000/api/healthcheck
  test: Server Running

Load Balancer Configuration

Configure load balancers with target services and SSL domains.

load_balancer:
  type: load_balancer
  target_services:
    - service_name: web_prod
      port: 3000
      weight: 10
    - service_name: web_dev
      port: 3000
      domains:
        - dev.example.com
        - domain_name: staging.example.com
  ssl:
    email: admin@example.com

Complete Example

- deployment_name: test
  provider: hetzner
  location: ash
  description: Production deployment on Hetzner
  services:
    web:
      instances: 2
      clusters: 2
      server_type: cpx21
      dir_mappings:
        - src: .
          dst: /app
        - src: ./secrets/prod.env
          dst: /app/.env
      dependencies:
        apt:
          - rsync
        turboci:
          - bun
          - node
      run:
        preflight:
          work_dir: /app
          cmds:
            - bun add -g pm2
            - pm2 kill
            - bun install
            - bunx next build
        start:
          work_dir: /app
          cmds:
            - pm2 start "bunx next start"
        postflight:
          cmds:
            - pm2 list
      healthcheck:
        cmd: curl http://localhost:3000/api/healthcheck
        test: Server Running
    load_balancer:
      type: load_balancer
      target_services:
        - service_name: web
          port: 3000
          
- deployment_name: test_aws
  provider: aws
  location: us-east-1
  duplicate_deployment_name: test

Next Steps

Learn how to deploy your configuration using the TurboCI CLI.

Continue to CLI Commands →