stack-orchestrator/docs/docker-compose-deployment.md

Docker Compose Deployment Guide

Introduction

What is a Deployer?

In stack-orchestrator, a deployer provides a uniform interface for orchestrating containerized applications. This guide focuses on Docker Compose deployments, which is the default and recommended deployment mode.

While stack-orchestrator also supports Kubernetes (k8s) and Kind (k8s-kind) deployments, those are out of scope for this guide. See the Kubernetes Enhancements documentation for advanced deployment options.

Prerequisites

To deploy stacks using Docker Compose, you need:

• Docker Engine (20.10+)
• Docker Compose plugin (v2.0+)
• Python 3.8+
• stack-orchestrator installed (laconic-so)

That's it! No additional infrastructure is required. If you have Docker installed, you're ready to deploy.

Deployment Workflow

The typical deployment workflow consists of four main steps:

1. Setup repositories and build containers (first time only)
2. Initialize deployment specification
3. Create deployment directory
4. Start and manage services

Quick Start Example

Here's a complete example using the built-in test stack:

# Step 1: Setup (first time only)
laconic-so --stack test setup-repositories
laconic-so --stack test build-containers

# Step 2: Initialize deployment spec
laconic-so --stack test deploy init --output test-spec.yml

# Step 3: Create deployment directory
laconic-so --stack test deploy create \
  --spec-file test-spec.yml \
  --deployment-dir test-deployment

# Step 4: Start services
laconic-so deployment --dir test-deployment start

# View running services
laconic-so deployment --dir test-deployment ps

# View logs
laconic-so deployment --dir test-deployment logs

# Stop services (preserves data)
laconic-so deployment --dir test-deployment stop

Deployment Workflows

Stack-orchestrator supports two deployment workflows:

1. Deployment Directory Workflow (Recommended)

This workflow creates a persistent deployment directory that contains all configuration and data.

When to use:

• Production deployments
• When you need to preserve configuration
• When you want to manage multiple deployments
• When you need persistent volume data

Example:

# Initialize deployment spec
laconic-so --stack fixturenet-eth deploy init --output eth-spec.yml

# Optionally edit eth-spec.yml to customize configuration

# Create deployment directory
laconic-so --stack fixturenet-eth deploy create \
  --spec-file eth-spec.yml \
  --deployment-dir my-eth-deployment

# Start the deployment
laconic-so deployment --dir my-eth-deployment start

# Manage the deployment
laconic-so deployment --dir my-eth-deployment ps
laconic-so deployment --dir my-eth-deployment logs
laconic-so deployment --dir my-eth-deployment stop

2. Quick Deploy Workflow

This workflow deploys directly without creating a persistent deployment directory.

When to use:

• Quick testing
• Temporary deployments
• Simple stacks that don't require customization

Example:

# Start the stack directly
laconic-so --stack test deploy up

# Check service status
laconic-so --stack test deploy port test 80

# View logs
laconic-so --stack test deploy logs

# Stop (preserves volumes)
laconic-so --stack test deploy down

# Stop and remove volumes
laconic-so --stack test deploy down --delete-volumes

Real-World Example: Ethereum Fixturenet

Deploy a local Ethereum testnet with Geth and Lighthouse:

# Setup (first time only)
laconic-so --stack fixturenet-eth setup-repositories
laconic-so --stack fixturenet-eth build-containers

# Initialize with default configuration
laconic-so --stack fixturenet-eth deploy init --output eth-spec.yml

# Create deployment
laconic-so --stack fixturenet-eth deploy create \
  --spec-file eth-spec.yml \
  --deployment-dir fixturenet-eth-deployment

# Start the network
laconic-so deployment --dir fixturenet-eth-deployment start

# Check status
laconic-so deployment --dir fixturenet-eth-deployment ps

# Access logs from specific service
laconic-so deployment --dir fixturenet-eth-deployment logs fixturenet-eth-geth-1

# Stop the network (preserves blockchain data)
laconic-so deployment --dir fixturenet-eth-deployment stop

# Start again - blockchain data is preserved
laconic-so deployment --dir fixturenet-eth-deployment start

