Docker Setup

Overview

Documentación de la configuración Docker y Docker Compose para el ecosistema Nostromo.

---

Docker Compose Structure

File: docker-compose.yml (ubicado en /opt/nostromo/)

version: "3.8"

services:
  mother:
    image: postgres:16-alpine
    container_name: nostromo_mother
    environment:
      POSTGRES_DB: nostromo
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init-scripts:/docker-entrypoint-initdb.d
    ports:
      - "5432:5432"
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  orchestrator:
    build:
      context: ./orchestrator
      dockerfile: Dockerfile
    container_name: nostromo_orchestrator
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@mother:5432/nostromo
      JWT_SECRET: ${JWT_SECRET}
    depends_on:
      mother:
        condition: service_healthy
    ports:
      - "8000:8000"
    restart: unless-stopped
    volumes:
      - ./orchestrator/logs:/app/logs

  etl:
    build:
      context: ./etl
      dockerfile: Dockerfile
    container_name: nostromo_etl
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@mother:5432/nostromo
    depends_on:
      - mother
    restart: unless-stopped
    volumes:
      - ./etl/data:/app/data
      - ./etl/logs:/app/logs

volumes:
  postgres_data:
    driver: local

networks:
  default:
    name: nostromo_network

---

Container Details

Mother (PostgreSQL)

Image: postgres:16-alpine

Exposed Port: 5432

Volumes:

• postgres_data:/var/lib/postgresql/data - Persistent data
• ./init-scripts:/docker-entrypoint-initdb.d - Init SQL scripts

Environment Variables:

POSTGRES_DB=nostromo
POSTGRES_USER=<SECRET>
POSTGRES_PASSWORD=<SECRET>

Health Check:

pg_isready -U postgres

---

Orchestrator

Build Context: ./orchestrator/

Dockerfile:

FROM node:20-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source
COPY . .

# Build TypeScript
RUN npm run build

# Expose port
EXPOSE 8000

# Start server
CMD ["node", "dist/server.js"]

Exposed Port: 8000

Environment Variables:

NODE_ENV=production
DATABASE_URL=postgresql://user:pass@mother:5432/nostromo
JWT_SECRET=<SECRET>
JWT_EXPIRATION=24h
PORT=8000

---

ETL Service

Build Context: ./etl/

Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Copy source
COPY . .

# Run cron jobs (if applicable)
CMD ["python", "-m", "etl.scheduler"]

Environment Variables:

DATABASE_URL=postgresql://user:pass@mother:5432/nostromo
SII_SCRAPE_DELAY=2
LOG_LEVEL=INFO

---

Docker Networks

Network Name: nostromo_network

Type: Bridge (default)

Inter-container Communication:

• Orchestrator → Mother via hostname mother:5432
• ETL → Mother via hostname mother:5432
• Containers se resuelven por nombre de servicio

---

Volumes

postgres_data

Type: Named volume (managed by Docker)

Path: /var/lib/docker/volumes/nostromo_postgres_data/_data

Backup:

# Backup volume
docker run --rm -v nostromo_postgres_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres_backup.tar.gz /data

# Restore volume
docker run --rm -v nostromo_postgres_data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/postgres_backup.tar.gz -C /

---

Bind Mounts

Container	Host Path	Container Path	Purpose
Orchestrator	./orchestrator/logs	/app/logs	Application logs
ETL	./etl/logs	/app/logs	ETL logs
ETL	./etl/data	/app/data	Scraped data cache
Mother	./init-scripts	/docker-entrypoint-initdb.d	Init SQL

---

Running Containers

Start All Services

cd /opt/nostromo
docker-compose up -d

Expected output:

Creating nostromo_mother ... done
Creating nostromo_orchestrator ... done
Creating nostromo_etl ... done

---

Stop All Services

docker-compose down

---

View Logs

# All containers
docker-compose logs -f

# Specific container
docker-compose logs -f orchestrator
docker-compose logs -f mother

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

---

Rebuild Container

# Rebuild single service
docker-compose build orchestrator

# Rebuild and restart
docker-compose up -d --build orchestrator

---

Environment Variables

File: .env (located in /opt/nostromo/)

# PostgreSQL
POSTGRES_USER=nostromo_user
POSTGRES_PASSWORD=<STRONG_PASSWORD>

# JWT
JWT_SECRET=<RANDOM_256_BIT_SECRET>
JWT_EXPIRATION=24h

# Node.js
NODE_ENV=production

# ETL
SII_SCRAPE_DELAY=2
LOG_LEVEL=INFO

Danger

NEVER commit .env to Git. Use .env.example as template.

---

Container Health

Health Check Commands

# Mother (PostgreSQL)
docker exec nostromo_mother pg_isready -U nostromo_user

# Orchestrator
docker exec nostromo_orchestrator curl -f http://localhost:8000/health

# View health status
docker-compose ps

Expected output:

Name                    State    Ports
-----------------------------------------------
nostromo_mother         Up (healthy)   0.0.0.0:5432->5432/tcp
nostromo_orchestrator   Up            0.0.0.0:8000->8000/tcp
nostromo_etl            Up

---

Resource Limits

Recommended (añadir a docker-compose.yml):

services:
  mother:
    # ... existing config ...
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 2G
        reservations:
          cpus: "1"
          memory: 1G

  orchestrator:
    deploy:
      resources:
        limits:
          cpus: "1"
          memory: 1G

---

Troubleshooting

Container won’t start

Symptoms: docker-compose ps shows Exited (1).

Debugging:

# View exit logs
docker-compose logs orchestrator

# Inspect container
docker inspect nostromo_orchestrator

# Try interactive shell
docker run --rm -it \
  --entrypoint /bin/sh \
  nostromo_orchestrator

---

Cannot connect to Mother from Orchestrator

Symptoms: Error: connect ECONNREFUSED mother:5432

Checks:

1. Mother container running? docker ps | grep mother
2. Health check passing? docker inspect nostromo_mother | grep Health
3. Network exists? docker network ls | grep nostromo

Fix:

# Restart Mother
docker-compose restart mother

# Verify network
docker network inspect nostromo_network

---

Disk space full

Symptoms: no space left on device

Cleanup:

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove stopped containers
docker container prune

# Nuclear option (removes EVERYTHING unused)
docker system prune -a --volumes

---

Production Best Practices

• ✅ Use specific image tags (NOT latest)
• ✅ Set resource limits (CPU, memory)
• ✅ Use health checks for all services
• ✅ Enable logging drivers (e.g., json-file with rotation)
• ✅ Use secrets management (Docker Swarm secrets or Vault)
• ✅ Regularly update base images (security patches)

---

Monitoring

Docker Stats

# Real-time container metrics
docker stats

# Expected output:
# CONTAINER     CPU %    MEM USAGE / LIMIT     NET I/O
# nostromo_mother        5%      500MB / 2GB       1kB / 2kB
# nostromo_orchestrator  10%     200MB / 1GB       50kB / 100kB

---

Grafana + cAdvisor

Setup (optional):

• cAdvisor: Container metrics exporter
• Prometheus: Scrape cAdvisor metrics
• Grafana: Visualize container health

---

Related Documentation

• Infrastructure: Networking - Network topology
• Infrastructure: PostgreSQL Config - Database tuning
• Runbook: Deploy - Deployment procedures
• ADR-002: Pool Management - Connection pooling

---

Changelog

Fecha	Version	Cambios
2026-01-18	1.0	Documentación inicial creada