Getting Started¶

Install rimae/scan, create an admin account, and verify the deployment. For advanced options, see Installation and Configuration.

System Requirements¶

Supported Operating Systems¶

OS	Version	Status
Ubuntu	22.04 LTS	Supported
Ubuntu	24.04 LTS	Supported
Debian	12 (Bookworm)	Supported
RHEL / AlmaLinux	9.x	Planned

Hardware Minimums¶

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	20 GB	50+ GB (depends on number of sources and assets)

Infrastructure¶

PostgreSQL 16 (installed automatically in appliance mode)
Redis 7 (optional -- falls back to in-memory)
Caddy 2 or Nginx (reverse proxy with TLS)

Installation¶

Quick Install (recommended)¶

curl -fsSL https://pkg.rimae.io/install.sh | sudo bash

The installer offers two modes:

Appliance mode -- installs all Rimae packages + PostgreSQL, Redis, Caddy
Infrastructure mode -- installs only selected Rimae packages (bring your own DB)

Manual APT Setup¶

# Add GPG key and repository
curl -fsSL https://pkg.rimae.io/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/rimae.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rimae.gpg] https://pkg.rimae.io/deb stable main" | \
  sudo tee /etc/apt/sources.list.d/rimae.list

# Appliance (everything)
sudo apt update && sudo apt install rimae-scan

# Or server only
sudo apt update && sudo apt install --no-install-recommends rimae-scan-server

See Installation for the full package list and options.

Post-Install Configuration¶

1. Set up the database¶

If PostgreSQL was installed automatically (appliance mode):

sudo systemctl enable --now postgresql

sudo -u postgres psql <<'SQL'
  CREATE ROLE rimae WITH LOGIN PASSWORD 'CHANGE_ME_TO_STRONG_PASSWORD';
  CREATE DATABASE rimae_scan OWNER rimae;
SQL

2. Edit the configuration¶

sudo nano /etc/rimae-scan/rimae-scan.conf

Four values are required:

Setting	Description
`DATABASE_URL`	`postgres://rimae:<password>@localhost:5432/rimae_scan?sslmode=require`
`SECRET_KEY`	Generate with `openssl rand -base64 32`
`ENCRYPTION_KEY`	Generate with `openssl rand -base64 32`
`DOMAIN`	Your hostname (e.g., `scan.example.com`)

3. Run database migrations¶

sudo rimae-scan-server --migrate --config /etc/rimae-scan/rimae-scan.conf

4. Start the service¶

sudo systemctl enable --now rimae-scan-server
sudo systemctl enable --now rimae-scan-scheduler   # if installed

First-Run Setup Wizard¶

Open your browser and navigate to your domain. On a fresh install, every URL redirects to /setup until the first admin account exists.

https://your-domain/setup

The wizard collects:

Username (e.g., admin)
Email address
Password (minimum 8 characters)
Password confirmation
Click Create Admin Account

You are logged in and redirected to the dashboard automatically.

The setup wizard is only available when no users exist in the database. Once the first admin account is created, /setup returns 409 Conflict and redirects to login.

Verifying the Installation¶

API Health Endpoint¶

curl -s http://localhost:8000/api/health | jq .

A healthy response:

{
    "status": "ok",
    "version": "3.0.0",
    "database": "connected",
    "redis": "connected",
    "uptime_seconds": 42.5
}

Field	Values	Description
`status`	`ok`, `degraded`, `unhealthy`	Overall health. `degraded` if Redis is down, `unhealthy` if database is down
`database`	`connected`, `disconnected`	PostgreSQL connectivity
`redis`	`connected`, `disconnected`	Redis connectivity

Service Status¶

systemctl status rimae-scan-server
journalctl -u rimae-scan-server -f

Next Steps¶

Configuration -- Configure integrations (Wazuh, GitHub), authentication, and scoring
Installation -- Detailed install options, upgrading, uninstalling
Architecture -- System design and data flow