Accessories

Accessories are additional services that run alongside your main application, such as databases, caches, message queues, and other supporting services. They are managed separately from the main service and can be deployed, started, stopped, and removed independently.

Overview

Accessories allow you to:

Add databases (PostgreSQL, MySQL, MongoDB, etc.)
Include caches (Redis, Memcached)
Set up message queues (RabbitMQ, Apache Kafka)
Add monitoring tools (Prometheus, Grafana)
Include other supporting services

Basic Configuration

Define accessories in your deploy.yaml file:


accessories:
  postgres:
    service: my-app-postgres
    image: postgres:15-alpine
    ports: "5432:5432"
    env:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    network: my-app-network
    options:
      restart: always

Configuration Options

Service Name

The service field defines the name of the accessory service. This is used as the container name and for service identification.


service: postgres

Default naming: If not specified, defaults to <main-service>-<accessory-name>

Image

The Docker image to use for the accessory.


image: postgres:15-alpine

Best practices:

Use specific version tags for production
Choose lightweight images when possible
Use official images from trusted sources

Port Mappings

Map host ports to container ports for external access.


ports: "5432:5432"  # Host:Container

Security note: Be careful about exposing ports publicly. See Docker networking documentation for security implications.

Multiple ports:


ports:
  - "5432:5432"  # Database
  - "5433:5432"  # Alternative port

Environment Variables

Configure the accessory with environment variables.


env:
  POSTGRES_DB: myapp
  POSTGRES_USER: user
  POSTGRES_PASSWORD: password
  POSTGRES_INITDB_ARGS: --encoding=UTF-8

Using variables from .env file:


env:
  POSTGRES_PASSWORD: ${DB_PASSWORD}
  POSTGRES_USER: ${DB_USER}

Volumes

Mount host directories or Docker volumes for data persistence.


volumes:
  # Named Docker volumes (recommended)
  - postgres_data:/var/lib/postgresql/data
  
  # Bind mounts
  - ./data:/var/lib/postgresql/data
  
  # Read-only mounts
  - ./config:/etc/postgresql:ro

Volume types:

Named volumes: volume_name:/container/path (recommended for data)
Bind mounts: ./host/path:/container/path
Read-only: Add :ro suffix

Options

Additional Docker run options.


options:
  restart: always
  memory: 512m
  cpus: 0.5

Supported options:

restart: Restart policy (always, unless-stopped, on-failure)
memory: Memory limit (e.g., 512m, 1g)
cpus: CPU limit (e.g., 0.5, 1.0)

Network

The network the accessory will be attached to.


network: custom

Default: Uses the asantiya network if not specified.

Common Accessory Examples

PostgreSQL Database


accessories:
  postgres:
    service: postgres
    image: postgres:15-alpine
    port: "5432:5432"
    env:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8
    volumes:
      - postgres_data:/var/lib/postgresql/data
    options:
      restart: always

MySQL Database


accessories:
  mysql:
    service: mysql
    image: mysql:8.0
    port: "3306:3306"
    env:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=myapp
      - MYSQL_USER=user
      - MYSQL_PASSWORD=password
    volumes:
      - mysql_data:/var/lib/mysql
    options:
      restart: always

Redis Cache


accessories:
  redis:
    service: redis
    image: redis:7-alpine
    port: "6379:6379"
    volumes:
      - redis_data:/data
    options:
      restart: always

MongoDB Database


accessories:
  mongodb:
    service: mongodb
    image: mongo:7
    port: "27017:27017"
    env:
      - MONGO_INITDB_ROOT_USERNAME=admin
      - MONGO_INITDB_ROOT_PASSWORD=password
      - MONGO_INITDB_DATABASE=myapp
    volumes:
      - mongodb_data:/data/db
    options:
      restart: always

RabbitMQ Message Queue


accessories:
  rabbitmq:
    service: rabbitmq
    image: rabbitmq:3-management-alpine
    port: "5672:5672"
    env:
      - RABBITMQ_DEFAULT_USER=admin
      - RABBITMQ_DEFAULT_PASS=password
    volumes:
      - rabbitmq_data:/var/lib/rabbitmq
    options:
      restart: always

Nginx Reverse Proxy


accessories:
  nginx:
    service: nginx
    image: nginx:alpine
    port: "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    options:
      restart: always

Managing Accessories

Deploy Accessories


# Deploy all accessories
asantiya accessory up
 
# Or deploy with main application
asantiya deploy

Start/Stop Accessories


# Start all accessories
asantiya accessory up
 
# Stop all accessories
asantiya accessory down
 
# Restart accessories
asantiya accessory restart

Check Status


# Check status of all accessories
asantiya accessory ls

View Logs


# View logs for specific accessory
asantiya accessory logs postgres
 
# Follow logs in real-time
asantiya accessory logs postgres --follow
 
# Show last N lines
asantiya accessory logs postgres --tail 100

Remove Accessories


# Stop all accessories
asantiya accessory down
 
# Stop with volumes
asantiya accessory down --volumes

Best Practices

1. Use Named Volumes for Data


volumes:
  - postgres_data:/var/lib/postgresql/data  # Good
  # Avoid: - ./data:/var/lib/postgresql/data

2. Set Resource Limits


options:
  memory: 512m
  cpus: 0.5
  restart: always

3. Use Environment Variables for Secrets


env:
  - POSTGRES_PASSWORD=${DB_PASSWORD}  # From .env file

4. Configure Health Checks


# In your Dockerfile or image
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD pg_isready -U user -d myapp || exit 1

5. Use Specific Image Versions


image: postgres:15-alpine  # Good
# Avoid: image: postgres:latest

Advanced Configuration

Multiple Instances


accessories:
  postgres-primary:
    service: postgres-primary
    image: postgres:15-alpine
    port: "5432:5432"
    # ... config
 
  postgres-replica:
    service: postgres-replica
    image: postgres:15-alpine
    port: "5433:5432"
    # ... config

Conditional Accessories

Use different configurations for different environments:


# deploy.dev.yaml
accessories:
  postgres:
    service: postgres-dev
    image: postgres:15-alpine
    # ... dev config
 
# deploy.prod.yaml
accessories:
  postgres:
    service: postgres-prod
    image: postgres:15-alpine
    # ... prod config

For more examples, check out the Examples section or refer to the CLI Reference for accessory management commands.