Install OpenJornada - Docker, Kubernetes & Self-Hosted

1. Prerequisites

Required software

Docker 20.10+ y Docker Compose v2+
Git para clonar repositorios
Opcionalmente: Docker Swarm para produccion

Minimum resources

Component	Development	Production
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disco	20 GB	50+ GB

2. System architecture

OpenJornada is composed of the following services:

API (FastAPI)

Backend REST API with Python

ghcr.io/openjornada/openjornada-api

Admin (Next.js)

Administration panel

ghcr.io/openjornada/openjornada-admin

Webapp (React + Vite)

Employee application

ghcr.io/openjornada/openjornada-trabajadores

MongoDB

Database

mongo:7-jammy

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

3. Docker Compose (development)

Quick start

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

# Configurar variables
cp .env.example .env
# Editar .env con tu configuracion

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

Basic docker-compose.yml

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 (production)

Initialize 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

Update services

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

# Forzar actualizacion
docker service update --force openjornada_api

# Rollback si hay problemas
docker service rollback openjornada_api

Alta disponibilidad

For high availability, use multiple replicas of web services. MongoDB requires a replica set configuration for HA.

5. Environment variables

API (openjornada-api)

Variable	Description	Example
MONGODB_URL	URL de conexion MongoDB	mongodb://user:pass@host:27017
SECRET_KEY	Clave para JWT (min 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	Contrasena SMTP	app-password

Admin Panel

Variable	Description
NEXT_PUBLIC_API_URL	URL de la API
NEXT_PUBLIC_APP_NAME	Nombre de la aplicacion
NEXT_PUBLIC_APP_LOGO	Ruta del logo

Webapp (Employees)

Variable	Description
VITE_API_URL	URL de la API
VITE_API_USERNAME	Usuario API para auth JWT
VITE_API_PASSWORD	Contrasena API para auth JWT
VITE_APP_NAME	Nombre de la app

6. SSL configuration

We use Caddy as a reverse proxy. It automatically obtains SSL certificates from Let's Encrypt.

Example Caddyfile

# 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 Automatico

Caddy automatically obtains and renews SSL certificates. Just make sure your domain points to the server's IP.

7. MongoDB

Recommended configuration

# 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

CLI connection

# 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. Create first user

After deployment, create the first administrator user using the API CLI.

Create admin user

# 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 pedira una contrasena

# Verificar que se creo
python -m api.manage_api_users list

Other useful commands

# Ver usuarios
python -m api.manage_api_users list

# Cambiar contrasena
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

Once the admin user is created, access the administration panel and create your first company and employees.

Installation & Deployment

Contents