Skip to main content

​
Overview

AmbioSys uses Docker Compose to orchestrate multiple services including backend APIs, GPT bot service, Redis cache, and optional frontend. The platform provides separate configurations for development, production, and local overrides.

​
Architecture

The AmbioSys Docker setup consists of the following services:
  • Redis (port 6379): Session storage and caching
  • Backend API (port 3000): Main Node.js application server
  • GPT Bot Service (port 4500): AI-powered WhatsApp bot
  • Frontend (port 5173): React + Vite application (dev only)
All services communicate through a custom bridge network named ambio_net.

​
Prerequisites

Before you begin, ensure you have:
  • Docker Engine 20.10 or higher
  • Docker Compose V2 or higher
  • At least 2GB of available RAM
  • 5GB of free disk space

​
Configuration Files

AmbioSys provides multiple Docker Compose configurations:
FilePurposeServices
docker-compose.ymlBase configurationRedis, Backend, GPT Bot
docker-compose.dev.ymlDevelopment with hot-reloadAll services + Frontend
docker-compose.prod.ymlProduction deploymentBackend, GPT Bot, Redis
docker-compose.override.ymlLocal development overridesVolume mounts for hot-reload

​
Development Setup

1

Clone the repository

git clone <repository-url>
cd source
2

Configure environment variables

Create environment files for each service:
# Backend environment
cp Backend/web-ambiotec/.env.example Backend/web-ambiotec/.env.dev

# Bot environment
cp Backend/gpt4-ambiotec-bot/.env.example Backend/gpt4-ambiotec-bot/.env.dev

# Frontend environment
cp Frontend/.env.example Frontend/.env.dev
See Environment Variables for required configuration.
3

Start development environment

docker-compose -f docker-compose.dev.yml up -d
4

Verify services are running

docker-compose ps
Expected output:
NAME                  STATUS    PORTS
ambiotec-redis        Up        0.0.0.0:6379->6379/tcp
ambiotec-backend      Up        0.0.0.0:3000->3000/tcp
gpt4-ambiotec-bot     Up        0.0.0.0:4500->4500/tcp
ambiotec-frontend     Up        0.0.0.0:5173->5173/tcp

​
Production Setup

Production deployment uses pre-built Docker images from Docker Hub. Ensure images are built and pushed before deploying.
1

Set environment variables

Create production environment file:
touch .env.prod
Configure all required variables (see Environment Variables).
2

Pull or build Docker images

docker pull alvarosp24/ambiotec-backend:latest
docker pull alvarosp24/gpt4-ambiotec-bot:latest
3

Deploy with Docker Compose

docker-compose -f docker-compose.prod.yml up -d
Production configuration uses image tags controlled by environment variables:
  • BACKEND_TAG (default: latest)
  • BOT_TAG (default: latest)
4

Verify deployment

# Check service status
docker-compose -f docker-compose.prod.yml ps

# View logs
docker-compose -f docker-compose.prod.yml logs -f

# Test backend API
curl http://localhost:3000/health

​
Service Configuration

​
Redis

redis:
  image: redis:7-alpine
  container_name: ambiotec-redis
  ports:
    - "6379:6379"
  volumes:
    - redis_data:/data
  restart: unless-stopped
Key Features:
  • Persistent storage with named volume
  • Alpine-based for minimal footprint
  • Automatic restart policy

​
Backend API

backend:
  build: ./Backend/web-ambiotec
  container_name: ambiotec-backend
  ports:
    - "3000:3000"
  env_file:
    - ./Backend/web-ambiotec/.env
  depends_on:
    - redis
  volumes:
    - ./Backend/web-ambiotec:/usr/src/app
    - backend_node_modules:/usr/src/app/node_modules
  restart: always
Key Features:
  • Hot-reload with nodemon (development)
  • Isolated node_modules volume
  • Depends on Redis for session storage

​
GPT Bot Service

gpt4-ambiotec-bot:
  build: ./Backend/gpt4-ambiotec-bot
  container_name: gpt4-ambiotec-bot
  ports:
    - "4500:4500"
  env_file:
    - ./Backend/gpt4-ambiotec-bot/.env
  depends_on:
    - redis
  restart: always
Key Features:
  • OpenAI GPT-4 integration
  • Redis-backed conversation history
  • WhatsApp Business API connectivity

​
Volume Management

​
Persistent Volumes

