First-time admin walkthrough

This guide assumes Skald is installed and the API is reachable. If you haven't deployed yet, start with the README for local installs or the production deployment guide for Kubernetes.

By the end of this walkthrough you'll have:

A working initial admin account
The first room created and people invited
Branding (logo, name, colors) configured if Enterprise
A license key installed (if you have one)
Backups confirmed
SSO and webhooks wired up (if applicable)

Allow about 30–60 minutes total.

1. Bootstrap the initial admin

On a fresh install no users exist. You have two ways to create the first admin:

Option A — Setup wizard (recommended for one-off installs)

Open the admin dashboard in a browser (default http://localhost:5173 for dev, or wherever you proxied /admin). The first time anyone visits, Skald automatically shows the setup wizard. Pick a username and password — that account is created and promoted to admin in a single transaction. You'll be logged in immediately.

Behind the scenes this hits POST /api/public/setup/bootstrap, which refuses to run once any admin exists. The wizard is single-use and disappears.

Option B — Environment variables (recommended for automated installs)

Set these before the API starts and they're applied idempotently on each boot:

bash

SKALD_INITIAL_ADMIN_USERNAME=myadmin
SKALD_INITIAL_ADMIN_PASSWORD=<long-random-secret>

Helm:

yaml

api:
  env:
    - name: SKALD_INITIAL_ADMIN_USERNAME
      value: myadmin
    - name: SKALD_INITIAL_ADMIN_PASSWORD
      valueFrom:
        secretKeyRef:
          name: skald-bootstrap
          key: admin-password

You can remove these vars after the first successful start, or leave them in place — they no-op once the account exists.

Either way, sign into the admin dashboard with your new account before continuing.

2. Install your license key (if you have one)

Skald runs as Community by default with the gated features unavailable. If you bought Professional or Enterprise, install the license before doing anything else so that gated UI surfaces are accessible.

bash

# Docker
docker run -e SKALD_LICENSE_KEY="eyJhbGciOi..." skald/api:latest

# Kubernetes via Secret
kubectl create secret generic skald-license \
  --from-literal=key='eyJhbGciOi...' -n chatty

# Helm values
api:
  env:
    - name: SKALD_LICENSE_KEY
      valueFrom:
        secretKeyRef:
          name: skald-license
          key: key

Restart the API and confirm the tier badge in the admin dashboard. Full reference: Licensing.

If you're just evaluating, run the dev Spring profile locally — it unlocks every feature without a key. Do not run dev in production; it logs a WARN if it detects a non-loopback host.

3. Configure branding (Enterprise)

Admin → Branding lets you replace the Skald name, logo, favicon, and color palette with your own. The public-facing branding endpoint is /api/public/branding, which means clients pick up the new branding without an admin token — the login page itself will be branded.

Minimum recommended changes:

App name (and short name for tabs) — e.g. "Acme Chat" / "Acme"
Logo — a PNG/SVG up to 5 MB (SKALD_BRANDING_ASSET_MAX_BYTES)
Favicon — a 32×32 ICO or PNG
Primary color — used for buttons, links, and highlights (hex #RRGGBB)

The dark and light palettes are configured separately. A "Reset to defaults" button restores the stock Skald palette. See the branding operator doc for the color tokens.

If you don't have an Enterprise license, the branding page returns 403 — skip this step.

4. Create your first rooms

Admin → Rooms → New room to create the first room. Or use the client app — any user can create a room via the + button next to the rooms list.

Choose:

Room ID — appears in URLs (kebab-case)
Description — shown in the room header
E2EE — enable end-to-end encryption (Professional+). Once on, only members can read messages. The server can't.
Voice / video toggle — disable if this room is text-only

Add members from the room settings panel. Invite real users by creating their accounts (Admin → Users → New user) or, if you have SCIM/SSO configured (step 6), they'll get provisioned automatically when they first sign in.

The dev profile auto-seeds a General room and Announcements room with all three test users (alice, bob, admin); production installs start empty.

5. Backups

Configure automated backups before going live. Skald can dump Postgres and mirror MinIO buckets to a separate bucket on a schedule.

Admin → Backups — shows recent backup runs, lets you trigger an on-demand backup, restores from a .tar.gz.
Backups upload to the bucket configured via SKALD_MINIO_BACKUP_BUCKET (default backups).

AWS S3 gotcha: the literal name backups is owned by another AWS account, so on S3 you must set SKALD_MINIO_BACKUP_BUCKET to a release-prefixed value (e.g. acme-skald-backups).

Full procedure and restore steps: Backup & restore.

Test the restore path before you need it. Restore is a destructive operation; verify it works on a non-production install at least once.

6. Configure SSO & SCIM (Enterprise, optional)

If your organization uses an identity provider, wire it up now so the rest of the rollout uses real accounts:

OIDC — set the SKALD_OIDC_* env vars and restart. See environment variables and SSO testing.
SAML — DB-backed. Admin → SAML SSO → upload your IdP metadata and set the user self-service portal URL. See SAML setup.
SCIM — Admin → SCIM tokens → create a token. Plug it into your IdP's provisioning configuration. See SCIM provisioning.

If you skip this and add users later, you can re-enable SSO at any time. Existing local accounts continue to work even after SSO is wired up.

7. Wire up notifications and email (optional)

SMTP — required for email verification, password reset, support email forwarding, and the email digest. Set the SKALD_SMTP_* env vars or Helm smtp.* block. There's a "Send test email" button in Admin → Support → Forwarding once it's configured. See operators/support-email-forwarding.md for the prereq checklist (SPF/DKIM/DMARC, egress, secrets).
iOS native call UI — set skald.apns.enabled=true plus your Apple Team ID, Key ID, .p8 PEM, and bundle ID.
Android native call UI — set skald.fcm.enabled=true and the path to your Firebase service-account JSON.
Expo push — works out of the box. Override the URL via SKALD_EXPO_PUSH_URL if you proxy through your own infrastructure.

Without these, calls still work but iOS lock-screen ring is not available and Android shows a regular notification instead of the full-screen incoming-call UI.

8. Set up outbound webhooks (Enterprise, optional)

If you want Skald events flowing into your audit pipeline, SIEM, or chat-ops tooling, configure outbound webhooks now:

Admin → Webhooks → New endpoint. Provide a URL, a long random signing secret, and the event types you care about. Hit "Send test" to verify connectivity before flipping it on.

Full reference: Webhooks integrator guide.

9. Tune policies before users arrive

A few things you probably want to set before opening the doors:

Admin page	Why
Login Settings	Decide whether to allow self-signup, passwordless email login, magic links.
Discipline Settings	Configure auto-cooldowns and reason categories for moderator actions.
IP Allowlist	Optional — restrict admin sign-in to specific CIDRs.
Rate limits	Per-endpoint rate limits — defaults are conservative; adjust if needed.
Compliance	If you need data retention (Enterprise), configure your retention windows now.
Mobile Updates	Pin a minimum client version if you need to force-upgrade.
Plugins	Inspect any plugins loaded from the classpath.

10. Invite the team

Once branding, backups, SSO, and rooms are configured:

For SSO users — direct them to your portal; the account is created on first sign-in.
For local accounts — Admin → Users → New user. Skald can send an email-verification link (requires SMTP and SKALD_PUBLIC_BASE_URL).
For mobile users — give them an APK or App Store link, and your server's URL. They enter the URL on first launch.

Hand new users the user guide for orientation on chat, threads, calls, and E2EE.

Operating checklist

Once Skald is live, here's the minimum maintenance you should do regularly:

[ ] Monitor backups — Admin → Backups, confirm the latest run is green.
[ ] Watch the license tier badge — surfaces grace-period warnings; renew before expiration.
[ ] Review audit logs weekly (Enterprise) — Admin → Audit Logs.
[ ] Update the API — see the upgrade guide. Flyway migrations run automatically on boot.
[ ] Watch Grafana — dashboards for messaging volume, call quality, push delivery, webhook health.

Need to dig deeper? Start from the documentation index.

First-time admin walkthrough ​

1. Bootstrap the initial admin ​

Option A — Setup wizard (recommended for one-off installs) ​

Option B — Environment variables (recommended for automated installs) ​

2. Install your license key (if you have one) ​

3. Configure branding (Enterprise) ​

4. Create your first rooms ​

5. Backups ​

6. Configure SSO & SCIM (Enterprise, optional) ​

7. Wire up notifications and email (optional) ​

8. Set up outbound webhooks (Enterprise, optional) ​

9. Tune policies before users arrive ​

10. Invite the team ​

Operating checklist ​