Database Configuration

This article will detail configuration of the Logship database.

The database is the backbone of any logship deployment. Configuration is specified between the database and backend sections, each providing configurable services with a wide range of capabilities.

You can find an example configuration here or in the logship deployments repository on GitHub.

Database Configuration

Example

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "agent": {
    "udpMetricsEndpoint": "host.docker.internal:49999"
  },
  "database": {
    "enable": true,
    "master": {
      "enable": true
    },
    "endpoints": {
      "worker": ["net.tcp://0.0.0.0:6000"],
      "master": ["net.tcp://127.0.0.1:6000"]
    },
    "services": {
      "keyvalue": {
        "enable": true,
        "dataPath": "/logship/kvs"
      },
      "transactionManager": {
        "enable": true
      },
      "transactionLog": {
        "enable": true,
        "disk": {
          "enable": true,
          "path": "/logship/tlog"
        },
        "memory": {
          "enable": false
        }
      },
      "gateway": {
        "enable": true
      },
      "partitionManager": {
        "enable": true
      }
    }
  },
  "backend": {
    "enable": true,
    "endpoints": {
      "worker": ["net.tcp://0.0.0.0:6002"],
      "master": ["net.tcp://127.0.0.1:6002"]
    },
    "database": {
      "worker": ["net.tcp://127.0.0.1:6000"],
      "master": ["net.tcp://127.0.0.1:6000"]
    },
    "services": {
      "databaseService": {
        "enable": true,
        "sqlite": {
          "enable": true,
          "fileName": "sqlite.db"
        }
      },
      "schemaManager": {
        "enable": true
      },
      "configService": {
        "enable": true
      },
      "inflowService": {
        "enable": true
      },
      "collectorService": {
        "enable": true,
        "tempPath": "/logship/tmp/"
      },
      "searchExecutorService": {
        "enable": true,
        "dataPath": "/logship/searchdata/",
        "minimumFreeSpaceBytes": 5368709120,
        "minimumFreeSpacePercentage": 15.0
      },
      "searchQueryService": {
        "enable": true
      },
      "accountsService": {
        "enable": true,
        "jwt": {
          "enable": true,
          "issuer": "logship-example",
          "audience": "logship-example",
          "signingKey": "this is a secret signing key for locally-signed JWT tokens"
        },
        "oauth": {
          "enable": false
        }
      },
      "messengerService": {
        "enable": true
      },
      "dashboardService": {
        "enable": true
      },
      "evaluatorManagerService": {
        "enable": true
      },
      "evaluatorRunnerService": {
        "enable": true
      },
      "setupService": {
        "enable": true,
        "provision": true,
        "accounts": [
          {
            "accountId": "00000000-0000-0000-0000-000000000000",
            "accountName": "Default Account"
          }
        ],
        "users": [
          {
            "userId": "00000000-0000-0000-0000-00000000cafe",
            "username": "admin",
            "password": "admin",
            "firstname": "Logship",
            "lastname": "Admin",
            "email": "admin@logship.io",
            "defaultGlobalPermissions": ["Logship.Global.Admin"],
            "defaultAccounts": [
              {
                "accountName": "Default Account",
                "userPermissions": ["Logship.Account.Admin"]
              }
            ]
          }
        ]
      }
    },
    "master": {
      "enable": true
    }
  }
}

Config validation can be ignored for services with enable: false.

Production defaults

Pin explicit image tags (e.g., ghcr.io/logship-io/logship-database:0.8.0) and roll forward deliberately.
Persist /logship on SSD/NVMe; separate data/log volumes when possible.
Keep minimumFreeSpaceBytes above 5 GB and minimumFreeSpacePercentage above 15% to avoid throttling.
Run distinct masters for backend and database on separate nodes when scaling horizontally.
Secure endpoints with network ACLs and TLS offload (via reverse proxy) where required.

Logging

See .NET Logging Configuration for more information.

LogLevel

Property	Type	Required	Description
Default	String	Yes	Specifies the default log level.
Microsoft.Hosting.Lifetime	String	Yes	Specifies the log level for Microsoft.Hosting.Lifetime.

agent

Property	Type	Required	Description
udpMetricsEndpoint	String	Yes	Specifies the UDP metrics endpoint.

database

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the database.
master	Boolean	Yes	Enables or disables the master database.
endpoints	Object	Yes	Defines endpoints for worker and master.
services	Object	Yes	Defines various database services.

