Bitflake logo

Self-host OpenJornada with Docker Compose

Employee clock-in and time records for Spanish and EU labour compliance.

openjornada

admin

ghcr.io/openjornada/openjornada-admin:latest

api

ghcr.io/openjornada/openjornada-api:latest

mongodb

mongo:8

mongodb-mongodb-data-init

busybox

mongodb-mongodb-tmp-init

busybox

The steps below take a few minutes end to end.

  1. Docker compose setup and file
    save the generated compose and env files.
  2. Secret generation
    create the random passwords OpenJornada needs.
  3. Start OpenJornada with Docker Compose
    bring the stack up and check it's healthy.

Requirements

You'll need these installed on the machine you're deploying to:

Docker

Packages OpenJornada and everything it depends on into an isolated container, so it runs the same way on your machine as it does everywhere else.

Install guide

Docker Compose

Reads docker-compose.ymland starts everything in it together. Ships with Docker Desktop. On Linux servers it's usually a separate install.

Install guide

1. Docker compose setup and file

Create a folder for OpenJornada and save the file below into it as docker-compose.yml. It describes every container the stack needs — OpenJornadaitself and any supporting services, such as its database — along with the ports, volumes and environment variables each one uses. You'll also need an empty .env file in the same folder; Docker Compose reads it automatically and uses it to fill in the ${VARIABLE}references you'll see in the file below.

docker-compose.yml

version: "3.9"
services:
  admin:
    image: ghcr.io/openjornada/openjornada-admin:latest
    restart: unless-stopped
    network_mode: service:openjornada
    environment:
      NEXT_PUBLIC_API_URL: http://openjornada.localhost:8080
      NEXT_PUBLIC_APP_NAME: OpenJornada
    volumes:
      - admin-next:/app/.next
      - admin-tmp:/tmp
  api:
    image: ghcr.io/openjornada/openjornada-api:latest
    restart: unless-stopped
    network_mode: service:openjornada
    environment:
      ACCESS_TOKEN_EXPIRE_MINUTES: "480"
      ALGORITHM: HS256
      API_HOST: 0.0.0.0
      API_PORT: "8000"
      DB_NAME: time_tracking_db
      DEBUG: "False"
      HOME: /tmp
      MONGO_URL: mongodb://127.0.0.1:27017/?directConnection=true
      PYTHONDONTWRITEBYTECODE: "1"
      SECRET_KEY: ${RANDOM_SECRET_KEY}
    volumes:
      - api-tmp:/tmp
      - api-backups:/app/backups
    entrypoint:
      - sh
      - -c
    command:
      - |
        for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
          python -m api.manage_api_users create admin admin@bitflake.com admin --password 'Admin123'
          python -m api.manage_api_users show admin 2>/dev/null | grep -q 'Username: admin' && break
          sleep 3
        done
        python -m api.manage_api_users create bitflake-webapp webapp@bitflake.com tracker --password 'BitflakeWebapp123'
        exec uvicorn api.main:app --host 0.0.0.0 --port 8000
  mongodb:
    image: mongo:8
    restart: unless-stopped
    volumes:
      - mongodb-data:/data/db
      - mongodb-tmp:/tmp
    depends_on:
      mongodb-mongodb-data-init:
        condition: service_completed_successfully
      mongodb-mongodb-tmp-init:
        condition: service_completed_successfully
    entrypoint:
      - sh
      - -c
    command:
      - mongod --replSet rs0 --bind_ip_all & MONGO_PID=$$! ; until mongosh --quiet --eval 'db.runCommand({ping:1})' >/dev/null 2>&1; do sleep 1; done ; mongosh --eval "try { rs.status() } catch(e) { rs.initiate({_id:'rs0',members:[{_id:0,host:'localhost:27017'}]}) }" >/dev/null 2>&1 || true ; wait $$MONGO_PID
  mongodb-mongodb-data-init:
    image: busybox
    volumes:
      - mongodb-data:/data/db
    command:
      - chown
      - 999:999
      - /data/db
  mongodb-mongodb-tmp-init:
    image: busybox
    volumes:
      - mongodb-tmp:/tmp
    command:
      - chown
      - 999:999
      - /tmp
  openjornada:
    image: ghcr.io/openjornada/openjornada-trabajadores:latest
    restart: unless-stopped
    ports:
      - 8080:8080
    environment:
      VITE_API_PASSWORD: BitflakeWebapp123
      VITE_API_URL: http://openjornada.localhost:8080
      VITE_API_USERNAME: bitflake-webapp
      VITE_APP_NAME: OpenJornada
    volumes:
      - webroot:/usr/share/nginx/html
      - tmp:/tmp
    configs:
      - source: openjornada-nginx-conf
        target: /etc/nginx/nginx.conf
