First-Run Setup Wizard¶

Section: Installation | Article 08
Audience: IT Administrators
Last Updated: 2026-04-07

Overview¶

After installing RP-PAM, the first-run setup wizard guides you through the essential configuration steps needed before the platform is operational. The wizard runs once and configures your database connection, encryption keys, admin account, license, database migrations, and optional modules.

You cannot use RP-PAM until the setup wizard has been completed.

What the Setup Wizard Does¶

The wizard performs six sequential steps:

Step	Name	What It Does
1	Database Connection	Configures the connection to your MSSQL or PostgreSQL database and tests connectivity
2	Encryption Initialisation	Generates the Content Encryption Key (CEK) and wraps it with a Key Encryption Key (KEK). This key material protects all secrets stored in the vault
3	Admin Account	Creates the first administrator account with full permissions. This account is used to log in to the web portal for the first time
4	License Import	Imports your license file (`.lic`) to activate RP-PAM. You can activate online or offline
5	Database Migrations	Runs all pending database migrations to create the schema tables, indexes, and seed data
6	Module Selection	Enables optional modules (Active Directory, Entra ID, SSH, Database) based on your license tier

What to Prepare Before Running the Wizard¶

Gather the following information before you start:

Item	Where to Get It
Database server hostname or IP	Your DBA or cloud console (e.g., Azure Portal, AWS RDS console)
Database name	Created in MSSQL Setup or PostgreSQL Setup
Database service account credentials	Created in MSSQL Setup or PostgreSQL Setup (use the `_write` account)
Admin username and password	Choose a username and a strong password (minimum 12 characters, mixed case, numbers, symbols)
Admin email address	A valid email address for the admin account (used for notifications and MFA recovery)
License file	The `.lic` file attached to your Ravenphyre welcome email, or obtained from the Ravenphyre portal

Tip: If you have not yet set up your database, do that first. See MSSQL Setup or PostgreSQL Setup.

Running the Setup Wizard¶

Windows¶

Open an elevated PowerShell prompt (Run as Administrator) and run:

PowerShell:

& "C:\Program Files\Ravenphyre\RP-PAM\rppam.exe" setup-wizard

Alternatively, open a browser and navigate to https://localhost:7101/setup. The web-based wizard provides the same steps with a graphical interface.

Linux¶

Bash:

sudo /opt/rppam/rppam setup-wizard

Or use the web-based wizard at https://localhost:7101/setup.

Docker¶

Bash:

docker exec -it rppam /opt/rppam/rppam setup-wizard

PowerShell:

docker exec -it rppam /opt/rppam/rppam setup-wizard

Or use the web-based wizard at https://localhost:7101/setup (where localhost is the Docker host).

Kubernetes¶

Bash:

kubectl exec -it -n rppam deploy/rppam -- /opt/rppam/rppam setup-wizard

Or port-forward to the pod and use the web wizard:

kubectl port-forward -n rppam svc/rppam 7101:7101 &
# Then open https://localhost:7101/setup in your browser

Step-by-Step Walkthrough¶

Step 1 — Database Connection¶

The wizard prompts for your database details:

Database provider [mssql/postgresql]: mssql
Database host: db-server.example.com
Database port [1433]: 1433
Database name: rppam
Database username: rppam_write
Database password: ********
Use TLS/SSL [Y/n]: Y

The wizard tests the connection. If the test fails, you are prompted to re-enter the details.

Note: Use the _write service account here. RP-PAM will later configure the _read and _audit accounts internally based on your service account setup. See Service Accounts for Active Directory for the three-role account model.

Step 2 — Encryption Initialisation¶

The wizard generates encryption key material:

Initialising encryption...
  Generating Content Encryption Key (CEK)... done
  Generating Key Encryption Key (KEK)... done
  Wrapping CEK with KEK... done
  Writing encrypted key material to disk... done

Encryption initialised successfully.
Key storage location:
  Windows: C:\ProgramData\Ravenphyre\RP-PAM\keys\
  Linux:   /etc/rppam/keys/

Critical: Back up the contents of the keys directory immediately after this step. If you lose the key material, you will not be able to decrypt any secrets stored in the vault. Store the backup in a separate, secure location (hardware security module, sealed USB drive in a safe, or encrypted cloud backup).

