A self-hosted web UI for investigating alerts, managing decisions, tracking long-term attack trends, monitoring runtime metrics, and sending notifications with CrowdSec.

You need a running CrowdSec LAPI. Connect the Web UI using either watcher password authentication or agent mTLS.

openssl rand -hex 32
docker exec crowdsec cscli machines add crowdsec-web-ui --password 'replace-with-generated-password' -f /dev/null

# For local installations
sudo cscli machines add crowdsec-web-ui --password 'replace-with-generated-password' -f /dev/null

Replace replace-with-generated-password with the value printed by openssl.

Configure LAPI TLS authentication and create a client certificate/key pair using the CrowdSec TLS authentication guide.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    container_name: crowdsec_web_ui
    ports:
      - "3000:3000"
    # For local CrowdSec instances
    # extra_hosts:
      # - "host.docker.internal:host-gateway"
    environment:
      CONFIG_INSTANCE_LAPI_URL: http://crowdsec:8080
      # For local CrowdSec instances
      # CONFIG_INSTANCE_LAPI_URL: http://host.docker.internal:8080
      CONFIG_INSTANCE_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCE_LAPI_AUTH_PASSWORD: your-crowdsec-password
    volumes:
      - ./data:/app/data
    restart: unless-stopped

A ready-to-use docker-compose.yml is included. Add the generated password, make sure the Web UI can reach CrowdSec on the same Docker network, then start it.

docker compose up -d

Open http://localhost:3000 and create the initial administrator account.

docker pull ghcr.io/theduffman85/crowdsec-web-ui:latest
mkdir -p data
docker run -d \
  --name crowdsec_web_ui \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e CONFIG_INSTANCE_LAPI_URL=http://crowdsec:8080 \
  -e CONFIG_INSTANCE_LAPI_AUTH_USERNAME=crowdsec-web-ui \
  -e CONFIG_INSTANCE_LAPI_AUTH_PASSWORD=your-crowdsec-password \
  --network your_crowdsec_network \
  ghcr.io/theduffman85/crowdsec-web-ui:latest

Current images use Node.js and do not have the former Bun/AVX-specific x64 limitation.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    container_name: crowdsec_web_ui
    ports:
      - "3000:3000"
    environment:
      CONFIG_INSTANCE_LAPI_URL: https://crowdsec:8080
      CONFIG_INSTANCE_LAPI_AUTH_TYPE: mtls
      CONFIG_INSTANCE_LAPI_AUTH_CERT_FILE: /certs/agent.pem
      CONFIG_INSTANCE_LAPI_AUTH_KEY_FILE: /certs/agent-key.pem
      # CONFIG_INSTANCE_LAPI_TLS_CA_FILE: /certs/ca.pem
    volumes:
      - ./data:/app/data
      - /path/on/host/agent.pem:/certs/agent.pem:ro
      - /path/on/host/agent-key.pem:/certs/agent-key.pem:ro
      # - /path/on/host/ca.pem:/certs/ca.pem:ro
    restart: unless-stopped

Adjust the URL and certificate paths. Enable CONFIG_INSTANCE_LAPI_TLS_CA_FILE and its volume when LAPI uses a private CA.

Use CONFIG_FILE only to select another existing file. config.example.yaml contains the complete commented YAML reference.

• Values are parsed as YAML and validated.
• CONFIG_AUTH_OIDC_CLIENT_ID parses YAML scalars as strings, preserving numeric identifiers and leading zeros. For example, CONFIG_AUTH_OIDC_CLIENT_ID=123456789012345678901 keeps every digit; YAML-quoted values also work. In config.yaml or whole-section CONFIG_AUTH overrides, quote numeric client IDs (for example clientId: "123456789012345678901").
• Arrays use zero-based contiguous indexes: CONFIG_AUTH_OIDC_ADMIN_GROUPS_0, CONFIG_INSTANCES_0_ID, CONFIG_INSTANCES_0_METRICS_0_URL.
• OIDC role groups require YAML arrays (for example CONFIG_AUTH_OIDC_ADMIN_GROUPS='[crowdsec_admins]' and CONFIG_AUTH_OIDC_READ_ONLY_GROUPS='[crowdsec_users]') or indexed variables, even for a single group.
• Whole sections accept YAML through CONFIG_SERVER, CONFIG_STORAGE, CONFIG_UI, CONFIG_AUTH, CONFIG_NOTIFICATIONS, CONFIG_AUDIT, CONFIG_UPDATES, CONFIG_CROWDSEC, or CONFIG_INSTANCES.
• CONFIG_INSTANCE_* addresses instance 0: CONFIG_INSTANCE_NAME equals CONFIG_INSTANCES_0_NAME. Metrics index 0 may also be omitted: CONFIG_INSTANCES_0_METRICS_URL equals CONFIG_INSTANCES_0_METRICS_0_URL, and CONFIG_INSTANCE_METRICS_URL applies both shorthands. Do not set equivalent forms together.
• Secrets accept a direct string or exactly one env: NAME / file: PATH reference. Secret overrides also accept _FILE.
• Initial direct secret overrides are stored as environment references, never plaintext. Persisted secret references still require their environment variable.

Some values can be set either in Settings or in the application config: the refresh interval, manual refresh, password login, and all OIDC fields. A value set in config.yaml or through its CONFIG_* variable takes precedence and is locked in Settings, marked with a lock icon whose tooltip names the CONFIG_* variable or config path that sets it. Leave it unset to manage it in Settings. Manual decision scenarios from the config are always offered and can't be removed in Settings, but more can be added there.

