MonsterOps logo MonsterOps
Docs / Getting Started / Installation

Installation

There are four ways to install MonsterOps. Production hosts should use the installer; the PyPI install is the quickest way to try it.

Run the installer as root on a fresh Ubuntu or Debian host:

git clone https://github.com/NLRI65000/MonsterOps.git
cd MonsterOps
sudo bash deploy/install.sh

The installer will:

  1. Install system packages (python3, python3-pip, python3-venv, acl, postgresql, FreeRADIUS/VPN tools)
  2. Create a dedicated monsterops system user
  3. Create and initialise the PostgreSQL database
  4. Set up a virtual environment in /opt/monsterops/.venv
  5. Install the monsterops package
  6. Generate /opt/monsterops/.env with a random SECRET_KEY
  7. Run the database migrations
  8. Provision the sudoers allow-list and VPN tooling
  9. Write and enable a monsterops.service systemd unit

After it finishes, the service is running on port 8000. Override defaults with environment variables:

MONSTEROPS_PORT=9000 INSTALL_DIR=/srv/monsterops sudo bash deploy/install.sh

From PyPI

The fastest path — the database migrations ship inside the package, so no source checkout is needed:

pip install monsterops
export MONSTEROPS_DATABASE_URL=postgresql+asyncpg://user:pass@localhost/radius
export MONSTEROPS_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

monsterops migrate          # create / upgrade the schema
monsterops serve --host 0.0.0.0 --port 8000

From source

git clone https://github.com/NLRI65000/MonsterOps.git
cd MonsterOps

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

cp .env.example .env
# edit .env — set MONSTEROPS_DATABASE_URL and MONSTEROPS_SECRET_KEY

monsterops migrate          # or, from a checkout: alembic upgrade head
monsterops serve --host 0.0.0.0 --port 8000

Docker Compose

cp .env.example .env
# edit .env as needed
docker compose up -d

The compose file starts PostgreSQL and the MonsterOps app. It does not start FreeRADIUS — point FreeRADIUS at the same database from the host.

Problems you may hit

connection refused / database errors on first run

MONSTEROPS_DATABASE_URL must use the async driver: postgresql+asyncpg://…, not postgresql://…. Confirm PostgreSQL is reachable and the database exists before monsterops migrate.

The app warns about the secret key

If MONSTEROPS_SECRET_KEY is still the default, the app warns on every start. Set a strong, random value before exposing it to a network — it signs sessions and encrypts stored credentials. See Configuration.

  • monsterops: command not found — activate the virtual environment, or use the full path to the venv's bin/monsterops.
  • Migrations "can't find alembic.ini" — on a pip install use monsterops migrate (the ini is bundled); alembic upgrade head only works from a source checkout.

Next: First-time Setup.