Docker Targets

Docker targets enable command execution within containerized environments. Xec provides comprehensive Docker integration with support for container lifecycle management, volume mounting, networking, and Docker Compose.

Basic Configuration

Define Docker containers in the targets.containers section:

targets:
  containers:
    app:
      image: node:18
      workdir: /app
      volumes:
        - ./src:/app

Container Properties

Essential Properties

targets:
  containers:
    basic:
      # Container identification (one required)
      image: ubuntu:22.04          # Docker image to use
      container: existing-container # OR existing container name/ID
      
      # Common settings
      workdir: /workspace          # Working directory
      user: "1000:1000"           # User ID or name

Advanced Properties

targets:
  containers:
    advanced:
      image: node:18-alpine
      
      # Volumes
      volumes:
        - ./src:/app:rw           # Read-write mount
        - ./config:/config:ro     # Read-only mount
        - data:/data             # Named volume
        - /tmp:/host-tmp         # Absolute path
      
      # Networking
      ports:
        - "3000:3000"           # Host:Container
        - "8080:80"
      network: my-network        # Network name
      
      # Container settings
      restart: unless-stopped    # Restart policy
      privileged: false         # Privileged mode
      tty: true                # Allocate TTY
      autoRemove: true         # Remove after exit
      
      # Resource limits
      memory: 512m              # Memory limit
      cpus: "0.5"              # CPU limit
      
      # Health check
      healthcheck:
        test: ["CMD", "curl", "-f", "http://localhost/health"]
        interval: 30s
        timeout: 10s
        retries: 3
        startPeriod: 40s

Execution Modes

Run Mode (Default)

Creates new container for each command:

targets:
  containers:
    ephemeral:
      image: alpine:latest
      runMode: run  # Default
      autoRemove: true
      
      # Each command creates new container
      # xec in containers.ephemeral "echo test"

Exec Mode

Executes in existing container:

targets:
  containers:
    persistent:
      container: my-app-container  # Existing container
      runMode: exec
      
      # Commands run in existing container
      # xec in containers.persistent "ps aux"

Hybrid Mode

targets:
  containers:
    smart:
      image: postgres:15
      container: db-container
      # Automatically uses exec if container exists,
      # otherwise creates with run

Volume Management

Volume Types

targets:
  containers:
    volumes-demo:
      image: ubuntu:22.04
      volumes:
        # Bind mount (relative path)
        - ./app:/app
        
        # Bind mount (absolute path)
        - /var/log:/logs:ro
        
        # Named volume
        - mydata:/data
        
        # Anonymous volume
        - /tmp
        
        # With options
        - type: bind
          source: ./config
          target: /config
          readonly: true

Volume Permissions

targets:
  containers:
    permissions:
      image: node:18
      volumes:
        - ./src:/app:rw      # Read-write (default)
        - ./config:/config:ro # Read-only
        - ./cache:/cache:rw,z # With SELinux label
      
      # Run as specific user
      user: "1000:1000"

Networking

Port Mapping

targets:
  containers:
    web:
      image: nginx:alpine
      ports:
        - "80:80"        # HTTP
        - "443:443"      # HTTPS
        - "127.0.0.1:8080:8080"  # Bind to localhost only
        - "3000-3005:3000-3005"  # Port range

Network Modes

targets:
  containers:
    # Default bridge network
    bridge:
      image: alpine
      network: bridge
    
    # Custom network
    custom:
      image: alpine
      network: my-app-network
    
    # Host network
    host:
      image: alpine
      network: host
    
    # No network
    isolated:
      image: alpine
      network: none

Container Linking

targets:
  containers:
    database:
      image: postgres:15
      network: app-network
      
    app:
      image: node:18
      network: app-network
      env:
        DB_HOST: database  # Can reference by name

Environment Variables

targets:
  containers:
    configured:
      image: node:18
      env:
        # Simple values
        NODE_ENV: production
        PORT: "3000"
        
        # From secrets
        API_KEY: ${secrets.api_key}
        DB_PASSWORD: ${secrets.db_password}
        
        # Complex values
        DATABASE_URL: "postgres://user:pass@db:5432/mydb"
        
        # From host environment
        HOME: ${env.HOME}
        USER: ${env.USER}

Environment Files

targets:
  containers:
    from-file:
      image: node:18
      envFile:
        - .env
        - .env.production

Container Lifecycle

Restart Policies

targets:
  containers:
    # Always restart
    critical:
      image: redis:alpine
      restart: always
    
    # Restart on failure
    resilient:
      image: app:latest
      restart: on-failure
      restartMaxRetries: 5
    
    # Don't restart
    oneshot:
      image: alpine
      restart: "no"

Auto-removal

targets:
  containers:
    # Remove after execution
    temporary:
      image: alpine
      autoRemove: true
      
    # Keep container
    persistent:
      image: postgres:15
      autoRemove: false

Health Checks

targets:
  containers:
    healthy:
      image: nginx:alpine
      healthcheck:
        # Command-based check
        test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
        
        # Or shell command
        # test: "curl -f http://localhost/ || exit 1"
        
        # Timing configuration
        interval: 30s      # Check interval
        timeout: 10s       # Check timeout
        retries: 3        # Failure retries
        startPeriod: 40s  # Grace period

Labels and Metadata

targets:
  containers:
    labeled:
      image: app:latest
      labels:
        app: myapp
        environment: production
        version: "1.2.3"
        "com.example.team": backend
        "com.example.git-commit": ${env.GIT_COMMIT}

Docker Compose Integration

targets:
  # Global compose configuration
  $compose:
    file: docker-compose.yml
    project: myproject
  
  containers:
    # Reference compose service
    web:
      $service: web
      
    # Override compose settings
    db:
      $service: database
      env:
        POSTGRES_PASSWORD: ${secrets.db_password}