To manage a locked value in Settings again, remove it from both the environment and config.yaml, then restart; the last value saved in Settings applies again. CONFIG_* values are written into config.yaml when the file is first created, and on every start with CONFIG_PERSIST_OVERRIDES: "true", so removing the variable alone may not unlock the setting.

Date patterns require one day, month, and year token in any order: d/dd (day), m/mm (numeric month), mmm/mmmm (localized month name), and yy/yyyy (year). Punctuation and spaces are literal; wrap words in single quotes, for example d 'of' mmmm yyyy. Date patterns affect full dates and timestamps; compact chart labels keep their own display format. Set ui.timeFormat separately for a 12 or 24 hour clock.

User actions that change CrowdSec state (adding decisions, deleting decisions and alerts, and per-IP cleanup) and user management changes (user.create, user.update, user.password-reset, user.mfa-reset, user.oidc-link, user.oidc-unlink, user.delete) are recorded as single [audit] lines in the application log. Each entry is a JSON object with the timestamp, acting user and role, action, target (IP, range, or entity IDs), and outcome:

[audit] {"time":"2026-08-17T01:30:00.000Z","user":"tommy","role":"admin","action":"decision.add","ip":"192.0.2.10","type":"ban","scenario":"manual/web-ui","duration":"4h","reason":"manual","instances":["CrowdSec"],"outcome":"success"}

Outcomes are success, partial, failure, or queued. Alert deletions handled by the persistent deletion queue are recorded as queued, because CrowdSec may complete them after the HTTP request returns. Multi-target actions include target_results or instance_results so successful, failed, and queued targets remain distinguishable. The Alerts page sends large deletions in batches of 2,000 alerts, and each batch has its own audit entry.

Omitting crowdsec.alertFilters uses the standard non-CAPI feed. Setting any explicit filter field enables explicit filtering.

The Add Decision form always offers manual/web-ui and selects it by default. With no other scenarios available, the scenario field is hidden and manual/web-ui is used; additional scenarios turn it into a dropdown. Admins can also add and remove scenarios under Settings → General → Manual decisions; those are stored in the database, offered for every instance on top of the configured list, and take effect without a restart. Scenarios from config.yaml or CONFIG_ variables are shown there as read-only. When All instances targets instances with different lists, only manual/web-ui is used and the field is hidden. These lists only shape the form: POST /api/decisions accepts any author/name scenario. If crowdsec.alertFilters.legacy.extraScenarios is used to show manual decisions, add the configured scenarios there too.

CrowdSec LAPI does not check allowlists for decisions sent with an alert, which is how the Web UI adds them. Like cscli decisions add, the Web UI therefore checks the target instances' allowlists first and refuses an allowlisted IP or range until Bypass allowlist is confirmed. Instances whose LAPI predates allowlists (CrowdSec 1.6.5) or cannot be checked do not block the decision.

Synchronization durations accept ms, s, m, h, or d, for example 500ms, 30s, 5m, or 7d. The lookback fields accept only m, h, or d.

• <INDEX> is zero-based.
• ID defaults to the index; name defaults to Instance <INDEX>; authentication type is inferred from credentials.
• Inferred values appear as comments in initial YAML unless compatibility requires an explicit identity.
• Explicit IDs use lowercase letters, digits, _, and -. Keep them stable after importing data.

• <INDEX> selects the instance; zero-based <METRIC_INDEX> selects its endpoint.
• Endpoint ID defaults to <METRIC_INDEX> and name to Metrics <METRIC_INDEX>.
• Endpoint icons are optional short text or emoji values and appear in the metrics source selector.
• Inferred values appear as comments in initial YAML.

Every field inherits its corresponding global value when omitted.

Use zero-based CONFIG_INSTANCES_<INDEX>_* overrides to define each instance. Indexes must be contiguous, starting at 0.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    environment:
      CONFIG_INSTANCES_0_ID: eu-prod
      CONFIG_INSTANCES_0_NAME: EU Production
      CONFIG_INSTANCES_0_LAPI_URL: http://crowdsec-eu:8080
      CONFIG_INSTANCES_0_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCES_0_LAPI_AUTH_PASSWORD_FILE: /run/secrets/eu-lapi-password
      CONFIG_INSTANCES_0_METRICS_0_ID: lapi
      CONFIG_INSTANCES_0_METRICS_0_NAME: EU LAPI
      CONFIG_INSTANCES_0_METRICS_0_URL: http://crowdsec-eu:6060/metrics

      CONFIG_INSTANCES_1_ID: us-prod
      CONFIG_INSTANCES_1_NAME: US Production
      CONFIG_INSTANCES_1_LAPI_URL: http://crowdsec-us:8080
      CONFIG_INSTANCES_1_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCES_1_LAPI_AUTH_PASSWORD_FILE: /run/secrets/us-lapi-password

      # For mTLS, replace instance 1's URL and password credentials above with:
      # CONFIG_INSTANCES_1_LAPI_URL: https://crowdsec-us:8080
      # CONFIG_INSTANCES_1_LAPI_AUTH_TYPE: mtls
      # CONFIG_INSTANCES_1_LAPI_AUTH_CERT_FILE: /certs/us-client-cert.pem
      # CONFIG_INSTANCES_1_LAPI_AUTH_KEY_FILE: /run/secrets/us-client-key.pem
      # CONFIG_INSTANCES_1_LAPI_TLS_CA_FILE: /certs/us-ca.pem
    volumes:
      - ./secrets/eu-lapi-password:/run/secrets/eu-lapi-password:ro
      - ./secrets/us-lapi-password:/run/secrets/us-lapi-password:ro
      # Mount these files when using the commented mTLS configuration:
      # - ./certs/us-client-cert.pem:/certs/us-client-cert.pem:ro
      # - ./secrets/us-client-key.pem:/run/secrets/us-client-key.pem:ro
      # - ./certs/us-ca.pem:/certs/us-ca.pem:ro

