gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-08-18 06:23:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: comprehensive review and refresh of all documentation (#374)

Browse Source 
* docs: comprehensive review and refresh of all documentation pages

Reviewed every doc page against the current app state after the v0.38
dashboard redesign. Updated content, fixed inaccuracies, and refreshed
all screenshots at 1920x1080.

Pages updated:
- introduction: expanded feature list to 25 items across 6 subsections
- quickstart: fixed docker run command (Docker Hub, auto JWT, COMPOSE_DIR)
- configuration: replaced personal paths with generic /home/user/docker
- sso-quickstart: fixed Settings navigation reference
- sso: added SSO_LDAP_DISPLAY_NAME env var
- overview: added 8 missing feature sections (labels, API tokens, schedules, etc.)
- dashboard: complete rewrite for new health bar, gauges, stack health table
- stack-management: updated for UP/DN indicators, rollback button, split actions
- editor: rewritten for two-column layout, inline stats, embedded terminal
- resources: updated Quick Clean docs, added network topology and inspect
- app-store: updated categories, deploy sheet details, permission gate, settings
- openapi.yaml: fixed YAML parsing error on line 1831

Screenshots refreshed: 14 images across 6 feature areas.

* docs: review and update observability, console, multi-node, and compatibility pages

- Global Observability: fix log format fields, add download button docs,
  split display limits into memory buffer vs rendered rows, correct
  settings labels
- Host Console: remove internal implementation details per security
  docs policy, add stack directory behavior, expand header bar docs,
  remove unverified scrollback claim
- Multi-Node: add Compose Directory field, document connection test
  details panel, fix edit/delete node behavior, simplify token security
  section, remove internal details
- Node Compatibility: add missing self-update capability, remove
  internal endpoint paths and cache TTL, move from Features to
  Reference group in navigation
- Refresh all screenshots for the redesigned UI (7 images)

* docs: review and refresh fleet, remote updates, labels, alerts, routing, and webhooks pages

- Fleet View: added node updates modal, container detail, version/update/critical badges, Tags filter
- Remote Updates: removed internal details, added capability cross-link, fast polling
- Stack Labels: three creation methods, two assignment methods, 10 colors, bulk actions screenshot
- Alerts & Notifications: fixed metric labels, added notification popover detail, status banner
- Notification Routing: HTTPS requirement, rule card layout, channel terminology fix
- Webhooks: corrected license tier to Admiral, matched action labels to UI, removed internal security details, added local-only note
- Troubleshooting: centralized entries from remote-updates, stack-labels, notification-routing
- Refreshed all screenshots at 1920x1080, removed 11 orphaned images

* docs: review and refresh RBAC, user management, and atomic deployments pages

- RBAC: added missing Auditor role (5th role), updated permission matrix, fixed license tier references, documented username/password validation rules, self-deletion protection
- Atomic Deployments: added "Which operations are protected" section covering webhooks/schedules/app store, removed internal backup path, fixed license tier to Skipper/Admiral
- Screenshots: cropped to dialog element per updated strategic cropping guideline, removed 2 orphaned images

* docs: review and refresh fleet-wide backups and audit log pages

Update fleet-backups page to reflect current inline create form, add
scheduled snapshots section, document the detail view and restore dialog,
expand RBAC table to all five roles. Update audit log page to document
expanded row detail fields, pagination, refresh button, and data retention
screenshot. Replace all screenshots with fresh captures at 1920x720.

* docs: review and refresh API tokens and private registries pages

- API Tokens: clarify Full Admin scope, add Managing tokens section
  with card details, document revocation confirmation dialog, add
  usage tracking to security model, refresh screenshot
- Private Registries: add Managing registries section with card details
  and action buttons, document edit behavior, fix URL auto-fill
  description, remove encryption algorithm name per security policy,
  fix grammar, refresh both screenshots

* docs: review and refresh auto-update policies, scheduled operations, and SSO pages

- Auto-Update Policies: document all 8 table columns, expand action buttons,
  add "All Stacks" wildcard option, fix field labels, add CSV export and
  pagination details, refresh screenshots
- Scheduled Operations: fix System Prune target description, add Task List
  table columns, restructure create dialog fields with action-specific
  annotations, rewrite execution history with column table, refresh screenshots
- SSO: remove encryption algorithm name per security policy, add LDAP and
  OIDC configuration field tables, document provider card controls (Save,
  Test Connection, Remove, Active badge), refresh screenshots
- Move SSO troubleshooting entries to centralized troubleshooting page

* docs: review and refresh licensing & billing page

Update upgrade card feature lists to match actual tier gating (Skipper:
fleet view, webhooks, labels, atomic deployments, backups, auto-update
policies; Admiral: scoped RBAC, SSO, audit log, host console, API
tokens, private registries, scheduled operations). Add flex layout to
align upgrade card buttons at the bottom. Replace stale screenshot with
fresh community and active license captures. Add feature breakdown
subsection and profile menu billing shortcut to docs.

* docs: review and refresh settings reference and security advisories pages

Settings Reference: add 5 missing sections (SSO, API Tokens, Registries,
Labels, Routing), expand Users from 2 to 5 roles, fix System Limits and
Developer field labels to match UI, restructure Developer into Streaming
and Data Retention sub-tables, update App Store and Support sections,
refresh overview screenshot.

Security Advisories: restructure into versioned sections (v0.25.x
hardening and v0.19-v0.24 CVE remediation), expand from 3 bullet points
to 10 specific improvements, fix GitHub URL from SaelixCode to AnsoCode,
redact internal details per security docs policy.

Remove "Sencho Pro" product name from all three pages, replaced with
tier names (Community, Skipper, Admiral).

* docs: review and refresh troubleshooting page, remove architecture and development guides

- Rewrote forgotten password section to remove exposed SQL and table names
- Updated all Settings navigation paths to Profile > Settings > X
- Fixed network topology from "tab" to "view mode", added Pro license note
- Updated Prune Networks to current "Prune Dead Networks" label
- Corrected update check cooldown from vague to 2 minutes
- Consolidated two network creation error sections into one
- Removed hardcoded version reference (v0.34.0)
- Replaced em dashes throughout
- Deleted architecture.mdx (exposes internal implementation details)
- Deleted development.mdx (contributor guide belongs in repo, not public docs)
- Removed both pages from docs.json navigation

* docs: review and refresh operations pages (backup, upgrade, self-hosting, troubleshooting)

Backup & Restore:
- Added missing encryption.key to all backup/restore procedures
- Added Warning about restoring db without matching encryption key
- Added cross-reference to Fleet-Wide Backups for paid tiers
- Removed false claim about no built-in backup scheduler
- Updated cron example to include encryption key copy

Upgrading Sencho:
- Removed internal migration details (table names, column specs, encryption algorithm)
- Replaced with high-level migration summary per security docs policy
- Added encryption.key to pre-upgrade backup command
- Updated version pinning example from 0.25.3 to 0.38.0
- Added Remote Updates cross-reference for Skipper/Admiral users

Self-Hosting Best Practices:
- Removed JWT_SECRET from env var table (auto-generated, not an env var)
- Removed PORT from env var table (hardcoded to 3000, not configurable)
- Added API_RATE_LIMIT to env var table (actually exists in code)
- Fixed listen port description from "configurable" to "fixed"
- Updated resource recommendations based on measured footprint audit
- Removed su-exec reference (internal implementation detail)
- Upgraded data directory Note to Warning with file names

Troubleshooting:
- Fixed "Pro features" heading to "Paid features" with correct tier names
This commit is contained in:
Anso
2026-04-04 21:32:51 -04:00
committed by GitHub
parent 7b14da0b10
commit a1804c8fbe
121 changed files with 1433 additions and 1126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations/backup.mdx
+20 -14
View File
@@ -3,7 +3,11 @@ title: Backup & Restore
description: What to back up, how to restore it, and how to migrate Sencho to a new host.
---
Sencho stores all its state in two places: the **data directory** (SQLite database) and your **compose directory** (your actual stack files). Both need to be backed up for a complete recovery.
Sencho stores all its state in two places: the **data directory** (SQLite database and encryption key) and your **compose directory** (your actual stack files). Both need to be backed up for a complete recovery.
<Note>
Skipper and Admiral users also have access to [Fleet-Wide Backups](/features/fleet-backups), which snapshot compose files across all nodes directly from the dashboard. This page covers lower-level backup of the Sencho instance itself.
</Note>
---
@@ -14,15 +18,18 @@ Sencho stores all its state in two places: the **data directory** (SQLite databa
Default path: `/app/data` inside the container, mapped to wherever you mounted it on the host (e.g. `./sencho-data`).
Contains:
- `sencho.db` - SQLite database with all settings, nodes, alerts, metrics history, and notification history
- `sencho.db` - SQLite database with all settings, users, nodes, alerts, metrics history, and notification config
- `encryption.key` - Key used to encrypt sensitive values (registry credentials, node API tokens) stored in the database
This single file is everything Sencho knows about itself. Back it up and you can fully restore any Sencho installation.
<Warning>
Both files are required for a full restore. If you restore `sencho.db` without the matching `encryption.key`, any encrypted values in the database will be unreadable and you will need to re-enter registry credentials and re-generate node API tokens.
</Warning>
### 2. Compose directory (`COMPOSE_DIR`)
The directory containing your stack subdirectories - your `compose.yaml` files, `.env` files, and any bind-mounted config files stored there.
The directory containing your stack subdirectories: your `compose.yaml` files, `.env` files, and any bind-mounted config files stored there.
This is your actual application data. It lives entirely outside Sencho and you almost certainly already have it on a schedule, but include it in any Sencho backup plan.
This is your actual application data. It lives entirely outside Sencho and you almost certainly already back it up on a schedule, but include it in any Sencho backup plan.
---
@@ -34,7 +41,7 @@ This is your actual application data. It lives entirely outside Sencho and you a
# Stop Sencho to ensure no active transactions (recommended but not strictly required)
docker stop sencho
# Copy the data directory
# Copy the data directory (includes both sencho.db and encryption.key)
cp -r /path/to/sencho-data /path/to/backup/sencho-data-$(date +%Y%m%d)
# Copy compose stacks
@@ -45,7 +52,7 @@ docker start sencho
```
<Note>
Sencho uses SQLite's default journal mode (not WAL), so you will not see `-wal` or `-shm` sidecar files alongside `sencho.db`. If a `-journal` file exists when you copy, it indicates an interrupted write — SQLite will automatically resolve it the next time the database is opened.
Sencho uses SQLite's default journal mode (not WAL), so you will not see `-wal` or `-shm` sidecar files alongside `sencho.db`. If a `-journal` file exists when you copy, it indicates an interrupted write. SQLite will automatically resolve it the next time the database is opened.
</Note>
### SQLite online backup (without stopping)
@@ -56,13 +63,15 @@ SQLite supports hot backups via its `.backup` command. This is safe to run while
sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho.db'"
```
Remember to also copy `encryption.key` from the same directory.
### Automated daily backup (cron example)
```cron
0 3 * * * sqlite3 /path/to/sencho-data/sencho.db ".backup '/backups/sencho-$(date +\%Y\%m\%d).db'" && find /backups -name "sencho-*.db" -mtime +30 -delete
0 3 * * * cp /path/to/sencho-data/encryption.key /backups/encryption.key && sqlite3 /path/to/sencho-data/sencho.db ".backup '/backups/sencho-$(date +\%Y\%m\%d).db'" && find /backups -name "sencho-*.db" -mtime +30 -delete
```
This backs up the database at 3 AM daily and deletes backups older than 30 days.
This copies the encryption key, backs up the database at 3 AM daily, and deletes database backups older than 30 days.
---
@@ -79,6 +88,7 @@ This backs up the database at 3 AM daily and deletes backups older than 30 days.
```bash
rm -rf /path/to/sencho-data/*
cp /path/to/backup/sencho.db /path/to/sencho-data/sencho.db
cp /path/to/backup/encryption.key /path/to/sencho-data/encryption.key
```
3. Restore your compose directory if needed:
@@ -135,9 +145,5 @@ If other Sencho instances were pointing to your old host as a remote node, updat
| Item | Location | Notes |
|------|----------|-------|
| Container data volumes | Wherever each stack's volumes are mounted on the host | Back these up separately per-application |
| Actual container images | Docker image cache | These are re-pulled on next deploy - no backup needed |
| Actual container images | Docker image cache | These are re-pulled on next deploy; no backup needed |
| Sencho logs (docker logs) | Container stdout | Not persisted beyond container lifetime |
<Note>
Sencho does not currently have a built-in backup scheduler or export function. The approaches above use standard OS tools and SQLite's own backup mechanism.
</Note>
docs/operations/self-hosting.mdx
+12 -13
View File
@@ -5,7 +5,7 @@ description: Volume mounts, Docker socket security, networking, and resource rec
## The 1:1 path rule
This is the most common setup mistake. When Sencho deploys a Docker Compose stack, Docker resolves bind-mount volume paths relative to the **host filesystem**, not the Sencho container. If your compose files reference relative paths like `./data:/app/data`, Docker looks for `./data` on the host — starting from the directory where the compose file lives on the host.
This is the most common setup mistake. When Sencho deploys a Docker Compose stack, Docker resolves bind-mount volume paths relative to the **host filesystem**, not the Sencho container. If your compose files reference relative paths like `./data:/app/data`, Docker looks for `./data` on the host, starting from the directory where the compose file lives on the host.
This means the path to your compose directory **must be identical** inside and outside the container:
@@ -32,12 +32,12 @@ Sencho requires three volume mounts to function correctly:
| Mount | Purpose | Required |
|-------|---------|----------|
| `/var/run/docker.sock:/var/run/docker.sock` | Docker Engine access for managing containers | Yes |
| `./sencho-data:/app/data` | Persistent storage for SQLite database and encryption keys | Yes |
| `./sencho-data:/app/data` | Persistent storage for the database and encryption key | Yes |
| `/opt/compose:/opt/compose` | Your compose project files (must follow 1:1 path rule) | Yes |
<Note>
The data directory contains your Sencho database and encryption keys. Losing this directory means losing your Sencho configuration entirely.
</Note>
<Warning>
The data directory contains your Sencho database (`sencho.db`) and encryption key (`encryption.key`). Losing this directory means losing your Sencho configuration entirely. See the [Backup & Restore guide](/operations/backup) for backup procedures.
</Warning>
---
@@ -48,7 +48,7 @@ Mounting the Docker socket (`/var/run/docker.sock`) grants the container the abi
Sencho mitigates this with privilege dropping:
1. The container starts as root to fix volume ownership and resolve Docker socket group permissions
2. The entrypoint script (`docker-entrypoint.sh`) then drops to a non-root `sencho` user via `su-exec`
2. The entrypoint script then drops to a non-root `sencho` user
3. All application code runs as the `sencho` user
If your environment requires stricter isolation, consider:
@@ -63,9 +63,9 @@ If your environment requires stricter isolation, consider:
| Resource | Minimum | Recommended | Notes |
|----------|---------|-------------|-------|
| CPU | 1 core | 1-2 cores | More cores help with concurrent stack operations |
| RAM | 256 MB | 512 MB | Higher for multi-node setups with many stacks |
| Disk | 100 MB | 500 MB | Database is typically < 50 MB; allocate headroom for metrics retention |
| CPU | 1 core | 2 cores | Compose operations spawn child processes that benefit from a second core |
| RAM | 128 MB | 256 MB | Baseline is around 100 MB at idle; increases with concurrent log streams and large fleets |
| Disk | 200 MB | 500 MB | The Docker image is around 200 MB; the database grows with metrics retention and fleet size |
Sencho itself is lightweight. The majority of resource usage on your host comes from the Docker containers it manages, not from Sencho.
@@ -73,7 +73,7 @@ Sencho itself is lightweight. The majority of resource usage on your host comes
## Networking
- **Listen port:** 3000 by default, configurable via the `PORT` environment variable
- **Listen port:** 3000 (fixed). Map it to any host port using Docker's `-p` flag or `ports` in your compose file
- **Inbound:** Only the listen port needs to be reachable (directly or through a reverse proxy)
- **Outbound:** No outbound connections are required for local-only setups. If you use multi-node management, Sencho needs HTTP/HTTPS access to remote Sencho instances on their configured API URLs
- **Health check:** `GET /api/health` returns `200` when the application is ready. The Docker image includes a built-in `HEALTHCHECK` that polls this endpoint every 30 seconds
@@ -86,11 +86,10 @@ Quick reference for all environment variables. See [Configuration](/getting-star
| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | *(required)* | Secret key for signing JWT tokens |
| `COMPOSE_DIR` | `/app/compose` | Path to compose project files (1:1 rule applies) |
| `PORT` | `3000` | HTTP server listen port |
| `DATA_DIR` | `/app/data` | Persistent data directory |
| `NODE_ENV` | `production` | Set automatically in Docker image |
| `FRONTEND_URL` | *(empty)* | Frontend origin for CORS; leave empty for same-origin |
| `API_RATE_LIMIT` | `100` | Maximum API requests per minute per IP (production only) |
| `NODE_ENV` | `production` | Set automatically in the Docker image |
SSO variables are documented separately in the [SSO Quickstart](/getting-started/sso-quickstart).
docs/operations/troubleshooting.mdx
+162 -76
View File
@@ -61,19 +61,19 @@ ls -la /var/run/docker.sock
# Expected: srw-rw---- 1 root docker ...
```
If the group is not `docker`, the auto-detection still works - Sencho reads the GID from the socket file at startup.
If the group is not `docker`, the auto-detection still works. Sencho reads the GID from the socket file at startup.
---
## "Permission denied" when deleting a stack
**Symptom:** Clicking Delete on a stack fails with a permission error mentioning `EACCES`.
**Symptom:** Clicking **Delete** on a stack fails with a permission error.
**Cause:** Stack directories often contain files owned by root — for example when Docker Compose was run with `sudo`, or when containers write config/data files into the stack directory. Since Sencho runs as a non-root user, the OS denies the removal.
**Cause:** Stack directories often contain files owned by root, for example when Docker Compose was run with `sudo`, or when containers write config/data files into the stack directory. Since Sencho runs as a non-root user, the OS denies the removal.
This is especially common when installing Sencho on a server where stacks were originally created outside of Sencho (e.g. via `sudo docker compose up`). Those directories and their contents are root-owned, but Sencho can still delete them.
**How Sencho handles it:** Sencho automatically detects permission errors during deletion and falls back to a Docker-based cleanup. It spawns a short-lived Alpine container that bind-mounts the stack directory and removes the root-owned files. This happens transparently — no manual intervention is needed in the standard Docker setup.
**How Sencho handles it:** Sencho automatically detects permission errors during deletion and falls back to a Docker-based cleanup. It spawns a short-lived container that bind-mounts the stack directory and removes the root-owned files. This happens transparently, with no manual intervention needed in the standard Docker setup.
**If automatic cleanup fails:** The error message will include the directory path. Remove it manually:
@@ -81,7 +81,7 @@ This is especially common when installing Sencho on a server where stacks were o
sudo rm -rf /path/to/your/compose/dir/stack-name
```
**Prerequisites:** The Docker socket must be mounted (standard setup). If Sencho cannot access Docker, the fallback will not work — see [Permission denied on the Docker socket](#permission-denied-on-the-docker-socket).
**Prerequisites:** The Docker socket must be mounted (standard setup). If Sencho cannot access Docker, the fallback will not work. See ["Permission denied" on the Docker socket](#permission-denied-on-the-docker-socket).
---
@@ -99,6 +99,26 @@ sudo rm -rf /path/to/your/compose/dir/stack-name
---
## Forgotten admin password
Sencho has no password recovery flow. To regain access:
1. Stop the Sencho container.
2. Delete the database file inside your data directory (`sencho.db`). You can find it in the volume you mounted to `/app/data`.
```bash
# Example, adjust the path to match your data volume mount
rm /path/to/data/sencho.db
```
3. Restart the container. Sencho will detect the missing database and re-enter first-boot setup mode, prompting you to create a new admin account.
<Warning>
This resets all Sencho configuration: users, nodes, alert rules, notification settings, and labels. Your Docker stacks and their compose files are not affected (they live in `COMPOSE_DIR`, not the database). Sencho will re-discover your stacks on the next sidebar scan.
</Warning>
---
## WebSocket connections fail (logs/console not streaming)
**Symptom:** The log viewer or host console shows a spinner that never resolves, or you see "Disconnected" immediately after connecting.
@@ -115,7 +135,7 @@ proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
```
Traefik handles WebSocket upgrades automatically for HTTP/1.1 backends - no extra config needed.
Traefik handles WebSocket upgrades automatically for HTTP/1.1 backends, so no extra config is needed.
---
@@ -126,59 +146,34 @@ Traefik handles WebSocket upgrades automatically for HTTP/1.1 backends - no extr
**Checks in order:**
1. **Is the remote Sencho instance running?** SSH to that machine and verify.
2. **Is the API URL correct?** It must include the protocol and port (e.g. `http://192.168.1.20:3001`). Open it in a browser - you should see a JSON response from `/api/health`.
2. **Is the API URL correct?** It must include the protocol and port (e.g. `http://192.168.1.20:3001`). Open it in a browser; you should see a JSON response from `/api/health`.
3. **Is the token correct?** Tokens are long JWT strings. Even one missing character will cause auth to fail. Regenerate the token on the remote instance and update the node config.
4. **Is there a firewall blocking the port?** The primary Sencho host must be able to reach the remote host's Sencho port.
Click the **wifi icon** on the node row to re-test connectivity after making changes.
To re-test connectivity after making changes, open **Profile > Settings > Nodes** and click the **wifi icon** on the node row.
---
## Pro features return 403 on remote nodes
## Paid features return 403 on remote nodes
**Symptom:** A Pro or Admiral feature works on the local node but returns "This feature requires Sencho Pro" (403) when you switch to a remote node.
**Symptom:** A Skipper or Admiral feature works on the local node but returns a 403 error when you switch to a remote node.
**Checks in order:**
1. **Is your primary instance licensed?** Go to **Settings > License** on the primary instance and verify it shows an active Skipper or Admiral license. Remote nodes inherit the primary's tier — if the primary is on Community, all remote nodes will be Community too.
1. **Is your primary instance licensed?** Open **Profile > Settings > License** on the primary instance and verify it shows an active Skipper or Admiral license. Remote nodes inherit the primary's tier; if the primary is on Community, all remote nodes will be Community too.
2. **Is the remote node's token valid?** An expired or revoked token prevents the license tier from being transmitted. Regenerate the token on the remote instance and update the node config on the primary.
3. **Is the remote node running an up-to-date version of Sencho?** Distributed license enforcement requires both the primary and remote instances to be on v0.34.0 or later. Update the remote node if it's on an older version.
3. **Is the remote node running an up-to-date version of Sencho?** Distributed license enforcement requires both the primary and remote instances to be on a compatible version. Update the remote node if it's outdated.
4. **Are you accessing the remote node directly?** If you navigate directly to the remote Sencho instance's URL (bypassing the primary), it uses its own local license. License inheritance only works through the primary's proxy.
---
## Forgotten admin password
Sencho has no password recovery flow. To reset the password:
1. Stop the Sencho container
2. Connect to the SQLite database directly:
```bash
sqlite3 /path/to/data/sencho.db
```
3. Delete the existing credentials so Sencho re-enters first-boot setup mode:
```sql
DELETE FROM global_settings WHERE key IN ('auth_username', 'auth_password_hash', 'auth_jwt_secret');
```
4. Restart the container - the setup screen will appear on next visit.
<Warning>
This resets authentication entirely. All active sessions become invalid. Your stacks, nodes, and alert rules are not affected.
</Warning>
---
## Scan stacks folder doesn't find my stacks
**Symptom:** You placed Docker Compose files in the stacks directory and clicked the scan button, but "No new stacks found" appears.
**Checks in order:**
1. **Is the compose file in a subdirectory?** Sencho only discovers stacks inside subdirectories of `COMPOSE_DIR`. A loose `compose.yaml` sitting directly in the root of `COMPOSE_DIR` is ignored — each stack must be in its own folder (e.g. `COMPOSE_DIR/my-app/compose.yaml`).
1. **Is the compose file in a subdirectory?** Sencho only discovers stacks inside subdirectories of `COMPOSE_DIR`. A loose `compose.yaml` sitting directly in the root of `COMPOSE_DIR` is ignored. Each stack must be in its own folder (e.g. `COMPOSE_DIR/my-app/compose.yaml`).
2. **Is the compose file named correctly?** Sencho recognizes these filenames only:
- `compose.yaml`
@@ -194,25 +189,15 @@ DELETE FROM global_settings WHERE key IN ('auth_username', 'auth_password_hash',
---
## Network creation fails with "name is required"
## Network creation fails
**Symptom:** Clicking Create in the Create Network dialog returns an error about a missing name.
**Symptom:** Clicking **Create** in the Create Network dialog returns an error about a missing or invalid name.
**Cause:** The network name field was left empty or contains only whitespace.
**Rules for network names:**
**Fix:** Enter a valid network name. Names must be non-empty and can contain letters, numbers, hyphens (`-`), underscores (`_`), and dots (`.`). Names cannot start with a dot or hyphen.
---
## Network creation fails with "invalid name"
**Symptom:** You enter a network name but the API rejects it as invalid.
**Cause:** The name contains characters that are not allowed, or starts with a special character.
**Allowed characters:** Letters, numbers, hyphens, underscores, and dots. The name must start with a letter, number, or underscore.
**Examples:**
- Names must be non-empty and cannot contain only whitespace.
- Allowed characters: letters, numbers, hyphens (`-`), underscores (`_`), and dots (`.`).
- Names must start with a letter, number, or underscore. They cannot start with a dot or hyphen.
| Name | Valid? | Reason |
|------|--------|--------|
@@ -229,25 +214,29 @@ DELETE FROM global_settings WHERE key IN ('auth_username', 'auth_password_hash',
**Symptom:** The delete button is missing or disabled for certain networks.
**Expected behavior:** Docker system networks (`bridge`, `host`, `none`) cannot be deleted — they are created by the Docker daemon and are required for normal operation. Sencho intentionally hides the delete action for these networks.
**Expected behavior:** Docker system networks (`bridge`, `host`, `none`) cannot be deleted. They are created by the Docker daemon and are required for normal operation. Sencho intentionally hides the delete action for these networks.
If you need to clean up unused *user-created* networks, use the **Prune Networks** button at the top of the Networks tab.
If you need to clean up unused *user-created* networks, use the **Prune Dead Networks** button in the Quick Clean section at the top of the Resources page.
---
## Network inspect shows "Network not found"
**Symptom:** Clicking the inspect (eye) icon on a network row returns a "not found" error.
**Symptom:** Clicking the inspect icon (eye) on a network row returns a "not found" error.
**Cause:** The network was deleted between the time the list loaded and when you clicked inspect. This can happen if another user or an external tool removed the network.
**Fix:** Refresh the Resources page to reload the current network list.
**Fix:** Switch to a different tab and back (or click another nav item and return to Resources) to reload the network list.
---
## Network topology is empty
**Symptom:** The Topology tab shows "No user-created networks found" even though you have running containers.
**Symptom:** Switching to the **Topology** view mode on the Networks tab shows "No user-created networks found" even though you have running containers.
<Note>
Network Topology requires a Skipper or Admiral license.
</Note>
**Possible causes:**
@@ -272,6 +261,120 @@ After deploying, the topology will show these networks and their connected conta
---
## "Open App" doesn't appear in the context menu
**Symptom:** You right-click a stack in the sidebar but "Open App" is not listed.
**Cause:** The **Open App** option only appears when both conditions are met:
1. The stack is **running** (status shows UP).
2. At least one container in the stack has a **published port** (a port mapped to the host).
If your container uses host networking, doesn't expose ports, or only binds to internal Docker networks, the option won't appear. You can still access the app manually by checking the container's port mappings in the stack detail view.
---
## Remote update button does not appear
**Symptom:** A remote node in Fleet View has no **Update** button even though it is running an older version.
**Cause:** The remote node does not advertise the `self-update` [capability](/features/node-compatibility). This happens when the node is not running inside a Docker Compose-managed container, or the Docker socket is not mounted.
**Fix:** Ensure the remote node's `docker-compose.yml` includes the socket volume mount:
```yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock
```
Nodes running very old Sencho versions that predate the capability system need to be updated manually first. After that, future updates can be triggered from the dashboard.
---
## Remote update times out
**Symptom:** After clicking **Update** on a remote node, the status changes to **Timed out** instead of **Updated**.
**Cause:** The image pull may be slow on the remote host, or the container failed to restart.
**Fix:** Check the Docker logs on the remote host for errors. You can also update manually by running:
```bash
docker compose pull && docker compose up -d
```
---
## Stack labels are not visible in the sidebar
**Symptom:** You assigned labels to stacks but no label pills appear in the sidebar.
**Checks:**
1. **License tier**: Labels require a Skipper or Admiral license. Verify your tier in **Profile > Settings > License**.
2. **At least one label must exist**: Labels are managed in **Profile > Settings > Labels**. Create at least one label before assigning it to stacks.
3. **Downgrade**: If you downgraded from a paid tier to Community, the label UI is hidden but your data is preserved. Upgrading again restores all labels and assignments.
---
## Notification routing rule matches but alerts still go to global channels
**Symptom:** You created a routing rule for a stack, but alerts from that stack still arrive on the global Discord/Slack/Webhook channels.
**Checks:**
1. **Stack name match**: The stack name in the routing rule must match exactly. Stack names are case-sensitive and correspond to the directory name in your compose folder.
2. **Rule is enabled**: Check that the route's toggle is turned on in **Profile > Settings > Routing**.
3. **License tier**: Notification Routing requires an Admiral license. Skipper and Community users can only use global channels.
---
## LDAP connection refused
**Symptom:** Enabling LDAP SSO and testing the connection fails with a connection error.
**Fix:** Verify the LDAP server is reachable from the Sencho container. If LDAP is on the host machine, use `host.docker.internal` (Docker Desktop) or the host's LAN IP address, not `localhost`.
---
## TLS certificate errors (LDAP)
**Symptom:** LDAP connection test fails with a TLS/certificate error.
**Fix:** If your LDAP server uses a self-signed certificate, toggle off "Verify TLS certificate" in **Profile > Settings > SSO**. For production, install a trusted certificate instead.
---
## OAuth callback URL mismatch
**Symptom:** After authenticating with Google, GitHub, or Okta, the provider returns a "redirect URI mismatch" error.
**Fix:** The redirect URI registered in your identity provider must exactly match what Sencho sends. Check:
1. `SSO_CALLBACK_URL` is set to your external URL (e.g., `https://sencho.example.com`)
2. The callback URL in your provider's settings is `https://sencho.example.com/api/auth/sso/oidc/<provider>/callback`
3. Protocol matches: don't mix `http` and `https`
---
## SSO buttons not appearing on login page
**Symptom:** You configured an SSO provider but the login page shows no SSO buttons.
**Cause:** SSO providers only appear on the login page when they are both **configured** (saved with valid credentials) and **enabled** (toggle is on).
**Fix:** Open **Profile > Settings > SSO** and verify the provider has an **Active** badge and its toggle is enabled.
---
## "Check for updates" shows rate-limit error
**Symptom:** Clicking "Check for updates" shows a toast error about waiting before checking again.
**Cause:** Manual update checks are rate-limited to prevent excessive requests to container registries. The cooldown between manual checks is 2 minutes. Wait for it to elapse before checking again. Automatic background checks run every 6 hours regardless of this limit.
---
## Checking the health endpoint
Sencho exposes a health endpoint for monitoring and container health checks:
@@ -294,20 +397,3 @@ docker logs -f sencho
```
The backend logs all route errors and service failures to stdout. This is the first place to look when the UI shows an error with no useful message.
## "Open App" doesn't appear in the context menu
**Symptom:** You right-click a stack in the sidebar but "Open App" is not listed.
**Cause:** The **Open App** option only appears when both conditions are met:
1. The stack is **running** (status shows UP).
2. At least one container in the stack has a **published port** (a port mapped to the host).
If your container uses host networking, doesn't expose ports, or only binds to internal Docker networks, the option won't appear. You can still access the app manually by checking the container's port mappings in the stack detail view.
## "Check for updates" shows rate-limit error
**Symptom:** Clicking "Check for updates" shows a toast error about waiting before refreshing.
**Cause:** Manual update checks are rate-limited to prevent excessive requests to container registries. Wait for the cooldown period to elapse before checking again. Automatic background checks run every 6 hours regardless of this limit.
docs/operations/upgrade.mdx
+18 -14
View File
@@ -22,20 +22,22 @@ docker stop sencho && docker rm sencho
Sencho will apply any necessary database migrations automatically on startup. No manual steps are required.
<Note>
Skipper and Admiral users can also update remote nodes directly from the Fleet View. See [Remote Updates](/features/remote-updates) for details.
</Note>
---
## Automatic migrations
Sencho handles all schema changes internally. When the application starts, it runs a series of migration checks:
Sencho handles all schema changes internally. When the application starts, it checks whether the database needs updating and applies any pending migrations automatically. This covers:
- **Schema evolution** — New columns are added via `ALTER TABLE ADD COLUMN`. If a column already exists, the operation is silently skipped.
- **Legacy config migration** — If upgrading from a very early version that used a `sencho.json` file, the settings are automatically imported into SQLite.
- **Admin account migration** — Legacy admin credentials stored in `global_settings` are migrated to the `users` table.
- **Encryption migration** — Unencrypted node API tokens are automatically encrypted at rest using AES-256-GCM.
- **SSO columns** — SSO provider fields are added to the users table if not present.
- **Registry tables** — Private registry storage tables are created if they don't exist.
- **RBAC tables** — Role assignment tables are created for granular permissions.
- **Legacy cleanup** — Obsolete columns from pre-0.7 versions (SSH/TLS fields) are dropped.
- **New tables and columns** for features introduced in newer versions
- **Legacy config migration** from very early versions that used a JSON config file
- **Admin account migration** from single-admin storage to the multi-user system
- **Encryption of sensitive values** (node API tokens, registry credentials) that were previously stored in plaintext
- **SSO and RBAC setup** for single sign-on provider config and role-based access
- **Legacy cleanup** of obsolete fields from pre-0.7 versions (SSH/TLS columns)
You never need to run SQL commands, migration scripts, or any manual database operations.
@@ -43,10 +45,12 @@ You never need to run SQL commands, migration scripts, or any manual database op
## Backup before upgrading
Always back up your data directory before upgrading. If something goes wrong, restoring from backup is the only recovery path — Sencho does not support downgrading or rolling back database migrations.
Always back up your data directory before upgrading. If something goes wrong, restoring from backup is the only recovery path. Sencho does not support downgrading or rolling back database migrations.
```bash
sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho-pre-upgrade.db'"
# Copy both the database and the encryption key
cp /path/to/sencho-data/sencho.db /path/to/backup/sencho-pre-upgrade.db
cp /path/to/sencho-data/encryption.key /path/to/backup/encryption-pre-upgrade.key
```
See the [Backup & Restore guide](/operations/backup) for full backup procedures.
@@ -58,7 +62,7 @@ See the [Backup & Restore guide](/operations/backup) for full backup procedures.
If you prefer to control exactly which version you run, pin the image tag in your `docker-compose.yml`:
```yaml
image: saelix/sencho:0.25.3
image: saelix/sencho:0.38.0
```
Check [GitHub Releases](https://github.com/AnsoCode/Sencho/releases) for available versions and changelogs.
@@ -71,8 +75,8 @@ Sencho follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`):
| Change type | Version bump | Example |
|-------------|-------------|---------|
| Bug fixes, performance improvements | Patch | 0.25.0 → 0.25.1 |
| New features | Minor | 0.25.x → 0.26.0 |
| Bug fixes, performance improvements | Patch | 0.38.0 → 0.38.1 |
| New features | Minor | 0.38.x → 0.39.0 |
| Breaking changes | Major | 0.x.y → 1.0.0 |
<Note>