endpoints

worker

Value	Type	Required	Description
	String[]	Yes	Specifies the worker endpoints.

master

Value	Type	Required	Description
	String[]	Yes	Specifies the master endpoints.

services

keyvalue

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the keyvalue service.
dataPath	String	Yes	Specifies the data path for keyvalue service.

transactionManager

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the transaction manager service.

transactionLog

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the transaction log service.
disk	Object	Yes	Defines disk settings for the transaction log service.
memory	Object	Yes	Defines memory settings for the transaction log service.

disk

Property	Type	Required	Description
enable	Boolean	No	Enables or disables disk storage for the transaction log.
path	String	Yes	Specifies the path for disk storage of the transaction log.

memory

Property	Type	Required	Description
enable	Boolean	No	Enables or disables memory storage for the transaction log.

gateway

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the gateway service.

partitionManager

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the partition manager service.

backend

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the backend service.
endpoints	Object	Yes	Defines endpoints for worker and master.
database	Object	Yes	Defines database settings for worker and master.
services	Object	Yes	Defines various backend services.
master	Boolean	Yes	Enables or disables the master backend service.

endpoints

worker

Value	Type	Required	Description
	String[]	Yes	Specifies the worker endpoints.

master

Value	Type	Required	Description
	String[]	Yes	Specifies the master endpoints.

database

worker

Value	Type	Required	Description
	String[]	Yes	Specifies the worker database endpoint.

master

Value	Type	Required	Description
	String[]	Yes	Specifies the master database endpoint.

services

databaseService

Backing metadata store for accounts, dashboards, alerts, and other relational state.

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the database service.
sqlite	Object	Yes	SQLite backing-store settings.

sqlite

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the SQLite backing store.
fileName	String	Yes	SQLite database file name (under the data root).

schemaManager

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the schema manager.

configService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the config service.

inflowService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the inflow service.

collectorService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the collector service.
tempPath	String	Yes	Specifies the temporary path for the collector service.

searchExecutorService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the search executor service.
dataPath	String	Yes	Specifies the data path for the search executor service.
minimumFreeSpaceBytes	Number	Yes	Specifies the minimum free space in bytes for the search executor service.
minimumFreeSpacePercentage	Number	Yes	Specifies the minimum free space percentage for the search executor service.

searchQueryService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the search query service.

accountsService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the accounts service.
jwt	Object	Yes	Defines JWT settings for the accounts service.
oauth	Object	Yes	Defines OAuth settings for the accounts service.

jwt

Property	Type	Required	Description
enable	Boolean	No	Enables or disables JWT for the accounts service.
issuer	String	Yes	Specifies the issuer for JWT tokens.
audience	String	Yes	Specifies the audience for JWT tokens.
signingKey	String	Yes	Specifies the signing key for JWT tokens.

oauth

All identity-provider connection details (client id, authority, endpoints, issuers, audiences) live on each entry of providers[] — see providers[] below. The oauth object itself holds only the cross-provider settings:

Property	Type	Required	Description
enable	Boolean	No	Enables OAuth/OIDC sign-in for the accounts service.
providers	Object[]	Yes	One or more OIDC providers. At least one must have `enable: true`.
createDefaultUser	Boolean	No	Auto-provision a Logship user when the token does not match one.
defaultUserAccount	String	No	Account id assigned to auto-provisioned users.
requireVerifiedEmail	Boolean	No	Reject tokens that do not assert a verified email. Defaults to `true`.
emailVerifiedClaimType	String	No	Claim that asserts the email is verified. Defaults to `email_verified`.
userIdClaimType	String	No	Claim used as the external subject identifier. Defaults to `sub`.
firstNameClaimType	String	No	Claim used for the user's first name. Defaults to `given_name`.
lastNameClaimType	String	No	Claim used for the user's last name. Defaults to `family_name`.
nickNameClaimType	String	No	Claim used for the user's nickname/display handle. Defaults to `nickname`.
emailClaimType	String	No	Claim used to match or create the Logship username.
claimMappings	Object[]	No	Rules granting Logship permissions based on token claims.

Logship only enables the OAuth bearer scheme when oauth.enable is true. Each enabled provider is exposed through /auth/oauth, rendered as a separate login option in the frontend, and accepted by the backend bearer auth pipeline.