• Use indexed variables for every instance in a multi-instance setup; reserve the CONFIG_INSTANCE_* shorthand for single-instance deployments.
• Each instance needs a stable ID, unique display name, LAPI URL, and one authentication method.
• Add metrics endpoints with CONFIG_INSTANCES_<INDEX>_METRICS_<METRIC_INDEX>_*.
• Mount password files read-only. When using the optional mTLS configuration, mount its private keys and certificates read-only as well, then restart the container.

Add entries to the top-level instances array. Each entry defines one LAPI connection and zero or more metrics endpoints.

instances:
  - id: eu-prod
    name: EU Production
    icon: 🇪🇺
    lapi:
      url: http://crowdsec-eu:8080
      auth:
        type: password
        username: crowdsec-web-ui
        password:
          file: /run/secrets/eu-lapi-password

    metrics:
      - id: lapi
        name: EU LAPI
        icon: 🧠
        url: http://crowdsec-eu:6060/metrics
        auth:
          type: bearer
          token:
            file: /run/secrets/eu-metrics-token

      - id: edge-engine
        name: EU Edge Engine
        icon: 🛡️
        url: http://crowdsec-edge:6060/metrics

    sync:
      requestTimeout: 45s
      alertSyncChunk: 6h

  - id: us-prod
    name: US Production
    icon: 🇺🇸
    lapi:
      url: http://crowdsec-us:8080
      auth:
        type: password
        username: crowdsec-web-ui
        password:
          file: /run/secrets/us-lapi-password
      # For mTLS, replace url and auth above with:
      # url: https://crowdsec-us:8080
      # auth:
      #   type: mtls
      #   certFile: /run/secrets/us-client-cert
      #   keyFile: /run/secrets/us-client-key
      # tls:
      #   caFile: /run/secrets/us-ca

• Instance and endpoint IDs are unique, URL-safe, and immutable database identities. They are 1–63 characters long, start with a lowercase letter or digit, use only lowercase letters, digits, _, or -, and must never be reused for another LAPI.
• Display names are unique but editable. icon accepts up to eight Unicode code points of text or emoji without control characters; omitted icons use colored squares and Combined uses a grid.
• Password secrets accept a direct value or exactly one env/file source. mTLS requires both certFile and keyFile; tls.caFile controls server trust.
• Metrics authentication supports none, basic, and bearer; metrics TLS supports caFile plus an optional complete client certificate/key pair.
• Embedded URL credentials, URL fragments, ambiguous secret sources, partial certificate pairs, unreadable files, and TLS verification bypasses fail validation. LAPI base URLs also reject paths.
• Prefer mounted secret files. Restart after configuration, certificate, or secret changes.

Authentication covers the browser UI and protected APIs; /api/health remains public.

Enable authentication explicitly on installations migrated from older releases.

auth:
  enabled: true

• Password changes and passkey registration/removal under Settings → Profile. A new password must differ from the current one.
• Optional TOTP enrollment through a QR code, mobile setup link, or manual key.
• An enrolled TOTP seed overrides the optional base32 auth.totpSeed fallback.
• Enabling or disabling TOTP signs out the account's other sessions. Disabling it requires a current authenticator code.
• Local sessions last up to 30 days. Logging out revokes the session on the server, so a copied session cookie stops working too.
• Administrators can disable password login under Settings → Authentication, or pin it from deployment config:

auth:
  passwordLogin:
    enabled: false # CONFIG_AUTH_PASSWORD_LOGIN_ENABLED=false

When auth.passwordLogin.enabled is set, it overrides the Settings value and the toggle is shown as managed by configuration. Removing it restores the last value saved in Settings. To avoid a lockout, false only takes effect while OIDC or an administrator's passkey is configured; otherwise password login stays enabled and a warning is logged. Password hashes are kept, so setting enabled: true and restarting restores password login if the identity provider is unreachable.

Every user has a Settings → Profile tab with their language, font, and Metrics and Allowlists sidebar visibility, plus their own password, TOTP, and passkeys and, while OIDC is configured, their linked SSO identity. The display preferences are saved for the account and follow the user to other browsers; without dashboard authentication they apply to the whole instance. Profile remains editable in read-only mode, including when dashboard authentication is disabled. Read-only users only see Profile, because they cannot change anything else; General, Authentication (password login and OIDC), Users, and Branding are shown to administrators.

Administrators manage accounts under Settings → Users:

• Create local users with a username, an initial password, and the admin or read-only role. Read-only users have the same permissions as OIDC users in a read-only group.
• Change a local user's role, or disable and re-enable the account. Disabling ends the user's sessions.
• Reset a local user's password. By default, the user must choose a new password at the next password sign-in before using anything else; new users start the same way.
• Reset a local user's TOTP and passkeys, for example after a lost phone. The user's sessions end and both can be set up again.
• Delete users. OIDC users are listed after their first sign-in; their role comes from the identity provider, so they can only be deleted. A deleted OIDC user is added again on the next sign-in if the identity provider still allows it. An OIDC user the group settings deny is shown as read-only and no longer counts as an administrator until an allowed sign-in restores the role.
• Remove the SSO link of an account shown as Local + SSO. These accounts are managed like local accounts, and the local sign-in stays.

Administrators cannot change, disable, or delete their own account there, and the last active administrator cannot be demoted, disabled, or deleted. While passkeys are the only sign-in method (password login disabled, no OIDC), changes that would leave no enabled administrator with a passkey are rejected. A user with a pending password change cannot register passkeys or set up TOTP until the password is changed. Changes are written to the audit log.

