Skip to main content

Docker Setup

Deploy Actyze locally using Docker Compose for development and testing.

Prerequisites​

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • 8GB+ RAM available for Docker
  • Internet connection for external services

Repository Structure​

The Docker setup is located in the dashboard repository:

dashboard/
├── docker/
│   ├── docker-compose.yml      # Main compose file
│   ├── env.example             # Environment template
│   ├── start.sh                # Start script
│   ├── stop.sh                 # Stop script
│   └── README.md               # Docker documentation
├── nexus/                      # FastAPI backend
├── frontend/                   # React frontend
└── schema-service/             # FAISS schema service

Installation Steps​

1. Clone Repository​

git clone https://github.com/actyze/dashboard-docker.git
cd dashboard

2. Configure Environment​

# Copy environment template
cp docker/env.example docker/.env

# Edit configuration
nano docker/.env

3. Configure LLM Provider​

Add your LLM API key to .env:

# LLM Configuration - Choose your provider
EXTERNAL_LLM_PROVIDER=perplexity  # or anthropic, openai, groq, etc.
PERPLEXITY_API_KEY=your-api-key-here
EXTERNAL_LLM_AUTH_TYPE=bearer

# Or for Anthropic Claude
EXTERNAL_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-your-key
EXTERNAL_LLM_AUTH_TYPE=x-api-key

See: LLM Provider Configuration for all supported providers.

4. Configure Database​

# PostgreSQL Configuration (local)
POSTGRES_PASSWORD=dashboard_password
POSTGRES_USER=dashboard_user
POSTGRES_DB=dashboard

# Trino Configuration (external - optional)
TRINO_HOST=your-trino-host
TRINO_PORT=443
TRINO_USER=your-username
TRINO_PASSWORD=your-password
TRINO_SSL=true
TRINO_SSL_VERIFY=false  # Set to false for self-signed certificates

5. Start Services​

# Using the start script (recommended)
./docker/start.sh

# Or using Docker Compose directly
cd docker
docker-compose up -d

The script will:

  • Build Docker images locally
  • Start all services
  • Initialize the database
  • Run health checks

6. Verify Installation​

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

# Check specific service
docker-compose logs nexus

Access Services​

Once running, access:

Service Architecture​

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Nexus API      │    │   PostgreSQL    │
│   (nginx:3000)  │───▶│   (FastAPI:8000) │───▶│   (postgres:5432)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  Schema Service  │
                       │  (FAISS:8001)    │
                       └──────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  External Trino  │
                       │  (Optional)      │
                       └──────────────────┘

Management Commands​

Start Services​

# Start all services
./docker/start.sh

# Start without rebuilding
./docker/start.sh --no-build

# Start and follow logs
./docker/start.sh --logs

Stop Services​

# Stop services (preserve data)
./docker/stop.sh

# Stop and remove all data
./docker/stop.sh --clean

View Logs​

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f nexus
docker-compose logs -f frontend

Restart Services​

# Restart all
docker-compose restart

# Restart specific service
docker-compose restart nexus

Development Workflow​

1. Make Code Changes​

Edit files in your IDE:

  • Frontend: frontend/src/
  • Backend: nexus/app/
  • Schema Service: schema-service/app/

2. Rebuild Changed Service​

# Rebuild specific service
docker-compose build nexus

# Restart the service
docker-compose up -d nexus

3. View Changes​

Refresh your browser or test the API endpoint.

4. Debug Issues​

# Check logs
docker-compose logs -f nexus

# Access container shell
docker-compose exec nexus bash

# Check environment variables
docker-compose exec nexus env

Configuration Options​

Using External Databases​

Edit .env to use external PostgreSQL or Trino:

# External PostgreSQL
POSTGRES_HOST=external-postgres.example.com
POSTGRES_PORT=5432
POSTGRES_USER=your-username
POSTGRES_PASSWORD=your-password

# External Trino
TRINO_HOST=external-trino.example.com
TRINO_PORT=443
TRINO_USER=your-username
TRINO_PASSWORD=your-password
TRINO_SSL=true
TRINO_SSL_VERIFY=false  # Set to false for self-signed certificates

Then start with external profile:

./docker/start.sh --profile external

Resource Limits​

Edit docker-compose.yml to adjust resource limits:

services:
  nexus:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Troubleshooting​

Port Conflicts​

# Check what's using the ports
lsof -i :3000
lsof -i :8000
lsof -i :5432

# Stop conflicting services or change ports in docker-compose.yml

Memory Issues​

# Check Docker memory usage
docker stats

# Increase Docker Desktop memory:
# Docker Desktop → Settings → Resources → Memory → 8GB+

Database Connection Issues​

# Check PostgreSQL logs
docker-compose logs postgres

# Verify database initialization
docker-compose exec postgres psql -U dashboard_user -d dashboard -c "\dt"

# Reset database
docker-compose down -v
docker-compose up -d

LLM API Issues​

# Check Nexus logs for API errors
docker-compose logs nexus | grep -i "llm\|error"

# Verify environment variables
docker-compose exec nexus env | grep EXTERNAL_LLM

# Test API key manually
curl -X POST https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonar-reasoning-pro", "messages": [{"role": "user", "content": "test"}]}'

Image Build Failures​

# Clean Docker cache
docker system prune -a

# Rebuild without cache
docker-compose build --no-cache

# Check disk space
df -h

Testing​

Run Automated Tests​

# Test deployment
./scripts/test-docker-deployment.sh

# Test specific service
docker-compose exec nexus pytest
docker-compose exec frontend npm test

Manual Testing​

# Test health endpoint
curl http://localhost:8000/health

# Test SQL generation (requires auth token)
curl -X POST http://localhost:8000/api/generate-sql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "nl_query": "Show all customers",
    "conversation_history": []
  }'

Upgrading​

Update to Latest Version​

# Pull latest code
git pull origin main

# Rebuild images
docker-compose build

# Restart services
docker-compose up -d

Database Migrations​

# Run migrations
docker-compose exec nexus alembic upgrade head

# Or use migration script
./docker/migrate.sh

Production Considerations​

Security​

  • Use strong passwords for all services
  • Enable SSL/TLS for external communications
  • Configure proper authentication
  • Apply regular security updates for base images

Performance​

  • Use production-optimized Docker images
  • Implement proper resource limits
  • Set up monitoring and logging
  • Use external managed databases

Scalability​

For production deployments with high availability and scalability, use Helm charts instead:

→ Helm Deployment Guide

Operational Notes​

Docker Compose is configured with sensible defaults for local development:

  • Cache: Query results cached for 30min, LLM responses for 2hr (reduces API costs)
  • Timeouts: 30s for SQL/LLM/Schema service calls (suitable for dev/test)
  • Connection Pool: 20 base connections + 30 overflow (sufficient for local use)
  • Retry Logic: Automatic retries with exponential backoff for transient failures

These defaults work well for local development. For production deployments with custom requirements, use Helm charts where all operational settings are fully configurable.

Next Steps​

Additional Resources​