requireVerifiedEmail defaults to true: Logship rejects any token whose emailVerifiedClaimType claim is missing or not true. This prevents account takeover when an IdP issues a token with an unverified, user-settable email/username that collides with an existing Logship user. Only set it to false when the IdP guarantees the identity claim out-of-band.

A plain OAuth 2.0 provider that is not OIDC cannot be used directly. Logship validates an RSA-signed JWT discovered via metadataAddress and requires a verified-email claim. To sign in with such a provider, front it with an OIDC broker (e.g. Keycloak or Dex) and point Logship at the broker.

When a token is accepted, Logship resolves the user from the configured emailClaimType. If the user already exists, Logship signs that user in. If the user does not exist and createDefaultUser is true, Logship creates the user and adds them to defaultUserAccount with a least-privileged Logship.Data.Viewer account permission.

claimMappings[]

Each mapping grants a set of Logship permissions when a token carries a matching claim value. On every login, Logship recomputes the set of granted permissions and syncs the user's global permissions to match: permissions listed in any mapping are considered "managed by SSO" and are added when a rule matches, removed when no rule matches. Permissions not referenced by any mapping are left alone, so permissions assigned through the admin UI are preserved.

Property	Type	Required	Description
claimType	String	Yes	JWT claim to inspect (e.g. `email`, `groups`, `roles`).
values	String[]	Yes	Claim values that trigger this mapping. Comparison is case-insensitive.
permissions	String[]	Yes	Logship permission names to grant. Must be entries from `AuthPermissions`.

"claimMappings": [
  { "claimType": "email",  "values": ["admin@example.com"], "permissions": ["Logship.Global.Admin"] },
  { "claimType": "groups", "values": ["logship-admins"],    "permissions": ["Logship.Global.Admin"] }
]

Permission names must match an entry in Logship's AuthPermissions table (Logship.Global.Admin, Logship.Account.Admin, Logship.Data.Viewer, etc.). Only global-scope permissions (like Logship.Global.Admin) take effect through claim mappings — account-scoped permissions are managed per-account.

providers[]

Use providers when you need multiple SSO or need to accept tokens from more than one OIDC identity provider. Claim-to-role mapping remains shared across all providers. Each provider is disabled by default, so set enable to true for every provider you want Logship to expose and accept.

Property	Type	Required	Description
enable	Boolean	No	Explicitly enables this provider. Defaults to `false`.
id	String	Yes	Stable identifier for the provider. Used by the frontend redirect flow.
displayName	String	No	Friendly label shown on the login button. Defaults to `clientId`/`id`.
clientId	String	Yes	OIDC client id Logship expects in the token audience.
scope	String	Yes	Scope string returned to the frontend for PKCE sign-in.
metadataAddress	String	Yes	OIDC discovery document URL.
authority	String	Yes	Issuer/authority URL for the identity provider.
tokenEndpoint	String	Yes	Token endpoint exposed to the frontend.
authorizeEndpoint	String	Yes	Authorization endpoint exposed to the frontend.
deviceEndpoint	String	Yes	Device authorization endpoint for device code flow clients.
requireHttpsMetadata	Boolean	No	Require HTTPS for discovery and metadata requests.
validIssuers	String[]	Yes	Allowed token issuers for this provider.
validAudiences	String[]	Yes	Allowed token audiences for this provider.

"providers": [
  {
    "enable": true,
    "id": "keycloak-main",
    "displayName": "Keycloak",
    "clientId": "logship-web",
    "scope": "openid profile email",
    "metadataAddress": "https://keycloak.example.com/realms/logship/.well-known/openid-configuration",
    "authority": "https://keycloak.example.com/realms/logship",
    "tokenEndpoint": "https://keycloak.example.com/realms/logship/protocol/openid-connect/token",
    "authorizeEndpoint": "https://keycloak.example.com/realms/logship/protocol/openid-connect/auth",
    "deviceEndpoint": "https://keycloak.example.com/realms/logship/protocol/openid-connect/auth/device",
    "requireHttpsMetadata": true,
    "validIssuers": ["https://keycloak.example.com/realms/logship"],
    "validAudiences": ["logship-web"]
  },
  {
    "enable": true,
    "id": "entra-prod",
    "displayName": "Microsoft Entra ID",
    "clientId": "11111111-2222-3333-4444-555555555555",
    "scope": "openid profile email",
    "metadataAddress": "https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration",
    "authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
    "tokenEndpoint": "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token",
    "authorizeEndpoint": "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize",
    "deviceEndpoint": "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/devicecode",
    "requireHttpsMetadata": true,
    "validIssuers": ["https://login.microsoftonline.com/<tenant-id>/v2.0"],
    "validAudiences": ["11111111-2222-3333-4444-555555555555"]
  }
]

