Instalación y Despliegue

1. Requisitos previos

Software necesario

Docker 20.10+ y Docker Compose v2+
Git para clonar repositorios
Opcionalmente: Docker Swarm para producción

Recursos mínimos

Componente	Desarrollo	Producción
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disco	20 GB	50+ GB

2. Arquitectura del sistema

OpenJornada está compuesto por los siguientes servicios:

API (FastAPI)

Backend REST API con Python

ghcr.io/openjornada/openjornada-api

Admin (Next.js)

Panel de administración

ghcr.io/openjornada/openjornada-admin

Webapp (React + Vite)

Aplicación para trabajadores

ghcr.io/openjornada/openjornada-trabajadores

MongoDB

Base de datos

mongo:7-jammy

┌─────────────────────────────────────────────────┐
│                   INTERNET                      │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│              Caddy (Reverse Proxy)              │
│         SSL automático + Load Balancing         │
└─────────────────────────────────────────────────┘
        │               │               │
        ▼               ▼               ▼
┌───────────┐   ┌───────────┐   ┌───────────┐
│   Admin   │   │  Webapp   │   │    API    │
│  :3000    │   │   :80     │   │   :8000   │
└───────────┘   └───────────┘   └───────────┘
                                        │
                                        ▼
                              ┌───────────────┐
                              │    MongoDB    │
                              │    :27017     │
                              └───────────────┘

3. Docker Compose (desarrollo)

Inicio rápido

# Clonar repositorio
git clone https://github.com/openjornada/openjornada-api.git
cd openjornada-api

# Configurar variables
cp .env.example .env
# Editar .env con tu configuración

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

docker-compose.yml básico

version: '3.8'

services:
  mongodb:
    image: mongo:7-jammy
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: changeme123
    volumes:
      - mongodb_data:/data/db
    ports:
      - "27017:27017"

  api:
    image: ghcr.io/openjornada/openjornada-api:latest
    environment:
      - MONGODB_URL=mongodb://admin:changeme123@mongodb:27017
      - SECRET_KEY=your-secret-key-here
    ports:
      - "8000:8000"
    depends_on:
      - mongodb

  admin:
    image: ghcr.io/openjornada/openjornada-admin:latest
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:8000
    ports:
      - "3001:3000"

  webapp:
    image: ghcr.io/openjornada/openjornada-trabajadores:latest
    environment:
      - VITE_API_URL=http://localhost:8000
      - VITE_API_USERNAME=admin
      - VITE_API_PASSWORD=your-password
    ports:
      - "5173:80"

volumes:
  mongodb_data:

4. Docker Swarm (producción)

Inicializar Swarm

# Inicializar Swarm (solo primera vez)
docker swarm init

# Crear red overlay
docker network create --driver overlay --attachable frontend

# Desplegar stack
docker stack deploy -c docker-compose.swarm.yml openjornada

# Ver servicios
docker stack services openjornada

# Ver logs de un servicio
docker service logs openjornada_api -f

Actualizar servicios

# Actualizar imagen de un servicio
docker service update --image ghcr.io/openjornada/openjornada-api:1.0.5 openjornada_api

# Forzar actualización
docker service update --force openjornada_api

# Rollback si hay problemas
docker service rollback openjornada_api

Alta disponibilidad

Para alta disponibilidad, usa múltiples réplicas de los servicios web. MongoDB requiere configuración de replica set para HA.

5. Variables de entorno

API (openjornada-api)

Variable	Descripción	Ejemplo
MONGODB_URL	URL de conexión MongoDB	mongodb://user:pass@host:27017
SECRET_KEY	Clave para JWT (mín 32 chars)	your-secret-key-min-32-characters
SMTP_HOST	Servidor SMTP	smtp.gmail.com
SMTP_PORT	Puerto SMTP	587
SMTP_USER	Usuario SMTP	noreply@empresa.com
SMTP_PASSWORD	Contraseña SMTP	app-password

Admin Panel

Variable	Descripción
NEXT_PUBLIC_API_URL	URL de la API
NEXT_PUBLIC_APP_NAME	Nombre de la aplicación
NEXT_PUBLIC_APP_LOGO	Ruta del logo

Webapp (Trabajadores)

Variable	Descripción
VITE_API_URL	URL de la API
VITE_API_USERNAME	Usuario API para auth JWT
VITE_API_PASSWORD	Contraseña API para auth JWT
VITE_APP_NAME	Nombre de la app

6. Configuración SSL

Usamos Caddy como reverse proxy. Obtiene certificados SSL automáticamente de Let's Encrypt.

Caddyfile de ejemplo

# Dominio principal
app.tuempresa.com {
    # Admin panel
    handle /admin* {
        reverse_proxy admin:3000
    }

    # API
    handle /api* {
        reverse_proxy api:8000
    }

    # Webapp (default)
    handle {
        reverse_proxy webapp:80
    }
}

# Redirect www a non-www
www.tuempresa.com {
    redir https://app.tuempresa.com{uri} permanent
}

SSL Automático

Caddy obtiene y renueva certificados SSL automáticamente. Solo asegúrate de que tu dominio apunte a la IP del servidor.

7. MongoDB

Configuración recomendada

# docker-compose.yml
mongodb:
  image: mongo:7-jammy
  environment:
    MONGO_INITDB_ROOT_USERNAME: admin
    MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
    MONGO_INITDB_DATABASE: openjornada
  volumes:
    - mongodb_data:/data/db
    - mongodb_config:/data/configdb
  deploy:
    placement:
      constraints:
        - node.role == manager

Conexión desde CLI

# Conectar a MongoDB
docker exec -it openjornada_mongodb mongosh

# Autenticar
use admin
db.auth("admin", "password")

# Ver bases de datos
show dbs

# Usar base de datos
use openjornada

# Ver colecciones
show collections

8. Crear primer usuario

Después de desplegar, crea el primer usuario administrador usando el CLI de la API.

Crear usuario admin

# Acceder al contenedor de la API
docker exec -it openjornada_api bash

# Crear usuario administrador
python -m api.manage_api_users create admin admin@empresa.com admin

# Se te pedirá una contraseña

# Verificar que se creó
python -m api.manage_api_users list

Otros comandos útiles

# Ver usuarios
python -m api.manage_api_users list

# Cambiar contraseña
python -m api.manage_api_users password admin

# Cambiar rol
python -m api.manage_api_users role admin tracker

# Activar/desactivar usuario
python -m api.manage_api_users toggle admin

Siguiente paso

Una vez creado el usuario admin, accede al panel de administración y crea tu primera empresa y trabajadores.