Step 3 — Admin Account¶

Create the first administrator account:

Admin username: admin
Admin email: admin@example.com
Admin password: ********
Confirm password: ********

Admin account created successfully.

Password requirements: - Minimum 12 characters - At least one uppercase letter - At least one lowercase letter - At least one number - At least one special character

Step 4 — License Import¶

Import your license file:

License file path: /path/to/rppam-license.lic

Validating license...
  Organisation: Contoso Ltd
  Tier: Enterprise
  Max users: 500
  Expires: 2027-04-07
  Features: AD, Entra ID, SSH, Database, AI, Session Recording, HA

License imported successfully.

You can also paste a license key string if you do not have the .lic file:

License file path [or paste key]: RPPAM-XXXX-XXXX-XXXX-XXXX-XXXX

For offline/air-gapped environments, see Offline License Activation.

Step 5 — Database Migrations¶

The wizard applies all pending migrations:

Running database migrations...
  Applying migration 001_InitialSchema... done
  Applying migration 002_AuditTables... done
  Applying migration 003_VaultTables... done
  ...
  Applying migration 024_ModuleTables... done

All 24 migrations applied successfully.

This step may take 30 seconds to 2 minutes depending on database performance.

Step 6 — Module Selection¶

Choose which modules to enable:

Available modules (based on your license):

  [1] Active Directory    - Manage AD group memberships and credentials
  [2] Entra ID            - Manage Azure AD via Microsoft Graph
  [3] SSH                 - Manage SSH key pairs for Linux servers
  [4] Database            - Provision temporary database users

Enable modules (comma-separated, or 'all'): 1,2,3

Enabling Active Directory... done
Enabling Entra ID... done
Enabling SSH... done

Module configuration complete.

Tip: You can enable or disable modules later from the web portal under Settings > Modules or using the REST API.

After the Wizard Completes¶

When the wizard finishes, you will see:

============================================================
  RP-PAM setup is complete!

  Web Portal:  https://localhost:7101
  REST API:    https://localhost:7101/api
  Health:      https://localhost:7101/health

  Log in with the admin account you just created.
============================================================

Recommended Next Steps After Setup¶

Log in to the web portal at https://<your-server>:7101 using the admin account.
Replace the self-signed TLS certificate with a certificate from your organisation's CA or a public CA.
Encrypt your connection strings — see Connection String Encryption.
Configure additional service accounts — see Service Accounts.
Activate your license online (if not done during the wizard) — see Online License Activation.

Re-Running the Setup Wizard¶

The setup wizard can only be run once. If you need to change settings after the initial setup:

Database connection — Edit rppam.config directly (see Config Reference)
Encryption keys — Cannot be changed after initialisation (by design)
Admin account — Change the password from the web portal or REST API
License — Import a new license from the web portal or REST API
Modules — Enable or disable from the web portal under Settings > Modules

If you need to start completely fresh, delete the database and the key material, reinstall RP-PAM, and run the wizard again.

Troubleshooting¶

Symptom	Cause	Resolution
Wizard says "Setup already completed"	Wizard has already been run on this installation	Use the web portal or config files to make changes instead
Database connection test fails	Wrong hostname, port, credentials, or firewall	Verify you can connect from the RP-PAM server using `sqlcmd` (MSSQL) or `psql` (PostgreSQL)
"Insufficient permissions" on database	Service account lacks required permissions	Grant `db_owner` on the RP-PAM database to the `_write` account (see database setup guides)
Migration fails with timeout	Slow database or large existing data	Increase the migration timeout in `rppam.config` (`migrationTimeoutSeconds`) and retry
License validation fails	Expired license, wrong file, or corrupted download	Re-download the `.lic` file from the Ravenphyre portal; check the file is not truncated
Web wizard at `/setup` returns 404	Setup already completed	The `/setup` endpoint is only available before the wizard has been run

Next Steps¶

Connection String Encryption — Encrypt your database credentials at rest
Online License Activation — Activate your license for automatic check-ins
Offline License Activation — Activate without internet access
Service Accounts — Configure the three-role service account model