Skip to main content
PathMon

Chapter 4 of 15

First-Time Admin Setup

Updated Read the full guide

Overview

The first time you open a fresh PatchMon install in a browser, you see the first-time setup wizard instead of the login page. The wizard creates your superadmin account, optionally sets up multi-factor authentication, confirms the URL agents will use to connect back to the server, and redirects you to the dashboard.

The wizard only runs while no admin user exists in the database. Once the superadmin account is created, the wizard disappears forever and the login page takes over.

This page walks through every step so you know what to expect.

Prerequisites

Before starting the wizard, PatchMon must already be running. You should be able to open http://localhost:3000 (or your configured URL) in a browser and see the wizard's welcome screen. If you don't, check:

Wizard Steps at a Glance

The wizard has up to five steps. Some are skipped depending on your deployment mode:

Step Name Always shown?
1 Create Admin Account Yes
2 Multi-Factor Authentication Yes
3 Confirm Server URL Only shown on self-hosted
4 Stay Updated (newsletter opt-in) Hidden when newsletter is disabled
5 Get in Touch (community links) Yes

Self-hosted users see all five steps. PatchMon Cloud users skip step 3 (the server URL is set for you) and may see fewer of the others depending on branding.

Step 1: Create Admin Account

The first screen collects the superadmin's name, username, email, and password.

Fields

Field Rules
First name Required
Last name Required
Username Required, at least 2 characters. Used to log in.
Email Required, valid email format
Password Must satisfy the active password policy (see below)
Confirm password Must match the password

Password policy

The password policy is pulled live from the server (GET /api/v1/settings/login-settings). Defaults require:

  • At least 8 characters
  • One uppercase letter
  • One lowercase letter
  • One number
  • One special character

A strength meter and per-rule checklist underneath the password field show which rules are satisfied as you type.

Tip: If you want a weaker or stronger policy before first login, set the PASSWORD_* variables in your .env before running docker compose up -d. See the Environment Variables Reference for the full list.

What happens when you click Next

The form is validated client-side first, then the server checks that no admin user already exists before accepting the submission. If somebody has already created an admin (for example because two people opened the wizard at the same time), you'll see Admin users already exist. This endpoint is only for first-time setup. The first person to submit wins; log in with those credentials instead.

The admin user is created with role superadmin, which has every permission in the system. You can demote later or create narrower roles from Settings → Users → Roles once you're logged in.

Step 2: Multi-Factor Authentication

After the admin account details are entered, the wizard offers to set up TOTP-based multi-factor authentication (MFA). You have two choices:

  • Setup MFA now: the admin account is created immediately and the TFA setup UI appears in-line. You scan a QR code, confirm with a 6-digit code, then receive one-time backup codes to save somewhere safe.
  • Skip (I'll do it later): the wizard moves on and the admin account is created at the end, with MFA disabled. You can enable it any time afterwards from Settings → My Profile → Two-Factor Authentication.

The "Setup MFA now" flow

Clicking Setup MFA now does three things:

  1. Creates the admin account immediately (rather than at the end of the wizard).
  2. Logs you in automatically (session cookies are set).
  3. Shows a QR code from the standard TOTP setup endpoint (GET /api/v1/tfa/setup).

Follow the in-page instructions:

  1. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, Bitwarden, Proton Authenticator, etc.). Most standards-compliant TOTP apps work.
  2. Enter the 6-digit code the app shows you.
  3. Save the backup codes. PatchMon issues a set of one-time backup codes when MFA verification succeeds. Download them as a text file and store them somewhere that is not your authenticator app (a password manager is ideal). Each code can be used exactly once if you lose your authenticator; once you run out, you'll need to reset MFA by signing in with another admin account.
  4. Click Continue to return to the wizard.

Important: The backup codes are displayed once only. If you close the tab before copying them, you'll need to disable and re-enable MFA from your profile page to generate a new set.

The admin account has full control over your entire fleet: it can trigger patch runs, read every host's inventory, and manage all users. If the admin password is compromised, MFA is the remaining barrier between an attacker and your infrastructure. Enable it on every production deployment.

Step 3: Confirm Server URL

This step only appears in self-hosted deployments. On PatchMon Cloud, the server URL is set for you and this step is skipped.

What the "server URL" means

This is the URL agents will use to connect back to the PatchMon server (not the URL users open in their browser, although it is usually the same). It is stored in the database and baked into every agent install command the UI generates. Change it later and every new agent will use the new value; existing agents keep using whatever URL they were installed with until you rerun their install script.