Configure OIDC in Settings or YAML. Fields set in YAML are locked in Settings; see Settings managed by configuration.

auth:
  enabled: true
  oidc:
    issuerUrl: https://idp.example.com/application/o/crowdsec-web-ui/
    clientId: crowdsec-web-ui
    clientSecret:
      file: /run/secrets/oidc_client_secret
    scope: openid profile email
    groupsClaim: groups
    adminGroups: [crowdsec-admins, secops]
    readOnlyGroups: [crowdsec-viewers]
    unmatchedRole: deny
    endSession: true
    backchannelLogout: true
    autoLogin: false

Register this callback URI with the identity provider.

https://<crowdsec-web-ui-host>/api/auth/oidc/callback

• The callback must exactly match the public scheme, host, port, and base path. For basePath: /crowdsec, use https://<host>/crowdsec/api/auth/oidc/callback.
• Reverse proxies must forward Host or X-Forwarded-Host and X-Forwarded-Proto.
• Saved Settings override YAML. Scopes must include openid; add provider-specific scopes such as groups only when required.
• Admin-group matches have full access; read-only-group matches can view data and keep permitted preferences; unmatched users follow auth.oidc.unmatchedRole (deny by default).
• Set an unmatched fallback role only when every user who can sign in should receive it.
• ui.readOnly: true overrides all roles for the deployment. It blocks CrowdSec writes, refresh changes, notification destination/rule management, test sends, and notification deletion. Personal preferences under Profile (language, font, and Metrics and Allowlists sidebar visibility) and marking notifications read remain available. This is not per-user RBAC.
• Identities use stable issuer and subject claims. Username collisions with local accounts remain separate.
• Sessions have a 24-hour absolute lifetime. OIDC-only users cannot add local passkeys; password-backed local accounts retain passkey support.
• Existing OIDC rows migrate on their next successful SSO login.
• If the provider cannot be reached, local sign-in keeps working and SSO comes back without a restart once the provider responds.

With auth.oidc.endSession: true or the matching Settings toggle, logging out of the dashboard also ends the SSO user's session at the identity provider (OpenID Connect RP-initiated logout), so the next SSO sign-in asks for credentials again. It is off by default because the provider may reject the redirect until the URI below is registered. Installations that already used OIDC when upgrading keep the earlier default of on unless the configuration or Settings sets a value. This requires the provider to advertise an end_session_endpoint; otherwise only the dashboard session is cleared. Register this post-logout redirect URI with the identity provider:

https://<crowdsec-web-ui-host>/login

Include the base path when one is configured, for example https://<host>/crowdsec/login. Leave it off to only clear the dashboard session.

To end dashboard sessions when a user signs out at the identity provider, enable auth.oidc.backchannelLogout or the matching Settings toggle and register this back-channel logout URI with the provider (OpenID Connect Back-Channel Logout):

https://<crowdsec-web-ui-host>/api/auth/oidc/backchannel-logout

Include the base path when one is configured. While the setting is off, logout notifications are rejected. The provider must be able to reach the dashboard directly, and logout tokens must be signed with a key from the provider's JWKS or, for HMAC tokens, with the client secret. A logout token with a session ID (sid) ends only the sessions from that provider sign-in, even when it also names the user (sub); if it names the user, it also ends that user's sessions that carry no sid, such as sessions from before the upgrade. Without sid, it ends all dashboard sessions for the named user. Repeated notifications with the same issuer and token ID (jti) are acknowledged without revoking later sign-ins; this protection survives restarts.

With auth.oidc.autoLogin: true or the matching Settings toggle, the login page redirects straight to the identity provider. It only applies while OIDC is configured and password login is disabled; otherwise the setting stays inactive and the server logs why. After a logout, the login page is shown once instead of redirecting, so users are not signed straight back in. Open /login?local=1 to reach the login page anyway, for example to sign in with a passkey.

A local account can also sign in with one SSO identity, so a single account has both sign-in methods and local sign-in stays available during an identity provider outage. The strictest setup is still a separate emergency account that is not linked to anything; linking is for when you want one account per person.

To link an account, sign in with your password or a passkey and open Settings → Profile → Single sign-on → Link SSO identity. After you sign in at the identity provider, the dashboard shows the identity it received and asks for your password and, if enabled, your authenticator code. Identities are matched by issuer and subject (iss + sub), never by username or email. An identity the group settings deny cannot be linked. Confirming only applies to the identity on screen: if a newer attempt in another tab replaced it, nothing is linked and you start again.

If the identity already has a separate SSO account, such as admin#oidc-1a2b3c4d5e, confirming the link merges it into the local account and removes it. Its saved search filters move over, unless the local account already has a filter with that name. Its display preferences and recent filters are dropped in favor of the local account's. A disabled SSO account is not merged; delete it first if that person should have access again.

What each sign-in method can do on a linked account:

• Password and passkey sessions use the local role set under Settings → Users. Nothing from the identity provider changes it, ends those sessions, or blocks that sign-in. A local username is never renamed.
• SSO sessions use the role from the identity provider, last updated at SSO sign-in. A denied identity loses SSO access only, and its SSO role is cleared until an allowed sign-in restores it. SSO sessions cannot change the password, TOTP, passkeys, or the link.
• Disabling or deleting the account applies to both sign-in methods. So do local credential changes and resets, which end all of the account's sessions.
• Last-administrator checks count either role, but the SSO role only while its issuer is still the configured one and the provider has not denied the identity. Unlinking is refused when the account's SSO role is the last administrator access.

Removing someone from the identity provider does not remove their local password. The dashboard cannot detect this until they try to use SSO, so also disable their account under Settings → Users.

