26 · Admin · Integrations

The platform integrates with several external services. Each integration has its own admin page where you configure the URL/credentials and toggle the integration on or off.

Email

/admin/settings/email

A read-only view of the outgoing SMTP and inbound IMAP configuration. The values are owned by /opt/.env — the page shows what each key is currently set to (passwords masked) and lets you copy an .env snippet to paste in. Changes take effect after /opt/run/start-all.sh.

Outbound (SMTP)

Env key	Purpose
SMTP_HOST	SMTP server hostname
SMTP_PORT	SMTP port
SMTP_USER	SMTP username
SMTP_PASS	SMTP password (masked in the UI)
SMTP_FROM	From address on outgoing mail

📷 Screenshot placeholder: screenshots/admin-email.png

Inbound (ticket intake)

Inbound mail is polled over IMAP:

Env key	Purpose
IMAP_HOST	IMAP server hostname
IMAP_PORT	IMAP port
IMAP_USER	IMAP username
IMAP_PASS	IMAP password (masked in the UI)
IMAP_MAILBOX	Mailbox to poll (e.g. INBOX)

Tickets are created from mail in the polled mailbox.

SIP (telephony)

/admin/settings/sip

A read-only view of the SIP trunk configuration for the softphone. Like the email page, the values are owned by /opt/.env; the page shows the current settings and a copyable .env snippet.

Env key	Purpose
SIP_SERVER	IP/hostname of your SIP provider
SIP_USERNAME	SIP auth username
SIP_PASSWORD	SIP auth password (masked in the UI)
SIP_REALM	SIP realm

⚠️ Caution. SIP credentials live in /opt/.env on the host (chmod 600). Keep that file protected and rotate the credentials periodically.

Checkmk

/admin/checkmk

Connects a Checkmk monitoring server so its hosts and alerts surface in the platform.

• Site URL — base URL of your Checkmk site
• Site name — Checkmk site ID (default cmk)
• API username — Checkmk automation user (default automation)
• API secret — the automation user's secret
• Sync interval (minutes) — how often hosts re-sync (default 5)
• Active — enable/disable the integration

The page has three tabs: Hosts (synced Checkmk hosts and their service-state counts, with their mapped RMM device), Sync runs (history of each sync — hosts added/updated, alerts created, devices mapped, errors) and Config (the connection form above). A Sync now action triggers an ad-hoc sync.

Public access to the Checkmk web UI

The Checkmk web UI is exposed publicly as a path prefix on the main portal host via a Traefik path-rewrite proxy:

• URL: https://portal.kwgroup.org.uk/checkmk/
• Login: Checkmk's own cmkadmin user (not the portal login) — see /opt/passwords.md §9 for the live credentials.
• Auth model: no portal auth wraps the path. The Checkmk login page is the gate; valid cmkadmin or automation credentials are required to proceed.
• Config: the router lives in /opt/data/traefik/dynamic/checkmk.yml and is picked up live by Traefik's file provider — no restart needed for edits.
• Internal listener: http://host.docker.internal:5000/cmk/check_mk/ (the kwgroup-checkmk container, port 5000 published to the host).

The router matches both PathPrefix(/checkmk) (the public entry path) and PathPrefix(/cmk/check_mk) (the absolute paths Checkmk uses in its own Location: headers after login), so the post-login redirect chain stays inside the Checkmk service instead of falling through to the Next.js portal.

📷 Screenshot placeholder: screenshots/admin-checkmk.png

Vaultwarden

/admin/vaultwarden

Connects a Vaultwarden instance for shared password collections — see Files & vault.

• Base URL — your Vaultwarden URL, typically https://secure.kwgroup.uk
• Admin token — Vaultwarden admin token used by the platform
• Vaultwarden org ID — the Vaultwarden organisation to manage (optional)
• SSO redirect URL — where the portal sends users into Vaultwarden (optional)
• Active — enable/disable the integration

The page has three tabs: Requests (pending/decided collection-access share requests, which an admin approves or denies), Collections (shared vault collections and their members) and Config (the connection form above).

⚠️ Caution. Don't change the base URL after rollout — existing vault links are absolute.

InvoiceNinja

/admin/integrations/invoiceninja

Connects the platform to InvoiceNinja (v5 REST API) for Billing.

The integration is configured by env, not the UI — the platform keeps these secrets out of the database on purpose:

Env key	Purpose
INVOICENINJA_URL	Your InvoiceNinja install URL
INVOICENINJA_TOKEN	API token from InvoiceNinja → Settings → Account Management → API Tokens

Set these in /opt/.env and restart the portal. The admin page is a connection tester — it calls InvoiceNinja and reports one of: not configured, connected (with the company name), or configured but unreachable (with the error). A Re-test connection button re-runs the check.

How it links

• Each portal customer maps to one InvoiceNinja client; the first invoice push creates the client if it doesn't exist.
• A billable project pushes an invoice or quote that references the project ID in the InvoiceNinja po_number field.
• A billable ticket pushes an invoice referencing the ticket ID.
• The Billing page lists every invoice and quote across all customers.

Apps & tiles

/admin/apps

The dashboard tile launcher. Each tile is one of the built-in apps but you can:

• Re-order tiles via drag-drop
• Hide tiles per role (e.g. don't show Marketing to support users)
• Add custom tiles — link to any URL with a label/icon. Useful for in-house tools (Grafana, internal docs).

Permissions

Integration	Required role
Email	admin
SIP	admin
Checkmk	admin
Vaultwarden	admin (admin tenancy)
InvoiceNinja	admin
App tiles	admin

Common workflows

Plug in Checkmk

1. In Checkmk: create the automation user, copy its secret.
2. Admin → Checkmk → Config tab → fill Site URL, site name, API username, API secret.
3. Save, then Sync now.
4. The Hosts tab populates with synced Checkmk hosts.

Add a custom dashboard tile

1. Admin → App tiles → + Add custom tile.
2. Label "Grafana", icon "📊", URL.
3. Pick which roles see it.
4. Users see it on their dashboard within seconds.

Switch SMTP providers

1. Edit SMTP_* keys in /opt/.env (the Admin → Email page shows the current values and a copyable snippet).
2. Run /opt/run/start-all.sh to restart the services.
3. Confirm Admin → Email reflects the new host/user.

See also

• Helpdesk — ticket intake
• Meetings & calls — softphone
• RMM — Checkmk integration
• Files & vault — Vaultwarden
• Billing — InvoiceNinja