Resource Limits

targets:
  containers:
    limited:
      image: node:18
      
      # Memory limits
      memory: 512m           # Memory limit
      memorySwap: 1g        # Memory + swap limit
      memoryReservation: 256m # Soft limit
      
      # CPU limits
      cpus: "0.5"           # Number of CPUs
      cpuShares: 512        # CPU shares (relative)
      cpusetCpus: "0,1"     # CPU cores to use
      
      # Other limits
      pidsLimit: 100        # Process limit
      ulimits:
        nofile:
          soft: 65535
          hard: 65535

Security Configuration

User and Groups

targets:
  containers:
    secure:
      image: node:18
      
      # Run as specific user
      user: "1000:1000"     # UID:GID
      # OR
      user: appuser         # Username
      
      # Additional groups
      groupAdd:
        - docker
        - video

Capabilities

targets:
  containers:
    capabilities:
      image: alpine
      
      # Add capabilities
      capAdd:
        - SYS_ADMIN
        - NET_ADMIN
      
      # Drop capabilities
      capDrop:
        - ALL
      
      # Privileged mode (all capabilities)
      privileged: false

Security Options

targets:
  containers:
    hardened:
      image: alpine
      securityOpt:
        - no-new-privileges
        - seccomp=unconfined
        - apparmor=docker-default
      readonlyRootfs: true

Docker Socket Access

targets:
  containers:
    docker-in-docker:
      image: docker:dind
      privileged: true
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock

Custom Docker Configuration

Docker Host

targets:
  containers:
    remote:
      image: alpine
      dockerHost: tcp://remote-docker:2376
      dockerCertPath: ~/.docker/certs

Registry Authentication

targets:
  containers:
    private:
      image: registry.example.com/app:latest
      registryAuth:
        username: ${secrets.registry_user}
        password: ${secrets.registry_password}

Real-World Examples

Development Environment

targets:
  containers:
    dev:
      image: node:18
      workdir: /app
      volumes:
        - .:/app
        - node_modules:/app/node_modules
      ports:
        - "3000:3000"
        - "9229:9229"  # Debugger
      env:
        NODE_ENV: development
        DEBUG: "*"
      tty: true
      stdin: true

Production Database

targets:
  containers:
    postgres:
      image: postgres:15-alpine
      restart: unless-stopped
      volumes:
        - postgres_data:/var/lib/postgresql/data
        - ./backup:/backup
      env:
        POSTGRES_DB: production
        POSTGRES_USER: appuser
        POSTGRES_PASSWORD: ${secrets.db_password}
      ports:
        - "127.0.0.1:5432:5432"
      healthcheck:
        test: ["CMD-SHELL", "pg_isready -U appuser"]
        interval: 10s
        timeout: 5s
        retries: 5

Build Environment

targets:
  containers:
    builder:
      image: node:18
      workdir: /build
      volumes:
        - .:/build:ro
        - build_cache:/build/.cache
        - dist:/build/dist
      env:
        CI: true
        NPM_TOKEN: ${secrets.npm_token}
      user: "1000:1000"
      autoRemove: true

Troubleshooting

Container Debugging

# Check container status
docker ps -a

# View container logs
xec logs containers.app

# Execute debug commands
xec in containers.app "ps aux"
xec in containers.app "env | sort"

Common Issues

Image Not Found

# Ensure image exists
targets:
  containers:
    app:
      image: node:18  # Use official images
      # OR pull explicitly
      imagePullPolicy: always

Permission Denied

# Fix volume permissions
targets:
  containers:
    fixed:
      image: node:18
      user: "$(id -u):$(id -g)"  # Match host user
      volumes:
        - .:/app:rw,z  # SELinux label if needed

Port Already in Use

# Use different ports
targets:
  containers:
    app:
      ports:
        - "3001:3000"  # Map to different host port

Best Practices

1. Use Specific Tags

# Good - specific version
image: node:18.17.1-alpine

# Bad - latest tag
image: node:latest

2. Minimize Layers

# Combine related operations
targets:
  containers:
    efficient:
      image: alpine
      command: sh -c "apk add --no-cache git && git clone repo"

3. Use .dockerignore

# .dockerignore
node_modules
.git
*.log
.env

4. Security First

targets:
  containers:
    secure:
      image: alpine
      user: nobody        # Non-root user
      readonlyRootfs: true  # Read-only filesystem
      capDrop: [ALL]      # Drop all capabilities

5. Resource Limits

targets:
  containers:
    limited:
      image: node:18
      memory: 512m      # Always set limits
      cpus: "0.5"

Next Steps

Kubernetes Targets - Kubernetes pod configuration

Basic Configuration​

Container Properties​

Essential Properties​

Advanced Properties​

Execution Modes​

Run Mode (Default)​

Exec Mode​

Hybrid Mode​

Volume Management​

Volume Types​

Volume Permissions​

Networking​

Port Mapping​

Network Modes​

Container Linking​

Environment Variables​

Environment Files​

Container Lifecycle​

Restart Policies​

Auto-removal​

Health Checks​

Labels and Metadata​

Docker Compose Integration​

Resource Limits​

Security Configuration​

User and Groups​

Capabilities​

Security Options​

Docker Socket Access​

Custom Docker Configuration​

Docker Host​

Registry Authentication​

Real-World Examples​

Development Environment​

Production Database​

Build Environment​

Troubleshooting​

Container Debugging​

Common Issues​

Image Not Found​

Permission Denied​

Port Already in Use​

Best Practices​

1. Use Specific Tags​

2. Minimize Layers​

3. Use .dockerignore​

4. Security First​

5. Resource Limits​

Next Steps​

See Also​