# Clean up everything including data
laconic-so deployment --dir fixturenet-eth-deployment stop --delete-volumes

Configuration

Passing Configuration Parameters

Configuration can be passed in three ways:

1. At init time via --config flag:

laconic-so --stack test deploy init --output spec.yml \
  --config PARAM1=value1,PARAM2=value2

2. Edit the spec file after init:

# Initialize
laconic-so --stack test deploy init --output spec.yml

# Edit spec.yml
vim spec.yml

Example spec.yml:

stack: test
config:
  PARAM1: value1
  PARAM2: value2

3. Docker Compose defaults:

Environment variables defined in the stack's docker-compose-*.yml files are used as defaults. Configuration from the spec file overrides these defaults.

Port Mapping

By default, services are accessible on randomly assigned host ports. To find the mapped port:

# Find the host port for container port 80 on service 'webapp'
laconic-so deployment --dir my-deployment port webapp 80

# Output example: 0.0.0.0:32768

To configure fixed ports, edit the spec file before creating the deployment:

network:
  ports:
    webapp:
      - '8080:80'  # Maps host port 8080 to container port 80
    api:
      - '3000:3000'

Then create the deployment:

laconic-so --stack my-stack deploy create \
  --spec-file spec.yml \
  --deployment-dir my-deployment

Volume Persistence

Volumes are preserved between stop/start cycles by default:

# Stop but keep data
laconic-so deployment --dir my-deployment stop

# Start again - data is still there
laconic-so deployment --dir my-deployment start

To completely remove all data:

# Stop and delete all volumes
laconic-so deployment --dir my-deployment stop --delete-volumes

Volume data is stored in <deployment-dir>/data/.

Common Operations

Viewing Logs

# All services, continuous follow
laconic-so deployment --dir my-deployment logs --follow

# Last 100 lines from all services
laconic-so deployment --dir my-deployment logs --tail 100

# Specific service only
laconic-so deployment --dir my-deployment logs webapp

# Combine options
laconic-so deployment --dir my-deployment logs --tail 50 --follow webapp

Executing Commands in Containers

# Execute a command in a running service
laconic-so deployment --dir my-deployment exec webapp ls -la

# Interactive shell
laconic-so deployment --dir my-deployment exec webapp /bin/bash

# Run command with specific environment variables
laconic-so deployment --dir my-deployment exec webapp env VAR=value command

Checking Service Status

# List all running services
laconic-so deployment --dir my-deployment ps

# Check using Docker directly
docker ps

Updating a Running Deployment

If you need to change configuration after deployment:

# 1. Edit the spec file
vim my-deployment/spec.yml

# 2. Regenerate configuration
laconic-so deployment --dir my-deployment update

# 3. Restart services to apply changes
laconic-so deployment --dir my-deployment stop
laconic-so deployment --dir my-deployment start

Multi-Service Deployments

Many stacks deploy multiple services that work together:

# Deploy a stack with multiple services
laconic-so --stack laconicd-with-console deploy init --output spec.yml
laconic-so --stack laconicd-with-console deploy create \
  --spec-file spec.yml \
  --deployment-dir laconicd-deployment

laconic-so deployment --dir laconicd-deployment start

# View all services
laconic-so deployment --dir laconicd-deployment ps

# View logs from specific services
laconic-so deployment --dir laconicd-deployment logs laconicd
laconic-so deployment --dir laconicd-deployment logs console

ConfigMaps

ConfigMaps allow you to mount configuration files into containers:

# 1. Create the config directory in your deployment
mkdir -p my-deployment/data/my-config
echo "database_url=postgres://localhost" > my-deployment/data/my-config/app.conf

# 2. Reference in spec file
vim my-deployment/spec.yml

Add to spec.yml:

configmaps:
  my-config: ./data/my-config

# 3. Restart to apply
laconic-so deployment --dir my-deployment stop
laconic-so deployment --dir my-deployment start

The files will be mounted in the container at /config/ (or as specified by the stack).

Deployment Directory Structure

A typical deployment directory contains:

my-deployment/
├── compose/
│   └── docker-compose-*.yml    # Generated compose files
├── config.env                   # Environment variables
├── deployment.yml              # Deployment metadata
├── spec.yml                    # Deployment specification
└── data/                       # Volume mounts and configs
    ├── service-data/           # Persistent service data
    └── config-maps/            # ConfigMap files

Troubleshooting

Common Issues

Problem: "Cannot connect to Docker daemon"

# Ensure Docker is running
docker ps

# Start Docker if needed (macOS)
open -a Docker

# Start Docker (Linux)
sudo systemctl start docker

Problem: "Port already in use"

# Either stop the conflicting service or use different ports
# Edit spec.yml before creating deployment:

network:
  ports:
    webapp:
      - '8081:80'  # Use 8081 instead of 8080

Problem: "Image not found"

# Build containers first
laconic-so --stack your-stack build-containers

Problem: Volumes not persisting

# Check if you used --delete-volumes when stopping
# Volume data is in: <deployment-dir>/data/

# Don't use --delete-volumes if you want to keep data:
laconic-so deployment --dir my-deployment stop

# Only use --delete-volumes when you want to reset completely:
laconic-so deployment --dir my-deployment stop --delete-volumes

Problem: Services not starting

# Check logs for errors
laconic-so deployment --dir my-deployment logs

# Check Docker container status
docker ps -a

# Try stopping and starting again
laconic-so deployment --dir my-deployment stop
laconic-so deployment --dir my-deployment start

Inspecting Deployment State

# Check deployment directory structure
ls -la my-deployment/

# Check running containers
docker ps

# Check container details
docker inspect <container-name>

# Check networks
docker network ls

# Check volumes
docker volume ls

CLI Commands Reference

Stack Operations

# Clone required repositories
laconic-so --stack <name> setup-repositories

# Build container images
laconic-so --stack <name> build-containers

Deployment Initialization

# Initialize deployment spec with defaults
laconic-so --stack <name> deploy init --output <spec-file>

# Initialize with configuration
laconic-so --stack <name> deploy init --output <spec-file> \
  --config PARAM1=value1,PARAM2=value2

Deployment Creation

# Create deployment directory from spec
laconic-so --stack <name> deploy create \
  --spec-file <spec-file> \
  --deployment-dir <dir>

Deployment Management

# Start all services
laconic-so deployment --dir <dir> start

# Stop services (preserves volumes)
laconic-so deployment --dir <dir> stop

# Stop and remove volumes
laconic-so deployment --dir <dir> stop --delete-volumes

# List running services
laconic-so deployment --dir <dir> ps

# View logs
laconic-so deployment --dir <dir> logs [--tail N] [--follow] [service]

# Show mapped port
laconic-so deployment --dir <dir> port <service> <private-port>

# Execute command in service
laconic-so deployment --dir <dir> exec <service> <command>

# Update configuration
laconic-so deployment --dir <dir> update

Quick Deploy Commands

# Start stack directly
laconic-so --stack <name> deploy up

# Stop stack
laconic-so --stack <name> deploy down [--delete-volumes]

# View logs
laconic-so --stack <name> deploy logs

# Show port mapping
laconic-so --stack <name> deploy port <service> <port>

Related Documentation

• CLI Reference - Complete CLI command documentation
• Adding a New Stack - Creating custom stacks
• Specification - Internal structure and design
• Kubernetes Enhancements - Advanced K8s deployment options
• Web App Deployment - Deploying web applications

Examples

For more examples, see the test scripts:

• scripts/quick-deploy-test.sh - Quick deployment example
• tests/deploy/run-deploy-test.sh - Comprehensive test showing all features

Summary

• Docker Compose is the default and recommended deployment mode
• Two workflows: deployment directory (recommended) or quick deploy
• The standard workflow is: setup → build → init → create → start
• Configuration is flexible with multiple override layers
• Volume persistence is automatic unless explicitly deleted
• All deployment state is contained in the deployment directory
• For Kubernetes deployments, see separate K8s documentation

You're now ready to deploy stacks using stack-orchestrator with Docker Compose!