Open-WebUI Service

Table of Contents

Features
Usage
Integration with OLLAMA
Backup
Options Reference

Defined in /modules/blocks/open-webui.nix, found in the selfhostblocks.nixosModules.open-webui module. See the manual for how to import the module in your code.

This service sets up Open WebUI which provides a frontend to various LLMs.

Features

  • Telemetry disabled.

  • Skip onboarding.

  • Declarative LDAP Configuration. Needed LDAP groups are created automatically.

  • Declarative SSO Configuration. When SSO is enabled, login with user and password is disabled. Registration is enabled through SSO.

  • Access through subdomain using reverse proxy.

  • Access through HTTPS using reverse proxy.

  • Backup through the backup block.

Usage

The following snippet assumes a few blocks have been setup already:

{
  shb.open-webui = {
    enable = true;
    domain = "example.com";
    subdomain = "open-webui";

    ssl = config.shb.certs.certs.letsencrypt.${domain};

    sso = {
      enable = true;
      authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";

      sharedSecret.result = config.shb.sops.secret.oidcSecret.result;
      sharedSecretForAuthelia.result = config.shb.sops.secret.oidcAutheliaSecret.result;
    };
  };

  shb.sops.secret.oidcSecret.request = config.shb.open-webui.sso.sharedSecret.request;
  shb.sops.secret.oidcAutheliaSecret.request = config.shb.open-webui.sso.sharedSecretForAuthelia.request;
}

Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.

The user and admin LDAP groups are created automatically.

Integration with OLLAMA

Assuming ollama is enabled, it will be available on port config.services.ollama.port. The following snippet sets up acceleration using an AMD (i)GPU and loads some models.

{
  services.ollama = {
    enable = true;

    # https://wiki.nixos.org/wiki/Ollama#AMD_GPU_with_open_source_driver
    acceleration = "rocm";

    # https://ollama.com/library
    loadModels = [
      "deepseek-r1:1.5b"
      "llama3.2:3b"
      "llava:7b"
      "mxbai-embed-large:335m"
      "nomic-embed-text:v1.5"
    ];
  };
}

Integrating with the ollama service is done with:

{
  services.open-webui = {
    environment.OLLAMA_BASE_URL = "http://127.0.0.1:${toString config.services.ollama.port}";
  };
}

Notice we’re using the upstream service here services.open-webui, not shb.open-webui.

Backup

Backing up Open-Webui using the Restic block is done like so:

shb.restic.instances."open-webui" = {
  request = config.shb.open-webui.backup;
  settings = {
    enable = true;
  };
};

The name "open-webui" in the instances can be anything. The config.shb.open-webui.backup option provides what directories to backup. You can define any number of Restic instances to backup Open WebUI multiple times.

Options Reference

shb.open-webui.enable

Whether to enable the Open-WebUI service.

Type: boolean

Default: false

Example: true

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup

Backup state directory.

Type: submodule

Default: { }

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request

Request part of the backup contract.

Options set by the requester module enforcing how to backup files.

Type: submodule

Default: { user = open-webui; sourceDirectories = [ config.services.open-webui.stateDir ]; excludePatterns = [ ]; hooks.beforeBackup = [ ]; hooks.afterBackup = [ ]; };

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request.excludePatterns

File patterns to exclude.

Type: list of string

Default: [ ]

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request.hooks

Hooks to run around the backup.

Type: submodule

Default: { }

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request.hooks.afterBackup

Hooks to run after backup.

Type: list of string

Default: [ ]

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request.hooks.beforeBackup

Hooks to run before backup.

Type: list of string

Default: [ ]

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request.sourceDirectories

Directories to backup.

Type: non-empty (list of string)

Default: [ config.services.open-webui.stateDir ]

Example: "/var/lib/vaultwarden"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.request.user

Unix user doing the backups.

Type: string

Default: "open-webui"

Example: "vaultwarden"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.result

Result part of the backup contract.

Options set by the provider module that indicates the name of the backup and restor scripts.

Type: submodule

Default: ""

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.result.backupService

Name of service backing up the database.

This script can be ran manually to backup the database:

$ systemctl start backup.service

Type: string

Default: "backup.service"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.backup.result.restoreScript

Name of script that can restore the database. One can then list snapshots with:

$ restore snapshots

And restore the database with:

$ restore restore latest

Type: string

Default: "restore"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.domain

domain under which Open-WebUI will be served.

