From c757210cf7c4539be4d45318b18673ee75f365ad Mon Sep 17 00:00:00 2001 From: SaelixCode Date: Thu, 7 May 2026 09:54:06 -0400 Subject: [PATCH] docs(configuration): align env var reference with current backend Bring docs/getting-started/configuration.mdx up to date with the v0.72.0 backend: - Remove PORT from the optional env vars table. The listen port is hardcoded to 1852 in backend/src/helpers/constants.ts and is never read from the environment. Replace it with a Listen port section that explains the fixed port and host-port remapping. - Document API_RATE_LIMIT (default 200) and API_POLLING_RATE_LIMIT (default 300), both applied in production only. - Note the /app/compose fallback default for COMPOSE_DIR while still pointing readers at the 1:1 path rule. - Point the SSO env var section at the new SSO Quickstart page and keep the SSO feature reference as the deeper dive. - Tighten First boot and cross-link to Quickstart so the screenshot is not duplicated. - Add a Where to next CardGroup matching the refreshed Introduction and Quickstart pages. Drop stale PORT=1852 and JWT_SECRET=your-secure-jwt-secret-here lines from .env.example so the example no longer contradicts the docs (PORT is hardcoded, JWT_SECRET is auto-generated and persisted to the database during initial setup). --- .env.example | 6 ---- docs/getting-started/configuration.mdx | 39 ++++++++++++++++++++++---- 2 files changed, 34 insertions(+), 11 deletions(-) diff --git a/.env.example b/.env.example index ac4a367d..a132b2e1 100644 --- a/.env.example +++ b/.env.example @@ -1,15 +1,9 @@ # Sencho Configuration # Copy this file to .env and update the values for production -# JWT secret - generate a secure random string for production -JWT_SECRET=your-secure-jwt-secret-here - # Directory containing docker-compose files COMPOSE_DIR=/path/to/your/compose/files -# HTTP server port (default: 1852) -PORT=1852 - # Database and state directory inside the container (default: /app/data) DATA_DIR=/app/data diff --git a/docs/getting-started/configuration.mdx b/docs/getting-started/configuration.mdx index 6be7c200..c321b47d 100644 --- a/docs/getting-started/configuration.mdx +++ b/docs/getting-started/configuration.mdx @@ -9,7 +9,7 @@ Sencho is configured entirely through environment variables and Docker volume mo | Variable | Description | |----------|-------------| -| `COMPOSE_DIR` | Absolute path to the directory that contains your Compose stacks. Every subdirectory inside becomes a stack in Sencho. | +| `COMPOSE_DIR` | Absolute path to the directory that contains your Compose stacks. Every subdirectory inside becomes a stack in Sencho. Falls back to `/app/compose` if unset, but per the [1:1 path rule](#compose-directory-the-11-path-rule) you should always set this explicitly to match the host path you mount. | **JWT_SECRET is generated automatically.** Sencho creates a secure random signing key during initial setup and stores it in its database. You do not need to provide one. @@ -23,11 +23,23 @@ When you point `COMPOSE_DIR` at a directory, Sencho expects each stack to live i | Variable | Default | Description | |----------|---------|-------------| -| `PORT` | `1852` | Port the Sencho HTTP server listens on. | | `DATA_DIR` | `/app/data` | Directory where Sencho stores its SQLite database, node registry, and cached metrics. | | `FRONTEND_URL` | *(empty)* | Frontend origin for CORS. Only needed if the UI is served from a different domain than the API. Leave empty for same-origin setups. | | `NODE_ENV` | `production` | Set automatically in the Docker image. Only change this for local development. | -| `SENCHO_USER` | *(unset)* | Optional. When set to a username present inside the container (`sencho` is pre-created for this purpose), the entrypoint drops privileges to that user at startup instead of running as `root`. See [Running as a non-root user](#running-as-a-non-root-user) below. | +| `SENCHO_USER` | *(unset)* | When set to a username present inside the container (`sencho` is pre-created for this purpose), the entrypoint drops privileges to that user at startup instead of running as `root`. See [Running as a non-root user](#running-as-a-non-root-user) below. | +| `API_RATE_LIMIT` | `200` | Global API requests per minute per user session. Applies in production only; development uses a fixed higher cap. Authenticated requests are keyed by user ID, unauthenticated by IP. Internal node-to-node traffic bypasses this limit. | +| `API_POLLING_RATE_LIMIT` | `300` | Rate limit for dashboard polling endpoints, in requests per minute. Applies in production only; development uses a fixed higher cap. Raise it for environments with many concurrent browser sessions behind shared NAT. | + +## Listen port + +Sencho always listens on `1852` inside the container. The port is fixed and is not read from an environment variable. To expose Sencho on a different host port, remap with Docker's `-p` flag (or the `ports:` key in your compose file): + +```yaml +ports: + - "8080:1852" # host 8080 to container 1852 +``` + +Behind a reverse proxy you can keep the standard mapping and let the proxy own the public port. ## Container user @@ -71,7 +83,7 @@ If you use SSO (Admiral), configure your identity providers via environment vari | `SSO_OIDC_OKTA_ENABLED` | Enable Okta SSO | | `SSO_CALLBACK_URL` | External base URL for OAuth callbacks (required behind reverse proxy) | -For the full SSO configuration reference and setup guides, see [SSO Authentication →](/features/sso). +For end-to-end provider setup walkthroughs, see the [SSO Quickstart →](/getting-started/sso-quickstart). For the full feature reference, see [SSO Authentication →](/features/sso). ## Required volume mounts @@ -270,4 +282,21 @@ Caddy automatically obtains and renews SSL certificates via Let's Encrypt. WebSo ## First boot -After starting Sencho, open it in your browser. If no admin account exists yet, you'll be taken to a setup screen to create one. This only appears once - subsequent visits go directly to the login page. +After starting Sencho, open `http://localhost:1852` in a browser. On a fresh install you land on the **Cold start** card to create the first admin account; every subsequent visit goes to the regular sign-in screen. The [Quickstart](/getting-started/quickstart#first-boot) shows it in detail. + +## Where to next + + + + Deploy, edit, restart, update, and roll back stacks from the cockpit. + + + Add a remote Sencho instance and manage it from the same console. + + + Resource recommendations, networking, and Docker socket security. + + + End-to-end provider setup for OIDC, LDAP, and Active Directory. + +