AmbioSys uses Docker volumes for data persistence: 
volumes:
  redis_data:           # Redis data persistence
  backend_node_modules: # Backend dependencies
  bot_node_modules:     # Bot dependencies
  frontend_node_modules: # Frontend dependencies (dev only)

​
Backup Redis Data

# Create backup
docker exec ambiotec-redis redis-cli SAVE
docker cp ambiotec-redis:/data/dump.rdb ./backup/redis-$(date +%Y%m%d).rdb

# Restore backup
docker cp ./backup/redis-20260303.rdb ambiotec-redis:/data/dump.rdb
docker restart ambiotec-redis

​
Networking

All services communicate through the ambio_net bridge network: 
networks:
  ambio_net:
    driver: bridge
Internal DNS Resolution:
  • Backend can connect to Redis via redis:6379
  • Bot service can call backend via backend:3000
  • Services are isolated from external networks

​
Development Overrides

The docker-compose.override.yml enables hot-reload for local development: 
services:
  backend:
    environment:
      - CHOKIDAR_USEPOLLING=true
    volumes:
      - ./Backend/web-ambiotec/src:/usr/src/app/src
      - ./Backend/web-ambiotec/.env:/usr/src/app/.env
CHOKIDAR_USEPOLLING=true ensures file watching works correctly in Docker on all platforms.

​
Useful Commands

​
Service Management

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

# Last 100 lines
docker-compose logs --tail=100 backend

​
Inspect and Debug

# View service details
docker-compose ps

# Check resource usage
docker stats

# Inspect network
docker network inspect source_ambio_net

# View service environment
docker-compose config

​
Building and Publishing Images

​
Build Production Images

# Backend
docker build -f Backend/web-ambiotec/Dockerfile \
  -t alvarosp24/ambiotec-backend:prod \
  Backend/web-ambiotec

# GPT Bot
docker build -f Backend/gpt4-ambiotec-bot/Dockerfile \
  -t alvarosp24/gpt4-ambiotec-bot:prod \
  Backend/gpt4-ambiotec-bot

​
Tag and Push to Docker Hub

# Tag images
docker tag alvarosp24/ambiotec-backend:prod alvarosp24/ambiotec-backend:latest
docker tag alvarosp24/gpt4-ambiotec-bot:prod alvarosp24/gpt4-ambiotec-bot:latest

# Login to Docker Hub
docker login

# Push images
docker push alvarosp24/ambiotec-backend:prod
docker push alvarosp24/ambiotec-backend:latest
docker push alvarosp24/gpt4-ambiotec-bot:prod
docker push alvarosp24/gpt4-ambiotec-bot:latest

​
Troubleshooting

​
Service won’t start

Symptom: Container exits immediately after starting 
# Check logs for errors
docker-compose logs backend

# Verify environment variables
docker-compose exec backend env | grep PG_

# Test database connectivity
docker-compose exec backend node -e "console.log(process.env.PG_HOST)"

​
Port already in use

Symptom: Error: bind: address already in use 
# Find process using port
lsof -i :3000

# Kill process or change port in docker-compose.yml
ports:
  - "3001:3000"  # Map to different host port

​
Hot-reload not working

Symptom: Code changes don’t trigger restart
1

Ensure docker-compose.override.yml is present

The override file should mount source directories.
2

Verify CHOKIDAR_USEPOLLING is set

docker-compose exec backend env | grep CHOKIDAR
3

Check nodemon configuration

Verify nodemon.json exists in the backend directory.

​
Redis connection issues

Symptom: Error: Redis connection refused 
# Verify Redis is running
docker-compose ps redis

# Test Redis connectivity
docker-compose exec redis redis-cli ping
# Expected: PONG

# Check backend can reach Redis
docker-compose exec backend ping redis

# Verify REDIS_HOST environment variable
docker-compose exec backend env | grep REDIS_HOST
# Should be: redis (not localhost)

​
Out of disk space

Symptom: Build fails or containers won’t start 
# Remove unused Docker resources
docker system prune -a

# Remove old volumes
docker volume prune

# Check disk usage
docker system df

​
Container memory issues

# Check memory usage
docker stats --no-stream

# Increase Docker memory limit (Docker Desktop)
# Settings > Resources > Memory > 4GB or higher

# Add memory limit to service (optional)
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G

​
Next Steps

Environment Variables

Configure required environment variables for all services

Database Setup

Initialize PostgreSQL database with schemas and seed data

Build docs developers (and LLMs) love

Get started for freeTalk to us