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

docs: add Tier 3 reference and operations pages

Browse Source 
- reference/settings: complete settings hub reference (all 7 tabs —
  Account, System Limits, Notifications, Appearance, Developer, Nodes,
  App Store)
- operations/troubleshooting: 1:1 path rule failures, Docker socket
  permissions, login errors, WebSocket proxy config, offline remote
  nodes, password reset, health endpoint, container logs
- operations/backup: what to back up (DATA_DIR SQLite + COMPOSE_DIR),
  hot backup via sqlite3, cron example, restore steps, host migration
  walkthrough
- mint.json: populate Reference and Operations nav groups
This commit is contained in:
SaelixCode
2026-03-22 23:25:15 -04:00
parent 7c120c671c
commit 932e7780ea
5 changed files with 436 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations/backup.mdx
+139
View File
@@ -0,0 +1,139 @@
---
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.
---
## What to back up
### 1. Data directory (`DATA_DIR`)
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
This single file is everything Sencho knows about itself. Back it up and you can fully restore any Sencho installation.
### 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.
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.
---
## Backing up
### Simple file copy
```bash
# Stop Sencho to ensure the SQLite WAL is flushed (recommended but not strictly required)
docker stop sencho
# Copy the data directory
cp -r /path/to/sencho-data /path/to/backup/sencho-data-$(date +%Y%m%d)
# Copy compose stacks
cp -r /opt/compose /path/to/backup/compose-$(date +%Y%m%d)
# Restart
docker start sencho
```
### SQLite online backup (without stopping)
SQLite supports hot backups via its `.backup` command. This is safe to run while Sencho is running:
```bash
sqlite3 /path/to/sencho-data/sencho.db ".backup '/path/to/backup/sencho.db'"
```
### 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
```
This backs up the database at 3 AM daily and deletes backups older than 30 days.
---
## Restoring
### Restore from backup
1. Stop Sencho:
```bash
docker stop sencho
```
2. Replace the data directory with your backup:
```bash
rm -rf /path/to/sencho-data/*
cp /path/to/backup/sencho.db /path/to/sencho-data/sencho.db
```
3. Restore your compose directory if needed:
```bash
cp -r /path/to/backup/compose /opt/compose
```
4. Start Sencho:
```bash
docker start sencho
```
Sencho will read the restored database and resume with all your previous settings, nodes, and alert rules intact.
---
## Migrating to a new host
### Step 1: Prepare the new host
Install Docker and Docker Compose on the new machine. Create the same directory structure you use for your compose files, following the [1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule).
### Step 2: Copy data
Transfer your backup files to the new host:
```bash
scp -r /path/to/sencho-data newhost:/path/to/sencho-data
scp -r /opt/compose newhost:/opt/compose
```
### Step 3: Deploy Sencho on the new host
Use the same `docker-compose.yml` you used on the old host (with the same `COMPOSE_DIR` and `DATA_DIR` paths):
```bash
docker compose up -d
```
### Step 4: Update remote node references
If other Sencho instances were pointing to your old host as a remote node, update their node config to use the new host's IP or hostname. Generate a new API token on the restored instance and distribute it.
### Step 5: Verify
- Log in and confirm your stacks, nodes, and alerts are all present
- Check that at least one stack deploys correctly
- Verify the node switcher shows the expected nodes with green status
---
## What is NOT backed up by this process
| 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 |
| 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/troubleshooting.mdx
+163
View File
@@ -0,0 +1,163 @@
---
title: Troubleshooting
description: Solutions to the most common Sencho setup and runtime problems.
---
## Containers won't start after deploy
**Symptom:** You click Deploy and containers immediately exit or never appear.
**Check:** Open the [Host Console](/features/host-console) and run:
```bash
docker compose -f /path/to/your/stack/compose.yaml logs
```
The most common causes:
- **Missing environment variable** — a required variable in your `.env` file is empty or has the wrong name.
- **Port already in use** — another container or host process is bound to the same port. Change the host port in the compose file.
- **Volume path does not exist** — a bind-mount path on the host doesn't exist yet. Create the directory manually.
---
## The 1:1 path rule — volumes resolve to wrong paths
**Symptom:** Stacks deploy but relative volume paths (e.g. `./config:/config`) point to the wrong location inside the container, or `docker compose` exits with a path error.
**Cause:** Your `COMPOSE_DIR` is mounted at a different path inside the Sencho container than it has on the host.
**Fix:** Your compose volume mount and `COMPOSE_DIR` environment variable must use the **same absolute path** on both sides:
```yaml
# docker-compose.yml for Sencho itself
volumes:
- /opt/docker:/opt/docker # same path inside and outside
environment:
- COMPOSE_DIR=/opt/docker
```
See [Configuration — the 1:1 path rule](/getting-started/configuration#compose-directory-the-11-path-rule) for a full explanation.
---
## "Permission denied" on the Docker socket
**Symptom:** Sencho starts but shows errors accessing Docker, or the stack list is empty even though containers exist.
**Cause:** The Sencho container cannot read `/var/run/docker.sock`.
**Fix:** Ensure the socket is mounted:
```yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock
```
On Linux, the Docker socket is owned by the `docker` group. The Sencho entrypoint detects the socket's GID automatically and adds the internal `sencho` user to the matching group. If you see permission errors despite a correct mount, check that the socket file is readable:
```bash
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.
---
## Login page shows "Something went wrong"
**Symptom:** You enter credentials and get a generic error instead of being logged in.
**Possible causes and fixes:**
| Cause | Fix |
|-------|-----|
| `JWT_SECRET` is not set or is empty | Set a non-empty value for `JWT_SECRET` in your environment |
| Container restarted and session cookie is stale | Clear browser cookies for the Sencho domain and try again |
| Rate limit triggered (5 failed attempts in 15 min) | Wait 15 minutes, or restart the container to reset the limiter |
---
## 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.
**Cause:** A reverse proxy is not forwarding WebSocket upgrade headers.
**Fix:** Add WebSocket support to your proxy config:
```nginx
# Nginx
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
```
Traefik handles WebSocket upgrades automatically for HTTP/1.1 backends — no extra config needed.
---
## Remote node shows "Offline" or "Unknown"
**Symptom:** A node you added shows a red or gray status dot.
**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`.
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.
---
## 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>
---
## Checking the health endpoint
Sencho exposes a health endpoint for monitoring and container health checks:
```bash
curl http://localhost:3000/api/health
# {"status":"ok","uptime":12345.67}
```
A `200` response confirms the backend is running. Use this endpoint in your uptime monitor or load balancer health check.
---
## Getting logs from the Sencho container itself
```bash
docker logs sencho
# or, to follow:
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.