⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
docs(admin): document instance settings
Tin8cacfa021ce7
diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 1094931f7..8d32fa130 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -98,10 +98,10 @@ only the small `{"type":"ping"}` text keepalive, with a 64-byte message limit.Name | Description | Default |--- | --- | --- |-| `DISABLE_WORKSPACE_CREATION` | Allow only instance administrators to create workspaces. Workspace ownership or a workspace admin role does not grant this instance-wide permission. | `false` |+| `DISABLE_WORKSPACE_CREATION` | Allow only instance administrators to create workspaces. When `true`, the matching [instance setting](/core/operations/administration#instance-settings) is locked. Workspace ownership or a workspace admin role does not grant this instance-wide permission. | `false` || `DISABLE_GUEST_ACCESS` | Disable anonymous/guest sign-in. Guests are also blocked before initial instance setup and when registration, local registration, or the local login form is disabled. | `false` |-| `DISABLE_REGISTRATION` | Disable public user registration. When set to `true`, the sign-up option will not be shown on the sign-in page and new user creation is blocked (including via SSO). **Note:** Invited password signups must present the matching invitation link. OAuth, OTP, and magic-link signups may match an invitation by email only after that email has been verified. Sign-in emails (OTP codes and magic links) are only sent to existing accounts or pending invitations. The first non-guest user can complete initial instance setup. | `false` |-| `DISABLE_PASSWORD_REGISTRATION` | Disable local account creation through password, email OTP, magic link, and guest access. Existing accounts can still use email sign-in unless `DISABLE_LOGIN_FORM=true`. Social/OIDC registration remains available unless `DISABLE_REGISTRATION=true`. The initial administrator can still be created through password signup. | `false` |+| `DISABLE_REGISTRATION` | Disable public user registration. When `true`, the matching [instance setting](/core/operations/administration#instance-settings) is locked; otherwise administrators can close registration there. When set to `true`, the sign-up option will not be shown on the sign-in page and new user creation is blocked (including via SSO). **Note:** Invited password signups must present the matching invitation link. OAuth, OTP, and magic-link signups may match an invitation by email only after that email has been verified. Sign-in emails (OTP codes and magic links) are only sent to existing accounts or pending invitations. The first non-guest user can complete initial instance setup. | `false` |+| `DISABLE_PASSWORD_REGISTRATION` | Disable local account creation through password, email OTP, magic link, and guest access. When `true`, the matching [instance setting](/core/operations/administration#instance-settings) is locked. Existing accounts can still use email sign-in unless `DISABLE_LOGIN_FORM=true`. Social/OIDC registration remains available unless `DISABLE_REGISTRATION=true`. The initial administrator can still be created through password signup. | `false` || `DISABLE_EMAIL_OTP_SIGN_IN` | When SMTP is configured, sign-in uses email verification codes by default. Set to `true` to use email/password sign-in instead. Workspace invitation and password-reset emails still use SMTP. | `false` || `DISABLE_LOGIN_FORM` | Disable local email sign-in and hide the form on the sign-in page. When set to `true`, only SSO/OAuth buttons are shown. Useful when you want to enforce authentication exclusively through an external identity provider. | `false` || `CUSTOM_OAUTH_AUTO_LOGIN` | Automatically redirect to the custom OAuth/OIDC provider instead of showing the sign-in page. When set to `true`, users are immediately redirected to your identity provider without seeing the login page. Requires a custom OAuth provider to be configured. | `false` |diff --git a/apps/docs/core/operations/administration.mdx b/apps/docs/core/operations/administration.mdxindex 9a644f75e..61658c963 100644--- a/apps/docs/core/operations/administration.mdx+++ b/apps/docs/core/operations/administration.mdx@@ -51,9 +51,9 @@ Deleting someone who is the only owner of a workspace that still has other membeChoose **Create user** and enter their name, email, and instance role. You never choose or see their password:- **Password sign-in available:** Kaneo emails them a link to set their own password. The link works once and expires in 2 days. If it expires, or SMTP wasn't configured yet, send a new one with **Send password reset link**.-- **`DISABLE_PASSWORD_REGISTRATION` or `DISABLE_LOGIN_FORM` set:** the account is created for single sign-on. No email is sent, and the email is marked verified so their first sign-in through GitHub, Google, Discord, or your OIDC provider with that address links to it.+- **Password sign-up turned off (in [settings](#instance-settings) or with `DISABLE_PASSWORD_REGISTRATION`), or `DISABLE_LOGIN_FORM` set:** the account is created for single sign-on. No email is sent, and the email is marked verified so their first sign-in through GitHub, Google, Discord, or your OIDC provider with that address links to it.-Administrators can create users even when `DISABLE_REGISTRATION` closes self-service sign-up. An email that already belongs to an account is rejected. On Kaneo Cloud, disposable email addresses are rejected as they are for sign-up.+When no role is chosen, the account gets the [default role](#instance-settings). Administrators can create users even when registration is closed. An email that already belongs to an account is rejected. On Kaneo Cloud, disposable email addresses are rejected as they are for sign-up.## Custom roles@@ -83,7 +83,7 @@ Give someone a role from **Edit** in the user directory. Each person has one rolCreating or renaming a role to a name already stored on users is blocked. Change those users' roles first so they don't gain permissions without an assignment.-Custom roles only grant these administration permissions. Built-in admins can also open every workspace, and some powers stay with them alone: managing roles, editing project access from the workspace page, and creating workspaces when `DISABLE_WORKSPACE_CREATION` is set.+Custom roles only grant these administration permissions. Built-in admins can also open every workspace, and some powers stay with them alone: managing roles, editing project access from the workspace page, and creating workspaces when workspace creation is restricted.Kaneo keeps custom roles from being used to gain more power:@@ -138,6 +138,21 @@ Kaneo keeps audit log entries until you remove them; there's no automatic retentReading the audit log, in the app or through `GET /api/admin/audit-log`, needs the `audit:read` permission and a signed-in session. API keys are rejected.+## Instance settings++Open **Settings → Administration → Settings** to change how the instance behaves. The page and `GET`/`PATCH /api/admin/settings` require the `instance:settings` permission; API keys are rejected. Changes apply right away on the API instance that saved them and within five seconds on the others, without Redis. Each change is recorded in the audit log as **Updated instance settings**, with the old and new value of every setting that changed.++- **Instance name**: replaces "Kaneo" in page titles and in the header and subject of emails. Leave it empty for Kaneo.+- **Instance URL**: shown read-only. It comes from `KANEO_CLIENT_URL`.+- **Open registration**: when off, only people with a valid invitation can create an account, the same as `DISABLE_REGISTRATION=true`.+- **Email and password sign-up**: when off, new accounts must use GitHub, Google, Discord, or your OIDC provider, the same as `DISABLE_PASSWORD_REGISTRATION=true`. Guest access is off while either registration setting is off.+- **Require email verification**: new password sign-ups are emailed a confirmation link and can't sign in with their password until they confirm. Signing in before then sends a new link. Accounts that existed before you turned it on, administrator-created accounts, and accounts from email codes, magic links, or single sign-on are not affected. Needs SMTP.+- **Default role for new users**: the instance role every new account gets, whether it signs up with a password, an email code, or single sign-on, or is created by an administrator without a role. It can be **User** or a custom role, never **Admin**, and you can only choose a role whose permissions you have. A role can't be deleted while it is the default. Guests and the first account on a new instance are not affected.+- **Only administrators can create workspaces**: the same as `DISABLE_WORKSPACE_CREATION=true`.+- **Integrations**: turning a provider off stops its connected projects from syncing, delivering, and handling webhooks, and stops projects from connecting, changing, or importing through it. Projects can still remove an existing connection. Turning it back on resumes the saved connections.++Environment variables win. When `DISABLE_REGISTRATION`, `DISABLE_PASSWORD_REGISTRATION`, or `DISABLE_WORKSPACE_CREATION` is `true`, the matching setting is locked and shows which variable sets it. On a new instance, or one that never saved settings, everything behaves as before this page existed. Sign-in providers are listed on the [System](#check-system-status) page.+## Check system statusOpen **Settings → Administration → System** to check this instance and the services it relies on. The page checks again each time you open it or choose **Refresh**.diff --git a/apps/docs/openapi.json b/apps/docs/openapi.jsonindex 3dbf67d0b..dae21fad5 100644--- a/apps/docs/openapi.json+++ b/apps/docs/openapi.json@@ -602,6 +602,10 @@"isCloud": {"type": "boolean"},+ "instanceName": {+ "type": "string",+ "description": "Name shown in page titles and emails. Defaults to Kaneo."+ },"disableRegistration": {"type": "boolean"},@@ -614,6 +618,13 @@"disableWorkspaceCreation": {"type": "boolean"},+ "disabledIntegrations": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Integration provider types an administrator turned off, such as `slack`."+ },"isDemoMode": {"type": "boolean"},@@ -683,10 +694,12 @@},"required": ["isCloud",+ "instanceName","disableRegistration","disablePasswordRegistration","disableEmailOtpSignIn","disableWorkspaceCreation",+ "disabledIntegrations","isDemoMode","hasSmtp","hasImageUploads",@@ -6607,6 +6620,100 @@"id"]},+ "InstanceSettings": {+ "type": "object",+ "properties": {+ "instanceName": {+ "type": [+ "string",+ "null"+ ],+ "description": "The saved name, or null for the default Kaneo."+ },+ "instanceUrl": {+ "type": [+ "string",+ "null"+ ],+ "description": "The web app URL from `KANEO_CLIENT_URL`. Read-only."+ },+ "registrationEnabled": {+ "type": "boolean"+ },+ "passwordRegistrationEnabled": {+ "type": "boolean"+ },+ "requireEmailVerification": {+ "type": "boolean"+ },+ "defaultRole": {+ "type": "string"+ },+ "workspaceCreationRestricted": {+ "type": "boolean"+ },+ "disabledIntegrations": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "lockedByEnv": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "registrationEnabled",+ "passwordRegistrationEnabled",+ "workspaceCreationRestricted"+ ]+ },+ "description": "Settings an environment variable forces. Their values here are the effective ones."+ },+ "emailDeliveryConfigured": {+ "type": "boolean"+ },+ "roles": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Custom instance roles that can be the default role."+ },+ "integrationProviders": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string"+ },+ "name": {+ "type": "string"+ }+ },+ "required": [+ "type",+ "name"+ ]+ }+ }+ },+ "required": [+ "instanceName",+ "instanceUrl",+ "registrationEnabled",+ "passwordRegistrationEnabled",+ "requireEmailVerification",+ "defaultRole",+ "workspaceCreationRestricted",+ "disabledIntegrations",+ "lockedByEnv",+ "emailDeliveryConfigured",+ "roles",+ "integrationProviders"+ ]+ },"AdminApiKeyList": {"type": "object","properties": {@@ -7260,7 +7367,7 @@"Config"],"summary": "Get config",- "description": "Public instance settings: which sign-in methods, registration paths, and features are enabled.",+ "description": "Public instance settings: the instance name, which sign-in methods, registration paths, integrations, and features are enabled.","security": [],"responses": {"200": {@@ -25515,8 +25622,7 @@"type": "string","minLength": 1,"maxLength": 64,- "default": "user",- "description": "Instance role: `admin` administers the instance, `user` has no instance permissions, or the name of a custom role. Only administrators can assign `admin`, and nobody can assign a role with permissions they don't have."+ "description": "Instance role, as for updates. Defaults to the instance's default role for new users."}},"required": [@@ -27848,6 +27954,164 @@}}},+ "/admin/settings": {+ "get": {+ "operationId": "getInstanceSettings",+ "tags": [+ "Admin"+ ],+ "summary": "Get instance settings",+ "description": "Read the instance-wide settings, which ones an environment variable locks, and the choices for the default role and integrations. Requires the `instance:settings` instance permission; API keys are rejected.",+ "responses": {+ "200": {+ "description": "Instance settings",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/InstanceSettings"+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid credentials",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "403": {+ "description": "The caller lacks the instance permission or used an API key",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ }+ }+ },+ "patch": {+ "operationId": "updateInstanceSettings",+ "tags": [+ "Admin"+ ],+ "summary": "Update instance settings",+ "description": "Change one or more instance-wide settings. Other API instances apply a change within a few seconds. Requires the `instance:settings` instance permission; API keys are rejected.",+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "instanceName": {+ "type": [+ "string",+ "null"+ ],+ "maxLength": 60,+ "description": "Shown in page titles and email headers and subjects. Empty or null restores Kaneo."+ },+ "registrationEnabled": {+ "type": "boolean",+ "description": "When false, only people with a valid invitation can create an account. Locked when `DISABLE_REGISTRATION=true`."+ },+ "passwordRegistrationEnabled": {+ "type": "boolean",+ "description": "When false, new accounts must use a social or OIDC provider. Locked when `DISABLE_PASSWORD_REGISTRATION=true`."+ },+ "requireEmailVerification": {+ "type": "boolean",+ "description": "New password sign-ups must confirm their email before they can sign in. Requires email delivery."+ },+ "defaultRole": {+ "type": "string",+ "minLength": 1,+ "maxLength": 64,+ "description": "Instance role for new users: `user` or a custom role name, never `admin`. You can only choose a role whose permissions you have."+ },+ "workspaceCreationRestricted": {+ "type": "boolean",+ "description": "Only administrators can create workspaces. Locked when `DISABLE_WORKSPACE_CREATION=true`."+ },+ "disabledIntegrations": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "maxItems": 32,+ "description": "Integration provider types to turn off. Their connections stop syncing and delivering, and projects can't connect them."+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "The saved settings",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/InstanceSettings"+ }+ }+ }+ },+ "400": {+ "description": "Invalid value, `admin` as the default role, an unknown role or integration, or email verification without SMTP",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid credentials",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "403": {+ "description": "The caller lacks the instance permission, used an API key, or chose a default role with permissions they lack",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "409": {+ "description": "An environment variable locks the setting (code SETTING_LOCKED_BY_ENV)",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ApiError"+ }+ }+ }+ },+ "429": {+ "$ref": "#/components/responses/ApiKeyRateLimited"+ }+ }+ }+ },"/admin/users/{userId}/sessions": {"get": {"operationId": "listAdminUserSessions",