Skip to main content

Docker Compose Deployment Architecture

Overview​

Docker Compose deployment provides a manual, command-line approach to deploying Chatty AI. This method gives administrators direct control over the deployment process without requiring Portainer infrastructure.

Architecture​

┌─────────────────────────────────────────────────────┐
│  Docker Host                                        │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │  Administrator (SSH/Direct Access)         │    │
│  └────────────────┬───────────────────────────┘    │
│                   │ docker-compose commands         │
│                   ▼                                 │
│  ┌────────────────────────────────────────────┐    │
│  │  Docker Engine                             │    │
│  │  - Reads docker-compose.yaml               │    │
│  │  - Reads .env file                         │    │
│  │  - Manages containers and volumes          │    │
│  └────────────────┬───────────────────────────┘    │
│                   │                                 │
│                   ▼                                 │
│  ┌────────────────────────────────────────────┐    │
│  │  Chatty AI Stack                           │    │
│  │  - nginx, chattyai, db, qdrant, n8n, etc.  │    │
│  └────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

Deployment Package​

The Docker Compose deployment uses files from the deploy/ folder:

Core Files​

  • docker-compose.yaml: Stack definition with all services
  • .env.example: Template environment file
  • README.md: Deployment instructions

Deployment Process​

  1. Copy Deployment Package to Docker host
  2. Create .env File from .env.example
  3. Configure Environment Variables in .env
  4. Prepare Certificates and mount directories
  5. Run docker-compose up -d to start stack
  6. Verify Deployment using docker-compose and docker commands

Manual Operations​

Starting the Stack​

cd /path/to/deploy
docker-compose up -d

Stopping the Stack​

docker-compose down

Viewing Logs​

docker-compose logs -f [service-name]

Checking Status​

docker-compose ps

Updating Images​

docker-compose pull
docker-compose up -d

Environment Configuration​

.env File​

All configuration is managed through the .env file:

# Copy example
cp .env.example .env

# Edit with your values
vi .env

Required Variables​

Must be set before deployment:

  • Domain names (CHATTYAI_DOMAIN, N8N_DOMAIN, DATABASES_DOMAIN)
  • URLs (CHATTYAI_URL, N8N_URL, DATABASES_URL)
  • Database password (DB_PASSWORD)
  • JWT secret (CHATTYAI_JWT_SECRET_KEY)
  • API keys (CHATTYAI_API_KEY, CHATTYAI_AI_API_KEY)
  • Admin password (CHATTYAI_ADMIN_PASSWORD)

Certificate Management​

Certificate Structure​

/path/to/certs/
├── chattyai/
│   ├── fullchain.pem
│   └── privkey.pem
├── n8n/
│   ├── fullchain.pem
│   └── privkey.pem
└── databases/
    ├── fullchain.pem
    └── privkey.pem

Mounting Certificates​

Certificates are mounted in docker-compose.yaml:

volumes:
  - /etc/nginx/certs:/etc/nginx/certs:ro

Ensure certificates exist at /etc/nginx/certs on the host before starting.

Advantages of Docker Compose Deployment​

Direct Control​

  • Full Transparency: See exactly what commands are executed
  • No Abstraction: Direct interaction with Docker
  • Customization: Easy to modify compose file for specific needs
  • Debugging: Direct access to Docker commands and logs

Minimal Dependencies​

  • No Portainer Required: Only Docker and Docker Compose needed
  • Simpler Infrastructure: Fewer moving parts
  • Standard Tools: Uses widely-known Docker tooling

Flexibility​

  • Custom Modifications: Easy to add custom services or configurations
  • Script Integration: Can be integrated into custom deployment scripts
  • CI/CD Friendly: Works well with automated deployment pipelines

When to Use Docker Compose​

✅ Use Docker Compose when:

  • Portainer infrastructure is not available
  • You prefer command-line operations
  • You need maximum transparency
  • You have custom deployment requirements
  • You're integrating with existing automation
  • You have only one or few deployments

❌ Consider Portainer when:

  • You manage multiple environments
  • You prefer GUI-based management
  • You need remote management capabilities
  • You want simplified update processes

Operational Responsibilities​

With Docker Compose deployment, administrators are responsible for:

Deployment​

  • Copying deployment package to host
  • Creating and configuring .env file
  • Preparing certificate directories
  • Running docker-compose commands
  • Verifying successful startup

Updates​

  • Obtaining new deployment package
  • Comparing new and old compose files
  • Updating .env file with new variables
  • Pulling new images
  • Recreating containers
  • Validating update success

Monitoring​

  • Checking container health manually
  • Reviewing logs for errors
  • Monitoring disk usage
  • Tracking resource consumption

Troubleshooting​

  • Diagnosing container failures
  • Reviewing Docker logs
  • Fixing configuration issues
  • Resolving network problems

Best Practices​

  1. Version Control .env Template: Keep .env.example in version control, not actual .env
  2. Document Custom Changes: If you modify docker-compose.yaml, document why
  3. Test Before Production: Test deployment in staging environment
  4. Backup Configuration: Keep backups of .env and custom configurations
  5. Use Absolute Paths: Use absolute paths for volume mounts
  6. Monitor Logs: Regularly check logs for errors
  7. Plan Upgrades: Review changelog before upgrading
  8. Keep Notes: Document deployment-specific decisions

Security Considerations​

.env File Security​

  • Permissions: Set restrictive permissions (600 or 640)
  • No Version Control: Never commit .env to git
  • Secure Storage: Store backups securely
  • Access Control: Limit who can read .env file

Docker Socket Access​

  • SSH Security: Secure SSH access to Docker host
  • User Permissions: Limit who can run docker commands
  • Audit Logging: Log docker command execution

Certificate Security​

  • File Permissions: Ensure certificates are readable by Docker
  • Secure Transfer: Use secure methods to transfer certificates to host
  • Rotation: Plan for certificate renewal and rotation

Comparison with Portainer​

AspectDocker ComposePortainer
Deployment MethodCommand-lineGUI
Remote ManagementRequires SSHVia Edge Agent
Update ProcessManualOne-click
Learning CurveLow (if familiar with Docker)Moderate
InfrastructureMinimalRequires Portainer Server
TransparencyHighModerate
Operational OverheadHigherLower
Multi-EnvironmentPer-environment managementCentralized
Audit TrailManualBuilt-in
RollbackManualSimple

Troubleshooting​

Common Issues​

Containers Not Starting

  • Check .env file for missing variables
  • Verify certificate paths exist
  • Review logs: docker-compose logs

Port Conflicts

  • Check if ports are already in use
  • Modify port mappings in .env or compose file

Volume Permission Issues

  • Ensure volume directories exist
  • Check directory permissions
  • Verify Docker has access to mount paths

Image Pull Failures

  • Verify internet connectivity
  • Check Docker registry access
  • Ensure correct image tags in compose file

Cross-Reference​