Skip to main content

Installation — overview

Liberty Framework ships as a small FastAPI process serving a React SPA on one HTTP port. There's nothing exotic to install — Python 3.12, a database for the framework's own metadata, and (optionally) a reverse proxy in front. You can run it from source on a Linux host or as a Docker Compose stack.

This section walks both paths plus the optional pieces most production installs add.

The two paths​

PathWhen to pickReads
Python source installDev shell. Single Linux server. You're comfortable with systemd and want minimal moving parts.Python server.
Docker ComposeMulti-service stack, easier onboarding for ops. Reproducible across envs (dev / staging / prod).Docker.

Both paths give the same runtime — same UI, same REST API, same Nomaflow scheduler. The choice is operational.

If your team already runs containers, Docker is the path of least friction. If you're starting fresh on a fresh Linux box and prefer plain processes, Python source + systemd works fine and adds no Docker layer to debug.

What you always need​

Regardless of the path:

ComponentWhy
Python 3.12 (Python source path only — Docker bakes it in)The framework runtime.
Node.js ≥ 20 + npm (Python source path only — Docker bakes it in)Build the React frontend bundle.
A databaseThe framework's own pool — auth, jobs, locks, run history. PostgreSQL is the default; SQLite works for dev. Oracle is supported when a customer ERP requires it.
The liberty-apps repoYour configuration: connectors.toml, dictionary.toml, screens.toml, menus.toml, dashboards.toml, charts.toml, jobs.toml, plus any Python plugins under plugins/.
An HTTP portOne. The framework serves the API and the SPA on the same port.

What you optionally add​

ComponentWhy
Reverse proxy (Traefik / nginx / Caddy)Terminate TLS, hide the framework behind a friendly hostname, route multiple apps on the same host. See Traefik for the canonical Docker setup.
PortainerVisual management for the Docker stack — see status, logs, restart services without typing docker compose commands. See Portainer.
A multi-replica deploymentWhen one replica isn't enough for the load. Pin the scheduler to one replica per the Nomaflow rules. See Production.
External monitoring (Prometheus / Grafana / OpenTelemetry)When the built-in Monitoring page isn't enough.

At a glance​

Liberty install — two paths, same runtimePATH 1 · PYTHON SOURCEgit clone liberty-next + liberty-appspython -m venv .venv && pip install -e .cd frontend && npm install && npm run buildliberty-admin init-dbuvicorn liberty.main:app --port 8000Wrap with a systemd unit for prod.→ Python server→ Production hardeningPATH 2 · DOCKER COMPOSEgit clone liberty-appscurl -O docker-compose.yml + .envdocker compose up -ddocker compose exec liberty liberty-admin init-dbAdds Postgres, Liberty, Traefik in one stack.→ Docker · Portainer · Traefik

Read in order​

StepPage
0This overview.
1Pick a path: Python server or Docker.
2(Optional) Add a reverse proxy and TLS: Traefik.
3(Optional) Add a visual Docker manager: Portainer.
4Production hardening (multi-replica, logs, backup): Production.
5When a new version ships: Upgrading.

Sanity check — what "installed" looks like​

After either path:

  • curl http://<host>:8000/health returns {"status":"ok"}.
  • The login page renders at http://<host>:8000/.
  • The framework log shows liberty.plugins importable from <path> (your plugins/ dir was found).
  • The admin user you bootstrapped with liberty-admin init-db can sign in.

If any of those don't hold, jump to the path's troubleshooting section.

What's next​