Configuration Guide

Otto-stack uses .otto-stack/config.yaml to define your development stack.

File Structure#

After running otto-stack init, you’ll have:

.otto-stack/
├── config.yaml              # Main configuration
├── generated/
│   ├── .env.generated       # Available environment variables
│   └── docker-compose.yml   # Generated Docker Compose
├── services/                # Service metadata
│   ├── postgres.yml
│   └── redis.yml
├── .gitignore
└── README.md

Main Configuration#

.otto-stack/config.yaml:

project:
  name: my-app
stack:
  enabled:
    - postgres
    - redis
sharing:
  enabled: false
advanced:
  auto_start: false
  pull_latest_images: false
  cleanup_on_recreate: false
version_config:
  required_version:

Project#

Project configuration settings

• name: Project name

Stack#

Stack service configuration

• enabled: List of enabled services

Sharing#

Container sharing configuration allows services to be shared across multiple projects, reducing resource usage and startup time

• enabled: Enable container sharing across projects. When enabled, containers are prefixed with ‘otto-stack-’ and tracked in ~/.otto-stack/shared/containers.yaml
• services: Per-service sharing overrides (service_name: true/false). If empty, all services are shared when enabled is true

Validation#

Validation and safety settings

• options: Named validation checks to enable or disable (e.g., config-syntax: true, docker: true)

Advanced#

Advanced operational settings

• auto_start: Automatically run ‘up’ after initialization completes
• pull_latest_images: Pull the latest Docker images before starting services
• cleanup_on_recreate: Remove volumes when force-recreating services (full data reset)

Version Config#

Version constraint settings

• required_version: Semver constraint the running otto-stack binary must satisfy (e.g., ‘>=1.2.0’)

Sharing Configuration Details#

When sharing is enabled:

1. Containers are prefixed with otto-stack- (e.g., otto-stack-redis)
2. A registry at ~/.otto-stack/shared/containers.yaml tracks which projects use each shared container
3. The down command prompts before stopping shared containers used by other projects
4. Shared containers persist across project switches

Example configurations:

# Share all services (default)
sharing:
  enabled: true

# Share specific services only
sharing:
  enabled: true
  services:
    postgres: true
    redis: true
    kafka: false  # Not shared

# Disable sharing completely
sharing:
  enabled: false

Registry location: ~/.otto-stack/shared/containers.yaml

Service Configuration#

Services are configured through environment variables. Otto-stack generates .otto-stack/generated/.env.generated showing all available variables with defaults:

Example .env.generated:

# # POSTGRES
DATABASE_URL=postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-password}@${POSTGRES_HOST:-localhost}:${POSTGRES_PORT:-5432}/${POSTGRES_DB:-local_dev}
PGHOST=${POSTGRES_HOST:-localhost}
POSTGRES_DB=${POSTGRES_DB:-local_dev}
POSTGRES_HOST=${POSTGRES_HOST:-localhost}
# REDIS
REDIS_HOST=${REDIS_HOST:-localhost}
REDIS_PASSWORD=${REDIS_PASSWORD:-password}
REDIS_PORT=${REDIS_PORT:-6379}
REDIS_URL=redis://:${REDIS_PASSWORD:-password}@${REDIS_HOST:-localhost}:${REDIS_PORT:-6379}

Customizing Services#

Create a .env file in your project root to override defaults:

# Postgres
DATABASE_URL=my_custom_value
PGHOST=my_custom_value
# Redis
REDIS_HOST=my_custom_value
REDIS_PASSWORD=my_custom_value

These values will be used by Docker Compose when starting services.

Service Metadata Files#

Files in .otto-stack/services/ contain service metadata:

.otto-stack/services/postgres.yml:

name: postgres
description: Configuration for postgres service

These are informational and don’t affect service behavior. Configuration happens via environment variables.

Complete Example#

.otto-stack/config.yaml:

project:
  name: my-fullstack-app
  type: docker
stack:
  enabled:
    - postgres
    - redis
    - kafka
validation:
  options:
    config-syntax: true
    docker: true

.env (your customizations):

# Postgres
DATABASE_URL=production_value
PGHOST=production_value
# Redis
REDIS_HOST=production_value
REDIS_PASSWORD=production_value

Next Steps#

• Services Guide - Available services and environment variables
• CLI Reference - Command usage
• Troubleshooting - Common issues