The same section shows whether the provider is reachable, checked when the page loads and reused for up to 30 seconds. Provider unavailable is temporary and leaves the link in place, while Provider changed means the configured issuer is no longer the one the identity came from.

To unlink an account, use the same section with your password and authenticator code, or Remove SSO link as another administrator. This ends the account's sessions, and the next SSO sign-in creates a separate account again. If the identity provider's issuer changes, existing links stop working; local sign-in keeps working, and each account has to be unlinked and linked again.

Linking existing accounts by username (Settings → Authentication, or auth.oidc.autoLinkUsername: true) is off by default and meant for migrations. While it is on, an allowed SSO sign-in links automatically to an enabled local account with exactly the same preferred_username, and merges any separate SSO account of that identity, without asking for the local password. Accounts already linked, accounts created while the setting is on, and accounts that were unlinked are left out. These links are logged as warnings and marked Linked by username (unverified).

Usernames from a provider can change and are not proof of ownership, so only turn this on when your provider controls them, and turn it off after migrating. Anyone who gets a matching username at the provider is linked to that account, although they only get their SSO role and none of its local credentials. Such a mix-up keeps the real owner's identity out until an administrator removes the link.

When the Web UI runs in Docker, add the Web UI container's source IP or, preferably, its Docker network CIDR to CrowdSec's /etc/crowdsec/config.yaml. This is not the browser's IP or the Docker host's public IP. Without this entry, decision operations can still work while alert deletion fails with 403 Forbidden.

api:
  server:
    trusted_ips:
      - 127.0.0.1
      - ::1
      - 172.16.0.0/12  # Docker default bridge network

Use the narrowest CIDR that contains the Web UI container and LAPI network. Container IPs can change when containers are recreated, so the Docker network CIDR is usually more reliable than one container IP. Restart CrowdSec after updating the file. The current CrowdSec container does not provide a TRUSTED_IPS environment override. See the CrowdSec configuration reference.

A self-signed certificate or internal CA may produce the following error.

Login failed: unable to get local issuer certificate

Mount the CA certificate and configure it for the LAPI instance.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    container_name: crowdsec_web_ui
    ports:
      - "3000:3000"
    environment:
      CONFIG_INSTANCE_LAPI_URL: https://crowdsec:8080
      CONFIG_INSTANCE_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCE_LAPI_AUTH_PASSWORD_FILE: /run/secrets/crowdsec_password
      CONFIG_INSTANCE_LAPI_TLS_CA_FILE: /certs/root_ca.crt
    secrets:
      - crowdsec_password
    volumes:
      - ./data:/app/data
      - /path/on/host/root_ca.crt:/certs/root_ca.crt:ro
    restart: unless-stopped

secrets:
  crowdsec_password:
    file: ./secrets/crowdsec_password.txt

Keep the CA mount read-only. CONFIG_INSTANCE_LAPI_TLS_CA_FILE maps to instances[0].lapi.tls.caFile; no image rebuild is needed.

CrowdSec Web UI listens for HTTP on port 3000 and does not obtain or terminate TLS certificates itself. Put a reverse proxy in front of it for HTTPS deployments and keep port 3000 private to the proxy.

HTTPS is required for passkeys because browsers expose WebAuthn only in a secure context. http://localhost is suitable for local testing, but a remote deployment needs a stable hostname and a certificate trusted by the browser. Passkeys registered for one hostname cannot be used from a different hostname.

The proxy must preserve Host (or set X-Forwarded-Host) and set X-Forwarded-Proto to the original scheme. The application uses these headers for WebAuthn origins, secure session cookies, OIDC callback URLs, and mutation-origin checks.

This minimal example assumes Traefik already has a websecure entrypoint, a Let's Encrypt resolver named letsencrypt, and an external Docker network named proxy. Add the labels and proxy network to the existing Web UI service, replacing the hostname and CrowdSec settings.

services:
  crowdsec-web-ui:
    image: ghcr.io/theduffman85/crowdsec-web-ui:latest
    expose:
      - "3000"
    environment:
      CONFIG_INSTANCE_LAPI_URL: http://crowdsec:8080
      CONFIG_INSTANCE_LAPI_AUTH_USERNAME: crowdsec-web-ui
      CONFIG_INSTANCE_LAPI_AUTH_PASSWORD: your-crowdsec-password
      # For https://crowdsec.example.com/crowdsec/:
      # CONFIG_SERVER_BASE_PATH: /crowdsec
    volumes:
      - ./data:/app/data
    labels:
      - traefik.enable=true
      - traefik.docker.network=proxy
      # For /crowdsec/, append: && PathPrefix(`/crowdsec`)
      - 'traefik.http.routers.crowdsec-web-ui.rule=Host(`crowdsec.example.com`)'
      - traefik.http.routers.crowdsec-web-ui.entrypoints=websecure
      - traefik.http.routers.crowdsec-web-ui.tls.certresolver=letsencrypt
      - traefik.http.services.crowdsec-web-ui.loadbalancer.server.port=3000
    networks:
      - proxy
      - crowdsec
    restart: unless-stopped

networks:
  proxy:
    external: true
  crowdsec:
    external: true
    name: your_crowdsec_network

Traefik supplies the forwarded headers and WebSocket upgrade handling automatically. See the Traefik ACME documentation if the letsencrypt resolver is not configured yet.

This equivalent example assumes Nginx already terminates HTTPS and the Web UI port is published only on loopback, for example 127.0.0.1:3000:3000.