Type: string

Example: "mydomain.com"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.environment

Extra environment variables. See https://docs.openwebui.com/getting-started/env-configuration

Type: attribute set of string

Example:

''
  {
    WEBUI_NAME = "SelfHostBlocks";
  
    OLLAMA_BASE_URL = "http://127.0.0.1:''${toString config.services.ollama.port}";
    RAG_EMBEDDING_MODEL = "nomic-embed-text:v1.5";
  
    ENABLE_OPENAI_API = "True";
    OPENAI_API_BASE_URL = "http://127.0.0.1:''${toString config.services.llama-cpp.port}";
    ENABLE_WEB_SEARCH = "True";
    RAG_EMBEDDING_ENGINE = "openai";
  }
''

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ldap

Setup LDAP integration.

Type: submodule

Default: { }

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ldap.adminGroup

Group users must belong to to have administrator privileges.

Type: string

Default: "open-webui_admin"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ldap.userGroup

Group users must belong to to be able to login.

Type: string

Default: "open-webui_user"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.port

Port Open-WebUI listens to incoming requests.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default: 12444

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ssl

Path to SSL files

Type: null or (anything)

Default: null

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ssl.paths

Paths where the files for the certificate will be located.

This option is the contract output of the shb.certs.certs SSL block.

Type: anything

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ssl.paths.cert

Path to the cert file.

Type: absolute path

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ssl.paths.key

Path to the key file.

Type: absolute path

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.ssl.systemdService

Systemd oneshot service used to generate the certificate. Ends with the .service suffix.

Use this if downstream services must wait for the certificates to be generated before starting.

Type: string

Example: "cert-generator.service"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso

Setup SSO integration.

Type: submodule

Default: { }

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.enable

Whether to enable SSO integration…

Type: boolean

Default: false

Example: true

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.authEndpoint

Endpoint to the SSO provider. Leave null to not have SSO configured.

Type: null or string

Default: null

Example: "https://authelia.example.com"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.authorization_policy

Require one factor (password) or two factor (device) authentication.

Type: one of “one_factor”, “two_factor”

Default: "one_factor"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.clientID

Client ID for the OIDC endpoint.

Type: string

Default: "open-webui"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret

OIDC shared secret for Open-WebUI.

Type: submodule

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.request

Request part of the secret contract.

Options set by the requester module enforcing some properties the secret should have.

Type: submodule

Default: ""

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.request.group

Linux group owning the secret file.

Type: string

Default: "root"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.request.mode

Mode of the secret file.

Type: string

Default: "0400"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.request.owner

Linux user owning the secret file.

Type: string

Default: "open-webui"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.request.restartUnits

Systemd units to restart after the secret is updated.

Type: list of string

Default:

[
  "open-webui.service"
]

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.result

Result part of the secret contract.

Options set by the provider module that indicates where the secret can be found.

Type: submodule

Default:

{
  path = "/run/secrets/secret";
}

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecret.result.path

Path to the file containing the secret generated out of band.

This path will exist after deploying to a target host, it is not available through the nix store.

Type: absolute path

Default: "/run/secrets/secret"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia

OIDC shared secret for Authelia. Must be the same as sharedSecret

Type: submodule

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.request

Request part of the secret contract.

Options set by the requester module enforcing some properties the secret should have.

Type: submodule

Default: { mode = 0400; owner = config.shb.authelia.autheliaUser; group = root; restartUnits = [ ]; }

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.request.group

Linux group owning the secret file.

Type: string

Default: "root"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.request.mode

Mode of the secret file.

Type: string

Default: "0400"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.request.owner

Linux user owning the secret file.

Type: string

Default: config.shb.authelia.autheliaUser

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.request.restartUnits

Systemd units to restart after the secret is updated.

Type: list of string

Default: [ ]

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.result

Result part of the secret contract.

Options set by the provider module that indicates where the secret can be found.

Type: submodule

Default:

{
  path = "/run/secrets/secret";
}

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.sso.sharedSecretForAuthelia.result.path

Path to the file containing the secret generated out of band.

This path will exist after deploying to a target host, it is not available through the nix store.

Type: absolute path

Default: "/run/secrets/secret"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>
shb.open-webui.subdomain

Subdomain under which Open-WebUI will be served.

Type: string

Default: "open-webui"

Declared by:

<selfhostblocks/modules/services/open-webui.nix>