Skip to main content
Modulo

Installation

The supported way to run Modulo is Docker Compose, on Docker Desktop or a Docker Engine on Linux. On Linux, a native install is also supported. See Platform support for the full matrix.

Platform support

Modulo v1 targets Linux server hosts. This is the supported platform matrix, mirroring the product’s system requirements. For the quick answer, see What infrastructure does Modulo need?.

Server host platforms

Server host platforms
Server host platform v1 status
Linux Supported (native install and container paths)
macOS Not a supported v1 server host: no native installer, no macOS release artifact
Windows Not a supported v1 server host: no native installer, no Windows release artifact

Docker Desktop on macOS or Windows is a developer convenience: it runs the Linux containers inside a Linux virtual machine, so the deployed stack is still Linux. It is not a supported production host.

Docker Compose

The Docker Compose path is distribution-agnostic, apart from its Docker requirement: any Linux distribution that can run Docker 24+ (Docker Engine or Docker Desktop) and Docker Compose v2.20+ works, at any glibc version, because the PostgreSQL, Redis, API, frontend, and worker containers carry their own dependencies.

Native install: distributions

The native install is Linux-only. The bundle ships its own PostgreSQL 16, Redis 8, and Python runtime, so the host requirement is the bundled service binaries’ glibc floor:

Native install: distributions
Distribution glibc Status
Debian 13+ 2.41 Supported
Ubuntu 26.04+ 2.41+ Supported
Ubuntu 24.04 and earlier 2.39 and below Not supported (below the bundled service-binary floor)
macOS - Out of scope for v1
Windows - Out of scope for v1

The hard requirement is glibc 2.41 or newer. An Ubuntu 24.04 host (glibc 2.39) is below the floor and is not a supported native-install target.

Native install: architectures

Native install: architectures
Architecture Status
linux-amd64 (x86_64) Supported
linux-arm64 Planned (pins exist; no artifact published yet)
macOS / Windows Out of scope for v1

The native bundle is currently built and published for linux-amd64 only. There is no linux-arm64 download yet.

Prerequisites

  • Docker 24+ (Engine or Desktop) and Docker Compose v2.20+
  • 4 GB RAM minimum (8 GB recommended)

Quick start

The default docker-compose.yml starts everything in one command: Postgres 16, Redis 8, the API, the frontend, and the queue workers. The first run builds the Docker images, which takes several minutes; subsequent starts are fast.

git clone https://github.com/farnalabs/modulo
cd modulo
docker compose up -d

Open http://localhost:5173 and log in with admin:admin. These are development credentials: change them before exposing the instance beyond local use. The backend runs database migrations automatically on first start.

Development setup

For local development with hot-reload, use the development Compose file and start the API and frontend separately:

Development prerequisites

  • Python 3.12+ and uv (or pip)
  • A GitHub account (for GitHub connector setup)

Steps

Start the database and queue services first:

git clone https://github.com/farnalabs/modulo
cd modulo

# Start Postgres 16, Redis 8, and the queue workers
docker compose -f docker-compose.local.yml up -d

Generate the two secret keys. SECRET_KEY must be at least 32 bytes (known placeholder values are rejected at startup), and FERNET_KEY must be a valid Fernet key, so do not invent values by hand:

python -c "import secrets; print(secrets.token_hex(32))"    # SECRET_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"  # FERNET_KEY

Create a .env file in the backend/ directory and paste the generated outputs:

DATABASE_URL=postgresql+asyncpg://modulo:changeme@localhost:5434/modulo
# The development Compose file publishes Redis on port 6380
REDIS_URL=redis://localhost:6380/0
# Paste the SECRET_KEY output from the generator above
SECRET_KEY=paste-generated-key-here
# Paste the FERNET_KEY output from the generator above
FERNET_KEY=paste-generated-key-here
# Local development login only. Use a strong password outside local development.
MODULO_USERS=admin:admin
# CORS (Cross-Origin Resource Sharing): comma-separated allowed origins
CORS_ORIGINS=http://localhost:5173

Run migrations and start the API:

cd backend
uv run alembic upgrade heads
uv run uvicorn modulo.api.main:app --reload --port 8000

In another terminal, start the frontend:

cd frontend
npm run dev

Open http://localhost:5173 and log in with admin:admin.

Native install (Linux)

On Linux, Modulo can also be installed natively, without Docker:

curl -fsSL https://raw.githubusercontent.com/farnalabs/modulo/main/scripts/install.sh -o modulo-install.sh
bash modulo-install.sh

Download the script to a file and run it rather than piping it straight into a shell. The installer verifies every download’s sha256 before executing anything, and a streamed install skips that verification.

The installer:

  • Downloads the release bundle for your architecture from GitHub Releases and verifies it
  • Installs a bundled stack: PostgreSQL 16, Redis 8, and a bundled Python runtime (no Docker or system Python needed)
  • Installs everything under your home directory and puts modulo on your PATH

modulo start runs everything: PostgreSQL, Redis, the API, and the queue workers. On systemd hosts, an optional systemd user unit manages it.

Which install to pick:

Native install (Linux)
Install Use for
Docker Compose Servers and production deployments
Native install Workstations and evaluation
Kubernetes (Helm) Teams running Modulo on a cluster they control

To run the whole stack on a Kubernetes cluster, use the Helm chart: see the Kubernetes guide for prerequisites, the values to set, and notes for Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), and any other conformant cluster.

The full native install, upgrade, and backup/restore documentation lives in the deployment docs.

Next: Architecture