Skip to main content

Install from source

Use this when you do not want Docker. You end up with the same result as the Docker quick start: one process serving the web interface and the API on port 8091.

Pre-alpha

The source code is not publicly available yet. During pre-alpha, you need access to the repository to follow this guide. The public release is planned for Q1 2027.

Debian and Raspberry Pi OS​

On 64-bit Debian, Ubuntu, or Raspberry Pi OS, the installer sets up the server as a systemd service. It brings its own Python, so you can skip the rest of this page. Download the bundle for your machine (amd64 or arm64) from the repository's server-latest release, then:

tar -xzf minipam-server-linux-arm64.tar.gz
sudo sh minipam-server/install.sh

It prints the address and a one-time bootstrap token for creating the first admin. The configuration is in /etc/minipam/server.yml, and sudo minipam-cli runs the command-line tools. Run the installer of a newer bundle to update. sudo sh minipam-server/install.sh --uninstall removes the server and keeps your data; add --purge to delete the data too.

What you need​

  • Python 3.14
  • Node.js 22.12 or newer, with npm (only to build the web interface)
  • Go, only if you also want to build an agent

1. Install the server​

From the repository root:

python3.14 -m venv .venv
.venv/bin/pip install .

2. Build the web interface​

cd app-ui
npm ci
VITE_API_BASE_URL=/ npm run build
cd ..

This writes the interface to app-ui/dist. VITE_API_BASE_URL=/ tells the interface to call the API on the same address it was loaded from. Without it, a build served by MiniPAM calls port 8000 and every request fails.

3. Create the configuration file​

The server reads its settings from one file. The checked-in app-server/config.yml is set up for development, so create your own app-server/config.local.yml. Git ignores this file, so your bootstrap token stays out of commits:

app-server/config.local.yml
server:
  database:
    location: bin/data/database.db # relative to this file
  services:
    web-api:
      listen:
        http: 0.0.0.0:8091
      frontend-directory: ../app-ui/dist # relative to this file
      authentication:
        bootstrap-token: "paste-the-generated-token-here"

Generate the bootstrap token with openssl rand -hex 32. It is the single-use secret for creating the first admin from the browser.

Keys you leave out take their defaults. The full example lists every key with comments.

4. Start the server​

cd app-server
../.venv/bin/python cli.py run --config config.local.yml

The database is created on first start, and later versions migrate it automatically. Open http://localhost:8091 and continue with Create the first admin.

To keep it running, start the same command from a systemd unit or another process supervisor. Run it from the app-server directory.

Last updated on