Karakeep
Defined in /modules/blocks/karakeep.nix,
found in the selfhostblocks.nixosModules.karakeep module.
See the manual for how to import the module in your code.
This service sets up Karakeep which is a bookmarking service powered by LLMs. It integrates well with Ollama.
Features
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.
Meilisearch configured with production environment and master key.
Access through subdomain using reverse proxy.
Access through HTTPS using reverse proxy.
Backup through the backup block.
Integration with the dashboard contract for displaying user facing application in a dashboard. Manual
Usage
Initial Configuration
The following snippet assumes a few blocks have been setup already:
the secrets block with SOPS,
the
shb.sslblock,the
shb.lldapblock.the
shb.autheliablock.
{
shb.karakeep = {
enable = true;
domain = "example.com";
subdomain = "karakeep";
ssl = config.shb.certs.certs.letsencrypt.${domain};
nextauthSecret.result = config.shb.sops.secret.nextauthSecret.result;
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.nextauthSecret.request = config.shb.karakeep.nextauthSecret.request;
shb.sops.secret."karakeep/oidcSecret".request = config.shb.karakeep.sso.sharedSecret.request;
shb.sops.secret."karakeep/oidcAutheliaSecret" = {
request = config.shb.karakeep.sso.sharedSecretForAuthelia.request;
settings.key = "karakeep/oidcSecret";
};
}
Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.
Application Dashboard
Integration with the dashboard contract is provided by the dashboard option.
For example using the Homepage service:
{
shb.homepage.servicesGroups.Documents.services.Karakeep = {
sortOrder = 3;
dashboard.request = config.shb.karakeep.dashboard.request;
};
}
An API key can be set to show extra info:
{
shb.homepage.servicesGroups.Documents.services.Karakeep = {
apiKey.result = config.shb.sops.secret."karakeep/homepageApiKey".result;
};
shb.sops.secret."karakeep/homepageApiKey".request =
config.shb.homepage.servicesGroups.Documents.services.Karakeep.apiKey.request;
}
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.
Options Reference
-
shb.karakeep.enable -
Whether to enable the Karakeep service.
Type: boolean
Default:
falseExample:
trueDeclared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup -
Backup state directory.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request -
Request part of the backup contract.
Options set by the requester module enforcing how to backup files.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request.excludePatterns -
File patterns to exclude.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request.hooks -
Hooks to run around the backup.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request.hooks.afterBackup -
Hooks to run after backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request.hooks.beforeBackup -
Hooks to run before backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request.sourceDirectories -
Directories to backup.
Type: non-empty (list of string)
Default:
[ "/var/lib/karakeep" ]Example:
"/var/lib/vaultwarden"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.request.user -
Unix user doing the backups.
Type: string
Default:
"karakeep"Example:
"vaultwarden"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.result -
Result part of the backup contract.
Options set by the provider module that indicates the name of the backup and restore scripts.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.result.backupService -
Name of service backing up the database.
This script can be ran manually to backup the database:
$ systemctl start backup.serviceType: string
Default:
"backup.service"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.backup.result.restoreScript -
Name of script that can restore the database. One can then list snapshots with:
$ restore snapshots <snapshot 1> <metadata> <snapshot 2> <metadata>And restore the database with:
$ restore restore <snapshot 1>Type: string
Default:
"restore"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.dashboard -
Dashboard contract consumer
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.dashboard.request -
Request part of the dashboard contract.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.dashboard.request.externalUrl -
URL at which the service can be accessed.
This URL should go through the reverse proxy.
Type: string
Default:
"https://\${config.shb.karakeep.subdomain}.\${config.shb.karakeep.domain}"Example:
"https://jellyfin.example.com"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.dashboard.request.internalUrl -
URL at which the service can be accessed directly.
This URL should bypass the reverse proxy. It can be used for example to ping the service and making sure it is up and running correctly.
Type: null or string
Default:
"http://127.0.0.1:3000"Example:
"http://127.0.0.1:8081"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.dashboard.result -
Result part of the dashboard contract.
No option is provided here.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.domain -
domain under which Karakeep will be served.
Type: string
Example:
"mydomain.com"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.environment -
Extra environment variables. See https://docs.karakeep.app/configuration/
Type: attribute set of string
Default:
{ }Example:
'' { OLLAMA_BASE_URL = "http://127.0.0.1:''${toString config.services.ollama.port}"; INFERENCE_TEXT_MODEL = "deepseek-r1:1.5b"; INFERENCE_IMAGE_MODEL = "llava"; EMBEDDING_TEXT_MODEL = "nomic-embed-text:v1.5"; INFERENCE_ENABLE_AUTO_SUMMARIZATION = "true"; INFERENCE_JOB_TIMEOUT_SEC = "200"; } ''Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ldap -
Setup LDAP integration.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ldap.userGroup -
Group users must belong to to be able to login.
Type: string
Default:
"karakeep_user"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.meilisearchMasterKey -
Master key used to secure communication with Meilisearch.
Type: submodule
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.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/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.request.group -
Linux group owning the secret file.
Type: string
Default:
"root"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.request.mode -
Mode of the secret file.
Type: string
Default:
"0400"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.request.owner -
Linux user owning the secret file.
Type: string
Default:
"karakeep"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.request.restartUnits -
Systemd units to restart after the secret is updated.
Type: list of string
Default:
[ "karakeep-init.service" "karakeep-workers.service" "karakeep-workers.service" ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.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/karakeep.nix> -
shb.karakeep.meilisearchMasterKey.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/karakeep.nix> -
shb.karakeep.nextauthSecret -
NextAuth secret.
Type: submodule
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.nextauthSecret.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/karakeep.nix> -
shb.karakeep.nextauthSecret.request.group -
Linux group owning the secret file.
Type: string
Default:
"root"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.nextauthSecret.request.mode -
Mode of the secret file.
Type: string
Default:
"0400"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.nextauthSecret.request.owner -
Linux user owning the secret file.
Type: string
Default:
"karakeep"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.nextauthSecret.request.restartUnits -
Systemd units to restart after the secret is updated.
Type: list of string
Default:
[ "karakeep-init.service" "karakeep-workers.service" "karakeep-workers.service" ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.nextauthSecret.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/karakeep.nix> -
shb.karakeep.nextauthSecret.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/karakeep.nix> -
shb.karakeep.port -
Port Karakeep listens to incoming requests.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
3000Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ssl -
Path to SSL files
Type: null or (open submodule of anything)
Default:
nullDeclared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ssl.paths -
Paths where the files for the certificate will be located.
This option is the contract output of the
shb.certs.certsSSL block.Type: open submodule of anything
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ssl.paths.cert -
Path to the cert file.
Type: absolute path
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ssl.paths.key -
Path to the key file.
Type: absolute path
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.ssl.systemdService -
Systemd oneshot service used to generate the certificate. Ends with the
.servicesuffix.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/karakeep.nix> -
shb.karakeep.sso -
Setup SSO integration.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.enable -
Whether to enable SSO integration…
Type: boolean
Default:
falseExample:
trueDeclared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.authEndpoint -
Endpoint to the SSO provider.
Type: string
Example:
"https://authelia.example.com"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.sso.clientID -
Client ID for the OIDC endpoint.
Type: string
Default:
"karakeep"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecret -
OIDC shared secret for Karakeep.
Type: submodule
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.sso.sharedSecret.request.group -
Linux group owning the secret file.
Type: string
Default:
"root"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecret.request.mode -
Mode of the secret file.
Type: string
Default:
"0400"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecret.request.owner -
Linux user owning the secret file.
Type: string
Default:
"karakeep"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecret.request.restartUnits -
Systemd units to restart after the secret is updated.
Type: list of string
Default:
[ "karakeep-init.service" "karakeep-workers.service" "karakeep-workers.service" ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.sso.sharedSecretForAuthelia -
OIDC shared secret for Authelia. Must be the same as
sharedSecretType: submodule
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.sso.sharedSecretForAuthelia.request.group -
Linux group owning the secret file.
Type: string
Default:
"root"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecretForAuthelia.request.mode -
Mode of the secret file.
Type: string
Default:
"0400"Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecretForAuthelia.request.owner -
Linux user owning the secret file.
Type: string
Default: config.shb.authelia.autheliaUser
Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.sso.sharedSecretForAuthelia.request.restartUnits -
Systemd units to restart after the secret is updated.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.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/karakeep.nix> -
shb.karakeep.subdomain -
Subdomain under which Karakeep will be served.
Type: string
Default:
"karakeep"Declared by:
<selfhostblocks/modules/services/karakeep.nix>