Keycloak SSO example

{
  "backend": {
    "services": {
      "accountsService": {
        "enable": true,
        "oauth": {
          "enable": true,
          "providers": [
            {
              "enable": true,
              "id": "keycloak-main",
              "displayName": "Keycloak",
              "clientId": "logship-web",
              "scope": "openid profile email",
              "metadataAddress": "https://keycloak.example.com/realms/logship/.well-known/openid-configuration",
              "authority": "https://keycloak.example.com/realms/logship",
              "tokenEndpoint": "https://keycloak.example.com/realms/logship/protocol/openid-connect/token",
              "authorizeEndpoint": "https://keycloak.example.com/realms/logship/protocol/openid-connect/auth",
              "deviceEndpoint": "https://keycloak.example.com/realms/logship/protocol/openid-connect/auth/device",
              "requireHttpsMetadata": true,
              "validIssuers": ["https://keycloak.example.com/realms/logship"],
              "validAudiences": ["logship-web"]
            }
          ],
          "createDefaultUser": true,
          "defaultUserAccount": "11111111-1111-1111-1111-111111111111",
          "userIdClaimType": "sub",
          "firstNameClaimType": "given_name",
          "lastNameClaimType": "family_name",
          "nickNameClaimType": "preferred_username",
          "emailClaimType": "email",
          "claimMappings": [
            {
              "claimType": "email",
              "values": ["admin@example.com"],
              "permissions": ["Logship.Global.Admin"]
            },
            {
              "claimType": "groups",
              "values": ["logship-admins"],
              "permissions": ["Logship.Global.Admin"]
            }
          ]
        }
      }
    }
  }
}

For Keycloak:

Create a realm for Logship.
Create a client with client id logship-web.
Allow the redirect URI used by your Logship frontend, including /login/oauth/redirect.
Ensure the issued token includes sub, email, given_name, family_name, and preferred_username claims, or adjust the claim mapping fields above to match your provider.
If you want to grant Logship permissions by group membership, add an oidc-group-membership-mapper to the client (token claim name groups, include in access token) so the access token carries a groups claim you can reference in claimMappings.

messengerService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the messenger service.

dashboardService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the dashboard service.

evaluatorManagerService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the evaluator manager service.

evaluatorRunnerService

Property	Type	Required	Description
enable	Boolean	No	Enables or disables the evaluator runner service.

setupService

The setup service can optionally provision accounts and users on startup (useful for local/dev and automation).

Property	Type	Required	Description
enable	Boolean	Yes	Enables or disables the setup service.
provision	Boolean	Yes	When `true`, provisions configured accounts/users on startup.
accounts	Object[]	No	Accounts to create/ensure exist (when `provision: true`).
users	Object[]	No	Users to create/ensure exist (when `provision: true`).
dashboardProvisioningPath	String	No	Optional path containing dashboard provisioning files.

accounts[]

Property	Type	Required	Description
accountId	String	Yes	Account id to create/ensure exists.
accountName	String	Yes	Human-friendly account name.
override	Boolean	No	Re-provision the account even if it already exists.

users[]

Property	Type	Required	Description
userId	String	Yes	User id to create/ensure exists.
username	String	Yes	Username for password login.
password	String	Yes	Password for password login.
firstname	String	Yes	First name.
lastname	String	Yes	Last name.
email	String	Yes	Email address.
override	Boolean	No	Re-provision the user even if it already exists.
defaultGlobalPermissions	String[]	No	Global permissions granted to the user.
defaultAccounts	Object[]	No	Accounts the user should be added to.

users[].defaultAccounts[]

Property	Type	Required	Description
accountName	String	Yes	The account name to add the user to (must exist in `accounts[]`).
userPermissions	String[]	No	Permissions granted to the user in that account.

master

Property	Type	Required	Description
enable	Boolean	Yes	Enables or disables the master backend service.