# For https://crowdsec.example.com/crowdsec/, set
# CONFIG_SERVER_BASE_PATH=/crowdsec and replace both `/` paths below
# with `/crowdsec/`.
location / {
    proxy_pass http://localhost:3000/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

• The base path starts with / and has no trailing slash.
• / redirects to it; APIs, assets, and navigation follow it automatically.
• With Traefik on a shared hostname, add CONFIG_SERVER_BASE_PATH: /crowdsec and use a router rule such as Host(`example.com`) && PathPrefix(`/crowdsec`). Do not configure StripPrefix; the application expects to receive the base path.
• The backend checks browser mutation origins, applies a Content Security Policy, limits API bodies to 1 MiB, and marks API responses private, no-store.
• Command-line and service clients without browser Origin and Sec-Fetch-Site headers remain compatible.
• Configure HSTS at the TLS-terminating proxy; the application does not emit it.

The public endpoint is GET /api/health. Startup does not wait for LAPI: bootstrap retries in the background, so the container can become healthy before synchronization completes.

curl http://localhost:3000/api/health
# {"status":"ok"}

The built-in check runs every 30 seconds with a five-second timeout, a 10-second start period, and three retries.

docker inspect --format='{{.State.Health.Status}}' crowdsec_web_ui

server.basePath does not affect the internal check at localhost:3000/api/health. If server.port changes, update the health-check command and port mapping.

• Reads a configured raw CrowdSec Prometheus endpoint. The Web UI does not configure one by default; CrowdSec normally exposes its local scrape at http://127.0.0.1:6060/metrics.
• Shows remediation-component and log-processor LAPI activity, AppSec, parsers and datasources, scenarios, LAPI latency, parsing time, and whitelist hits. Log-processor activity uses POST /v1/alerts; CrowdSec builds that expose an exact last-heartbeat timestamp also provide the processor health badge.
• When the current instance scope has multiple endpoints, Combined is selected by default. Headline totals sum successful sources, detailed rows retain their instance and endpoint, and unavailable endpoints produce a partial-data warning instead of hiding healthy sources.
• Combined counters are cumulative across processes that may have different start times. Configuring the same Prometheus scrape more than once counts it more than once; endpoint roles and automatic duplicate detection are not applied.
• Alert and decision analytics remain on the main dashboard.

Enable full metrics in CrowdSec's /etc/crowdsec/config.yaml.

prometheus:
  enabled: true
  level: full
  listen_addr: 127.0.0.1
  listen_port: 6060

For separate containers, bind listen_addr: 0.0.0.0 on a trusted network, then configure the matching Web UI instance.

environment:
  CONFIG_INSTANCE_METRICS_URL: http://crowdsec:6060/metrics

AppSec and latency sections appear only when CrowdSec emits those metrics. Time-window-only rate()/increase() metrics are intentionally omitted. See the CrowdSec Prometheus documentation.

• crowdsec.simulationsEnabled: true fetches non-remediating simulation alerts/decisions and shows badges, filters, and dashboard counts. Default: false.
• Alerts and Decisions column layouts persist per browser profile in local storage.
• Drag the edge of a column header on Alerts or Decisions to resize the column, with the mouse or by touch. Double-click or double-tap the edge to fit the content. With the edge focused, the arrow keys resize the column and Enter fits it. Reset widths in the Table columns dialog returns to the automatic widths.
• ID, Machine, and Origin are hidden by default. Machine prefers machine_alias, then machine_id; multiple alert decision origins display as Mixed.
• Hidden columns remain searchable through fields such as id:, machine:, and origin:.
• Grouped by IP on the Alerts page shows one row per attacking IP session. Alerts from an IP stay in one session until there is a gap of more than 30 minutes. Select a row to expand the session's alerts below it. Delete Session removes every alert in the session that matches the current search, along with their linked decisions. The choice persists per browser profile in local storage.
• On screens at least 1024 px wide, the expanded or collapsed sidebar persists per browser profile. On smaller screens the sidebar is a drawer that always starts closed.

Administrators can replace the application name, logo, and colors from Settings > Branding. The name is used in the sidebar, browser tab title, web app manifest, sign-in and setup pages, TOTP issuer, passkey relying-party name, test and application update notifications, and the {{event.app_name}} webhook template variable. The logo replaces the sidebar, sign-in, and setup logos as well as the browser favicon and home screen icon.

• Names are limited to 60 characters; leave the field empty to restore CrowdSec Web UI.
• Logos may be PNG, JPEG, GIF, WebP, or SVG images up to 512 KB. The image type is detected from the file content, and SVG logos are served with a sandboxed Content Security Policy.
• An optional dark mode logo replaces the sidebar, sign-in, and setup logos while the dark theme is active. Without one, the main logo is used in both themes. The favicon and home screen icon always use the main logo.
• Colors can be set separately for light and dark mode: an accent color, from which the full accent palette is generated, and a neutral tone (gray, slate, zinc, neutral, or stone) for backgrounds, borders, and text. Dark mode uses the light mode colors unless it has its own. Status colors such as red for bans stay unchanged. The settings page previews both modes and warns when the accent has low contrast.
• The server injects the branded title, icons, and colors into the page shell, so the page is branded before JavaScript loads.
• Branding is stored in the application database and requires admin mode to change.

Dashboard, Alerts, and Decisions share one count-aware Quick Filters drawer. Its trigger shows the number of active selections, and the clear control in the drawer header resets all stored quick filters.

Instance and machine options use stable IDs for filtering while displaying their configured names or aliases. Country, instance, and machine searches match the displayed label as well as the stored value. Alerts with several origins or targets contribute to each distinct facet option instead of exposing a combined bucket.

• Filter selections, date range, and simulation mode persist in local storage for the current browser profile and are restored when navigating between the three pages.
• Changing a structured search field updates the matching quick-filter selection, and changing a quick filter updates the structured search. A field supplied explicitly in a page URL takes precedence over its stored value; stored values fill fields that are absent.
• Dashboard top countries, scenarios, AS numbers, targets, the world map, and the Activity History range update the same shared state. Changes made in the drawer update those widgets in return.
• Filtered Dashboard alert and active-decision counts use the same indexed predicates as the Alerts and Decisions lists. The alert card links with the alert-compatible query, while the decision card links with the decision-compatible query.
• The drawer follows each table's configured column order. Filters for hidden columns are grouped under Hidden columns.
• Page-only filters remain visible under Unavailable when another page cannot apply them. Alerts lists Action, Status, and Alert there; Decisions lists Decision; Dashboard lists all four. Their stored selections are preserved for the page that supports them and can be cleared from any drawer.
• Facet selections use exact equality. Selecting the target tausend.me generates target=tausend.me and does not include bw.tausend.me. Manually entering target:tausend.me remains a broader contains search.
• Each facet reports counts after the other active filters have been applied. Use the facet search control to find values beyond the initially loaded list.

Dashboard applies the shared fields Country, Scenario, Kind, AS, IP / Range, Target, ID, Instance, Region, City, Machine, and Origin. Filters that depend on decision-only or alert-list-only data are retained in Unavailable instead of being silently discarded.

Active decisions are deduplicated by instance, value, and simulation mode. When filters exclude the globally preferred decision, the best matching decision is promoted so enabling Hide duplicates cannot make an otherwise matching duplicate group disappear.

Use the bookmark button beside search on Dashboard, Alerts, or Decisions to save the current valid query under a name. The menu lets you apply, rename, and delete saved filters, reuse the five most recently used queries, or clear recent history. Queries are shared across these pages; Apply is disabled when a query is not valid for the current page. Applying one changes the search query while keeping the selected instance and other page settings.

Saved filters and recent history are stored on the server for the signed-in user, so they are available on other devices. Read-only users can manage their own filters. If authentication is disabled, everyone using the installation shares one list. Valid nonempty queries enter recent history after a brief pause, including searches opened from bookmarked URLs. Quick Filter queries enter recent history only after the Quick Filters drawer closes.

The : operator performs a case-insensitive contains match, while = matches the complete field value. Quick Filter selections use =. Date fields support <, >, <=, >=, and =>. A bare field name is free text unless followed by :. Quote literal AND, OR, or NOT. The search Info button lists page-specific fields and examples.

Limit the local cache by origin when CrowdSec ingests automation, blocklists, or community feeds.

crowdsec:
  alertFilters:
    includeOrigins: [crowdsec, cscli-import]
    excludeOrigins: [cscli]
    includeCapi: true
    includeOriginEmpty: true
    excludeOriginEmpty: false

• No explicit filters fetches the normal non-CAPI/non-lists feed.
• Includes are pushed upstream where possible. Generic excludes and empty-origin handling run locally because LAPI lacks those filters.
• includeCapi: true adds CAPI to the default feed; includeOrigins: [CAPI] selects only CAPI.
• If any origin is excluded, the whole alert is dropped.
• Origins prefer associated decisions, then blocklist/list source scopes for alerts without decisions.
• includeOriginEmpty retains origin-less alerts alongside includes; excludeOriginEmpty removes them.
• Because Decisions is built from synchronized alerts, filters also change which imported decisions appear.

Rules run against locally cached CrowdSec data, create in-app notifications, record delivery status, and optionally deliver outbound messages.

Every rule has a name, severity (info, warning, critical), incident deduplication, and destination channels. Alert rules filter scenario, target, and simulation state; the scenario filter can include or exclude matching names. IP Ban and New Alert/Decision also accept exact IP/CIDR filters. Window Minutes sets the rolling lookback for each rule evaluation; Alert Spike also compares it with the preceding period of equal length. It does not set how often rules are evaluated.

Instance-backed titles and metadata identify the contributing instance or instances.

Destinations are independently enabled and reusable across rules. Send Test validates saved settings immediately; results are stored as delivered or failed.

• MQTT JSON contains title, message, severity, metadata, sent_at, channel_id, channel_name, channel_type, rule_id, rule_name, and rule_type. Tests use rule_id=test, rule_name=Test notification, and rule_type=test.
• Webhook templates expose dotted event.* fields for title, message, severity, metadata, sent_at, channel_name, rule_id, rule_name, rule_type, and app_name (the configured branding name). Each has a *Json variant; nullable rule fields also have OrUnknown and OrUnknownJson aliases.
• Failed webhooks store HTTP status and a truncated response. notifications.debugPayloads: true also logs a truncated rendered body with sensitive form fields redacted; enable it only while troubleshooting.
• Destination secrets are masked and encrypted by notifications.secretKey, or an auto-generated key stored in state.db.
• notifications.allowPrivateAddresses: false blocks private, loopback, and link-local destinations; default: true. Hostnames are checked when the connection is made, so a DNS change cannot point a destination at a blocked address. IPv4 addresses embedded in IPv6 forms (for example ::ffff:7f00:1) are blocked like their IPv4 equivalents.
• Apprise, Gotify, and ntfy follow only same-origin 307/308 redirects, and each redirect target is checked again.
• Telegram is not supported natively; use Apprise to reach it. Home Assistant discovery/state and inbound MQTT commands are not supported.

A Helm chart for CrowdSec Web UI is maintained by zekker6.

Application state, cached alert details, and optional historical statistics use separate SQLite files:

Mount the directories, not single files: WAL mode also uses cache.db-wal / cache.db-shm and, when statistics are enabled, statistics.db-wal / statistics.db-shm. Stop the application before copying database files for a backup, or use SQLite’s online backup API. Back up statistics.db alongside state.db and config.yaml; completed statistics cannot be rebuilt after the underlying LAPI history expires.

volumes:
  - ./data:/app/data

To keep the cache on fast node-local storage while state.db and config.yaml stay on backed-up or network storage, set storage.cacheDir to a separate mount. The container only fixes ownership of /app/data, so a cache mount elsewhere must be writable by the container user. state.db uses a rollback journal and is written rarely, so it works on network filesystems that do not support WAL.

Upgrading from a version that used a single crowdsec.db copies its durable data into state.db on the first start and then deletes crowdsec.db. Cached alerts and decisions are not copied; the first start runs a full synchronization of crowdsec.sync.lookback. Back up the data directory before upgrading. Older versions cannot read the new files.

• History survives restarts, merges with new LAPI data, and expires after crowdsec.sync.lookback (default: seven days).
• Initial imports and reconciliation retry in smaller windows after timeouts.
• During LAPI outages, the application serves its available cache and retries in the background; partial imports are marked.

Use POST /api/cache/clear for a full cache reset. Synchronization internals are documented in DEVELOPMENT.md.

New installations collect statistics by default. Installations that existed before this feature keep it off until you enable it under Settings → General → Statistics, or configure:

statistics:
  enabled: true
  retentionDays: 90
  jobInterval: 1h
  jobTimeBudget: 30s

Explicit YAML and environment settings lock the corresponding Settings controls. Other changes persist in state.db and apply without a restart.

The Statistics page ranks attacking IPs, attacked machines and known targets. Rankings include unique IPs, linked bans, scenarios, country and ASN, activity dates, and targeted machines. Top Targets shows alert counts and unique source IPs for each target. Target information is available for alerts archived after target collection was added.

• Findings flag quiet machines, scenarios without bans, AppSec blocks, IPs that return after a ban, traffic spikes by machine, new attack types, dominant networks, and IPs that target several machines. Up to five findings appear initially, with warnings first. Expand a finding to see the IPs involved, the address ranges (/24 or /64) of a dominant AS, or a machine's recent activity. IP and range tables start with 25 rows and can expand to 500. With enforcement permissions, Ban and Block range open the decision dialog for one value. Ban all and Block all apply the same decision to every listed value, skipping allowlisted values unless you bypass the allowlist. Top IPs also offer the single-IP action.
• Summary tiles show alerts, unique IPs (and how many were never seen before), bans, ban coverage (the share of attacking IPs that were banned), recurring IPs, and IPs that returned after a ban. Most tiles compare their totals with the preceding period of equal length.
• Scenarios show alerts with their trend, unique IPs, machines, bans and ban coverage per scenario; select one to filter the whole page by it.
• Top countries and AS include their number of distinct IPs, which tells one noisy host from a botnet. Machine changes show increases and machines that went quiet.

Choose individual/all instances, live/simulation mode, Top 10/20/50, calendar presets or custom dates. Dates use UTC; Today is a partial day, not a rolling 24-hour window. Ranges within today and yesterday chart activity by hour, longer or older ranges by day. Comparisons and new-IP counts are only shown when the preceding period is fully covered.

Counts represent the first captured observation. Deleting alerts or expiring decisions does not subtract history. Each distinct decision counts once, even when its expiry is extended. Ranking bans are linked to alerts dated in the selected period; issuance charts use the decision’s own creation date. Missing addresses and network ranges do not count as unique attacking IPs. Counts only cover alerts and decisions imported by the existing sync filters.

Collection starts with available cached data; it does not fetch additional history from CrowdSec. A transactional queue preserves observations until a separate, lower-priority worker consolidates them in batches of up to 500. HTTP reads use a separate statistics query worker and never trigger collection. Coverage and backlog indicators identify incomplete periods; chart gaps are not treated as zero attacks. Investigation links show alert details only while those details remain in the normal cache.

Statistics survive cache resets. Disabling collection finishes pending observations and keeps existing summaries until expiry; enabling it again backfills available cached records. Reducing retention permanently removes older summaries and deduplication identities. Queries enforce retention immediately. Expired data is pruned in bounded batches once per UTC day and after retention changes, including while collection is disabled. Restarts resume an unfinished backfill instead of rescanning the cache. Records dated up to one day ahead of the server clock are kept on their own date; anything further ahead is ignored. Processed observation payloads are discarded. Only compact aggregate relationships, timestamps, counts, hourly histograms and deduplication identities remain; alert bodies, events and search indexes are not archived. Exact IP statistics still grow with distinct IP/machine/scenario relationships.

For data directories on filesystems without SQLite WAL support, set storage.walEnabled: false; this also applies to statistics.db. Statistics storage uses incremental vacuum when enabled at database creation. Never delete statistics.db as part of a cache rebuild.

Run pnpm loadtest:benchmark:statistics for an isolated A/B comparison of capture overhead, foreground request p95 during consolidation, historical query time, and storage size with repeated and high-cardinality attacker data. Temporary benchmark data never uses the configured application directory. STATISTICS_BENCHMARK_RECORDS, STATISTICS_BENCHMARK_RUNS, and STATISTICS_BENCHMARK_SAMPLES control its size; changes above 5% are an investigation gate, not a guarantee across deployment hardware.

cache.db uses SQLite incremental auto-vacuum by default and reclaims free pages while idle. A cache created with storage.incrementalVacuumEnabled: false keeps that format. If startup reports reclaimable space, stop CrowdSec Web UI, delete cache.db, cache.db-wal, and cache.db-shm, and start it again. The cache is recreated with incremental auto-vacuum and refilled by a full synchronization.

Linux Update Dashboard A self-hosted dashboard for checking and applying Linux package updates across multiple servers.