Fields

Field Description
Protocol HTTP or HTTPS. Use HTTPS in any non-lab deployment.
Host The DNS name or IP agents reach, e.g. patchmon.example.com.
Port Public port. Usually 443 for HTTPS, 80 for HTTP, or 3000 for direct-to-container setups without a reverse proxy.

The wizard pre-fills these by calling GET /api/v1/settings/current-url, which reflects the URL in the browser's address bar. If you opened the wizard at https://patchmon.example.com, those values are already correct.

Self-signed SSL toggle

The toggle "Will you be using a self-signed SSL certificate?" controls whether the install command the UI generates passes -k to curl. Enable it only if your TLS certificate is not trusted by the system CA bundle on the target hosts, for example a private-CA internal certificate.

Warning: skip_ssl_verify disables TLS verification in the agent as well, which exposes agents to man-in-the-middle attacks on the enrolment network path. The preferred fix is to install your CA into the host's trust store (/usr/local/share/ca-certificates/ on Debian/Ubuntu, /etc/pki/ca-trust/source/anchors/ on RHEL/Fedora). Only enable the toggle in lab or air-gapped deployments.

You can change all of these values later from Settings → Server URL.

Step 4: Stay Updated (optional)

The newsletter opt-in step offers to sign you up for PatchMon's security and product update newsletter. Toggle it on to subscribe with the name and email from step 1, or leave it off to skip.

No tracking happens. The only network call is a single subscribe request to the upstream marketing endpoint when you click through, and only when the toggle is on. Your email is never sent anywhere without your explicit opt-in.

This step is hidden if the server's login-settings response includes show_newsletter: false (for example, on self-hosted installs that have disabled marketing).

Step 5: Get in Touch

The final screen lists community and support links: Discord, GitHub, documentation, the feature roadmap, and bug reporting. Feature requests go to the feedback portal; bugs go to GitHub Issues. Click Access Dashboard to finish setup.

What happens when you finish

  1. If you didn't choose "Setup MFA now" earlier, the admin account is created now via POST /api/v1/auth/setup-admin.
  2. The server URL settings are saved via PATCH /api/v1/settings (self-hosted only).
  3. If you opted in to the newsletter, one subscribe call goes out.
  4. Cookies are set for your admin session and you're redirected to / (the dashboard).

The first-time wizard is complete. The next time you open PatchMon, you'll see the normal login page.

Errors You Might See

"Admin users already exist"

The server already has at least one admin account. The wizard only runs while the database is empty. Log in with the existing admin credentials instead.

"Password does not meet the password policy"

One or more of the password rules isn't satisfied. Re-read the checklist under the password field. Every box that isn't ticked is a failing rule.

"Setting up PatchMon" stuck on a step

If the setup spinner sits on "Creating admin account..." or "Saving server URL..." for more than 10 seconds, something is wrong between the browser and the server. A red error bar appears with two buttons:

  • Retry: retries the same call. Useful for transient network hiccups.
  • Skip and continue: if the admin account was created successfully but the URL save failed, this takes you to the dashboard anyway. You can finish the URL configuration from Settings → Server URL.

Check the server logs in parallel:

docker compose logs -f server

Browser says "CORS policy" after clicking Next

Your CORS_ORIGIN doesn't match the URL in your browser's address bar. Fix it in .env, restart the server container, and reload the page. If users access PatchMon from more than one URL, comma-separate the values with no spaces, e.g. CORS_ORIGIN=https://patchmon.example.com,https://patchmon.internal.lan. See Environment Variables Reference: CORS_ORIGIN.

What to Do Next

With the wizard complete, the usual next steps are:

  1. Enrol your first host. Go to Hosts → Add Host, pick the target OS, and copy the generated one-line install command to run on the server.
  2. Confirm the agent reports in. Within a minute, the host should appear on the Hosts page with a green "online" indicator. If it doesn't, see Managing the PatchMon Agent.
  3. Review your settings. The Settings in the web UI page walks through every settings area, including where to configure OIDC SSO, branding, notifications, and alerts.
  4. Secure the deployment. Enable HTTPS via a reverse proxy (Reverse proxy examples), set ENABLE_HSTS=true, set TRUST_PROXY=true, and consider enabling OIDC SSO or OIDC_DISABLE_LOCAL_AUTH for production.

See Also