gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-07-26 11:49:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
2465f7607e5bccd0b0f84d0ca9f1eecc18018753
sencho/docs/reference/settings.mdx
T
Anso 2465f7607e fix(stacks): harden stack management with security, validation, and logging (#520) 
* fix(stacks): harden stack management with security fixes, validation alignment, and logging

Validate WebSocket stack names with isValidStackName() to close a
path-traversal gap on the /api/stacks/:stackName/logs WS endpoint.
Align POST /api/stacks to use the canonical validator (allows underscores).
Replace error: any catch blocks with error: unknown + type narrowing.
Add cache invalidation to PUT /api/stacks/:stackName/env.
Rename DELETE param from :name to :stackName for consistency.

Add standard [Stacks] lifecycle logs and diagnostic [Stacks:debug] logs
gated behind the Developer Mode toggle (with 5s TTL cache).
Extract shared isDebugEnabled() and getErrorMessage() utilities.

Frontend: roll back optimistic status on API failure, guard unsaved
changes when switching stacks, pre-check duplicate names in App Store.

* docs(settings): update Developer Mode description to mention debug diagnostics
2026-04-12 05:43:15 -04:00

313 lines
10 KiB
Plaintext
Raw Blame History

---
title: Settings Reference
description: Complete reference for every option in the Sencho Settings Hub.
---
Open the Settings Hub by clicking the **Profile** icon in the top bar and selecting **Settings**. The left sidebar lists all available sections. Some sections show a lock icon when they require a higher license tier.
<Frame>
<img src="/images/settings/settings-overview.png" alt="Settings Hub showing the Account tab and the full section sidebar" />
</Frame>
---
## Account
**Scope:** Global (applies to this Sencho instance, not per-node)
Change the admin account password. All three fields are required.
| Field | Description |
|-------|-------------|
| **Current Password** | Your existing password for verification |
| **New Password** | Must be at least 6 characters |
| **Confirm New Password** | Must match New Password |
Click **Update Password** to apply. The change takes effect immediately; existing sessions remain valid.
---
## License
**Scope:** Global
Manage your Sencho license and subscription from this section.
| Element | Description |
|---------|-------------|
| **Current tier** | Shows your current tier (Community, Skipper, or Admiral) with a tier badge |
| **Trial status** | If on a trial, shows remaining days |
| **Renews** | Next renewal date for active subscriptions |
| **Upgrade cards** | Dynamic plan cards with feature highlights and checkout links. Community users see Skipper and Admiral; Skipper users see Admiral only |
| **Activate** | Enter a license key to activate your plan (visible when no license is active) |
| **Manage Subscription** | Opens the Lemon Squeezy billing portal (Skipper / Admiral only) |
| **Deactivate License** | Reverts to Community features (Skipper / Admiral only) |
See [Licensing & Billing](/features/licensing) for the full walkthrough.
---
## Users
<Note>
User management requires a Sencho Skipper or Admiral license and admin role. Community supports a single admin account only.
</Note>
**Scope:** Global
Create and manage user accounts with role-based access.
| Action | Description |
|--------|-------------|
| **Create user** | Add a new account with username, password, and role |
| **Edit user** | Change an existing user's password or role |
| **Delete user** | Remove a user account (you cannot delete your own account) |
**Available roles:**
| Role | Tier | Description |
|------|------|-------------|
| **Admin** | Skipper+ | Full access to all features |
| **Viewer** | Skipper+ | Read-only access to stacks and nodes |
| **Deployer** | Admiral | Can view stacks and trigger deployments |
| **Node Admin** | Admiral | Full stack and node management, no system settings |
| **Auditor** | Admiral | Read-only plus audit log access |
See [RBAC & User Management](/features/rbac) for details on what each role can access.
---
## SSO
<Note>
SSO requires a Sencho Admiral license.
</Note>
**Scope:** Global
Configure Single Sign-On providers (LDAP/AD and OIDC) for centralized authentication. Each provider type has its own configuration card with connection fields, a test button, and an active toggle.
See [SSO](/features/sso) for the full configuration walkthrough.
---
## API Tokens
<Note>
API Tokens require a Sencho Admiral license.
</Note>
**Scope:** Global
Create and manage long-lived API tokens for external integrations and automation. Tokens can be scoped to specific permissions.
See [API Tokens](/features/api-tokens) for the full walkthrough.
---
## Registries
<Note>
Private Registries require a Sencho Admiral license.
</Note>
**Scope:** Global
Configure private Docker registries so Sencho can pull images that require authentication.
See [Private Registries](/features/private-registries) for the full walkthrough.
---
## Labels
<Note>
Stack Labels require a Sencho Skipper or Admiral license.
</Note>
**Scope:** Global
Create, edit, and delete labels used to organize and filter stacks across your fleet. Each label has a name and one of ten available colors.
See [Stack Labels](/features/stack-labels) for the full walkthrough.
---
## System Limits
**Scope:** Per-node (applies to the currently selected node)
Configure resource thresholds that trigger visual warnings on the dashboard stat cards. These are display thresholds only; Sencho does not throttle or kill containers when limits are reached. When viewing a remote node, a badge shows which node you are configuring.
| Setting | Default | Description |
|---------|---------|-------------|
| **Host CPU Alert Threshold** | 90% | CPU percentage above which the CPU card turns orange/red |
| **Host RAM Alert Threshold** | 90% | RAM percentage above which the RAM card turns orange/red |
| **Host Disk Alert Threshold** | 90% | Disk percentage above which the Disk card turns orange/red |
| **Docker Janitor Storage Threshold** | 5 GB | Alert when unused Docker data (reclaimable via prune) exceeds this size. Set to `0` to disable. |
| **Global Crash Detection** | On | Watch all containers for unexpected exits. When enabled, Sencho sends a notification whenever any managed container exits unexpectedly. |
Click **Save Limits** to apply.
---
## Notifications
**Scope:** Per-node (each node has its own notification agents; remote nodes dispatch alerts through their own channels)
Configure external destinations for alert notifications. Three agent types are available on separate tabs: **Discord**, **Slack**, and **Webhook**.
For each agent:
| Field | Description |
|-------|-------------|
| **Enable toggle** | Activates or deactivates this agent. Disabled agents receive no messages even if a URL is saved. |
| **Webhook URL** | The endpoint Sencho will POST to when an alert fires |
Click **Save** to persist changes. Click **Test** to send a test payload immediately and verify delivery.
At least one agent must be enabled for stack alerts to deliver notifications. See [Alerts & Notifications](/features/alerts-notifications) for how to create alert rules.
---
## Routing
<Note>
Notification Routing requires a Sencho Admiral license.
</Note>
**Scope:** Global
Create routing rules that direct specific alert types to specific notification channels. Rules let you send critical alerts to one channel and informational alerts to another.
See [Notification Routing](/features/notification-routing) for the full walkthrough.
---
## Webhooks
<Note>
Webhooks require a Sencho Skipper or Admiral license.
</Note>
**Scope:** Global
Create and manage HTTP webhooks that external systems (CI/CD pipelines, automation tools) can call to trigger stack actions. See [Webhooks](/features/webhooks) for the full walkthrough including authentication and CI examples.
Quick reference:
| Action | How |
|--------|-----|
| Create a webhook | Click **Create Webhook**, select a stack and action |
| Copy trigger URL | Click the copy icon on any webhook row |
| View execution history | Expand a webhook row to see recent executions |
| Delete a webhook | Click the trash icon |
---
## Developer
**Scope:** Per-node (streaming and polling settings), Global (data retention)
Advanced settings for log streaming behavior and data retention. Most users can leave these at their defaults.
### Streaming
| Setting | Default | Description |
|---------|---------|-------------|
| **Developer Mode** | Off | Enables real-time SSE streaming for [Global Observability](/features/global-observability), and activates debug diagnostics (timing, cache state, file resolution) in the server logs |
| **Standard Log Polling Rate** | 5s | Polling interval in standard mode. Options: `1s`, `3s`, `5s`, `10s`. Disabled when Developer Mode is on. |
### Data Retention
| Setting | Default | Max | Description |
|---------|---------|-----|-------------|
| **Container Metrics Retention** | 24 hrs | 8,760 (1 year) | How long to keep per-container CPU, RAM, and network history for dashboard charts |
| **Notification Log Retention** | 30 days | 365 | How long to keep alert and notification history |
| **Audit Log Retention** | 90 days | 365 | How long to keep audit trail entries (Admiral only) |
Click **Save Developer Settings** to apply.
<Note>
Lower polling rates (1s) increase backend CPU usage as Sencho polls Docker more frequently. Use only when actively debugging.
</Note>
---
## Nodes
**Scope:** Global
Manage connections to local and remote Sencho instances. This is the same interface as the [Multi-Node](/features/multi-node) feature; see that page for the full walkthrough.
Quick reference:
| Action | How |
|--------|-----|
| Add a remote node | Click **+ Add Node** |
| Generate a token for this instance | Click **Generate Token** |
| Test an existing node's connectivity | Click the wifi icon on any row |
| Edit a node | Click the pencil icon |
| Delete a node | Click the trash icon (remote nodes only) |
---
## App Store
**Scope:** Global
Configure the template source used by the App Store.
| Element | Description |
|---------|-------------|
| **Default Registry** | LinuxServer.io (used when no custom URL is set) |
| **Custom Registry URL** | A URL pointing to a Portainer v2 compatible template JSON file. Overrides the default registry. Leave empty to use the default. |
| **Reset to Default** | Clears the custom URL and reverts to LinuxServer.io |
Click **Save & Refresh** to update the URL and immediately refresh the cached template list.
See [App Store](/features/app-store#custom-template-registry) for more on custom registries.
---
## Support
**Scope:** Global
Links to help resources, with additional channels for Skipper and Admiral users.
### Resources (all tiers)
| Resource | Description |
|----------|-------------|
| **Documentation** | Opens docs.sencho.io |
| **GitHub Issues** | Report bugs and request features on GitHub |
### Paid tier support
Skipper and Admiral license holders see additional support channels:
| Channel | Description |
|---------|-------------|
| **Email Support** | Direct email support (Skipper) |
| **Priority Email Support** | Responses within 24 hours (Admiral) |
Community users see an upgrade prompt with a link to the pricing page.
---
## About
**Scope:** Global
Displays instance information at a glance.
| Field | Description |
|-------|-------------|
| **Version** | Current Sencho version (e.g. v0.38.0) |
| **Tier** | Community, Skipper, or Admiral badge |
| **License Status** | Active, trial, expired, or community |
| **Instance ID** | Truncated unique identifier for this Sencho instance |
The **Links** section contains a link to the full changelog on GitHub.
Reference in New Issue View Git Blame Copy Permalink