volumes:
  admin-next: null
  admin-tmp: null
  api-backups: null
  api-tmp: null
  mongodb-data: null
  mongodb-tmp: null
  tmp: null
  webroot: null
configs:
  openjornada-nginx-conf:
    content: |
      worker_processes auto;
      error_log /dev/stderr warn;
      pid /tmp/nginx.pid;

      events {
        worker_connections 1024;
      }

      http {
        include /etc/nginx/mime.types;
        default_type application/octet-stream;
        access_log /dev/stdout;

        client_body_temp_path /tmp/client_temp;
        proxy_temp_path /tmp/proxy_temp;
        fastcgi_temp_path /tmp/fastcgi_temp;
        uwsgi_temp_path /tmp/uwsgi_temp;
        scgi_temp_path /tmp/scgi_temp;

        sendfile on;
        keepalive_timeout 65;
        gzip on;
        gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

        server {
          listen 8080;
          server_name _;
          root /usr/share/nginx/html;
          index index.html;

          # Emit relative Location headers. Behind a TLS-terminating proxy
          # nginx sees plain HTTP on 8080, so an absolute redirect would send
          # the browser to http://<host>:8080/, leaking the internal port and
          # downgrading the scheme.
          absolute_redirect off;

          # The published image is built with Vite's base and the React Router
          # basename both fixed to /trabajadores, and neither can be changed
          # without rebuilding. Upstream expects the proxy in front to strip
          # that prefix, so this strips it the same way and sends the bare root
          # there. Serving the app at / instead would load index.html but leave
          # the router matching nothing, i.e. a blank page.
          location = / {
            return 302 /trabajadores/;
          }

          location /trabajadores/ {
            rewrite ^/trabajadores/(.*)$$ /$$1 break;
            try_files $$uri $$uri/ /index.html;
          }

          # The admin panel and the API are separate containers in this same
          # pod, so they share its network namespace and answer on localhost.
          # Serving all three under one hostname mirrors the layout upstream
          # documents for its own Caddy proxy, and keeps the browser's API
          # calls same-origin. The admin image bakes /admin as its base path,
          # so its prefix is passed through rather than stripped.
          location /admin {
            proxy_pass http://127.0.0.1:3001;
            proxy_set_header Host $$host;
            proxy_set_header X-Forwarded-Proto https;
            proxy_set_header X-Forwarded-For $$proxy_add_x_forwarded_for;
          }

          location /api/ {
            proxy_pass http://127.0.0.1:8000;
            proxy_set_header Host $$host;
            proxy_set_header X-Forwarded-Proto https;
            proxy_set_header X-Forwarded-For $$proxy_add_x_forwarded_for;
          }
        }
      }

Volumes

OpenJornada stores its data in named Docker volumes, so it survives container restarts and updates:

  • webroot mounted at /usr/share/nginx/html: The employee clock-in app's own files. The app rewrites the API address into them each time it starts.
  • tmp mounted at /tmp: Scratch space the web server uses while serving requests.

2. Secret generation

OpenJornada needs a few randomly generated secrets — for example, database passwords or an internal session key — before it can start. These are referenced from docker-compose.ymlabove but don't live in it, so they need to end up in your .env file. Pick one of the two options below.

Generating secrets…

3. Start OpenJornada with Docker Compose

From the folder with docker-compose.yml and .env, run:

Terminal

Start OpenJornada and all its supporting services in the background.

docker compose up -d

The -d flag runs the stack in the background so it keeps running after you close the terminal. Docker will pull the images the first time, which can take a minute or two.

To check on it afterwards: docker compose ps shows whether containers are healthy, and docker compose logs -f follows their logs if something looks wrong. Once it's running, open http://localhost:8080 in your browser.