mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
ba2e7bded9
* feat: add compose discovery for setup preflight and sidebar empty state Expose read-only compose discovery via GET /api/stacks/discovery and setup diagnostics. Replace the blank sidebar with path-aware discovery and move adopt into a dedicated dialog with a three-tab Create Stack flow. * test: assert post-setup handoff via sessionStorage read-back The Setup preflight test spied on Storage.prototype.setItem to check the post-setup adopt handoff. When the jsdom storage probe fails and the test harness swaps in its in-memory storage stub (which does not extend Storage), that stub's setItem never touches Storage.prototype, so the spy records zero calls and the assertion fails even though the component wrote the value. Read the value back with sessionStorage.getItem instead, matching how every other storage test in the suite asserts. This is robust to both the native jsdom storage and the in-memory fallback. * fix(setup): surface compose discovery as a preflight check row Drop the Setup discovery banner and non-working Review button. Show counts as a pass row in EnvironmentChecks (Setup only) and keep Enter Sencho as the handoff that opens adopt when candidates exist. * test(setup): cover zero-count discovery row omission * fix(stacks): widen adopt scan to any yaml and rename into place Homelab layouts often use nginx.yml or plex.yml. Surface those for adopt (except overrides), rename to compose.yaml on move so stacks register, and reset the confirm UI when a move fails.
135 lines
8.2 KiB
Plaintext
135 lines
8.2 KiB
Plaintext
---
|
|
title: Quickstart
|
|
description: Get Sencho running in under five minutes.
|
|
---
|
|
|
|
This walks you from a clean Docker host to a working Sencho console. Five minutes if your Compose directory is already in the right place, ten if you need to lay it out first.
|
|
|
|
<Note>
|
|
Sencho is used in production for day-to-day Docker Compose and fleet management. As a pre-1.0 project it still evolves quickly, so review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and validate against your own setup before deploying it on critical infrastructure.
|
|
</Note>
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose installed on the host.
|
|
- A directory where your Compose projects live (for example `/opt/compose`). Each subdirectory inside becomes one stack in Sencho.
|
|
|
|
<Warning>
|
|
Sencho needs the Docker socket to manage containers. Mounting `/var/run/docker.sock` gives Sencho the same level of Docker control as an operator running Docker commands on the host. For exposed or shared environments, put Sencho behind a TLS-terminating reverse proxy and restrict who can sign in. See [Self-hosting](/operations/self-hosting) for the operational guidance.
|
|
</Warning>
|
|
|
|
## Run with Docker Compose
|
|
|
|
Drop this into a `docker-compose.yml` next to your Compose tree, or anywhere convenient, and bring it up:
|
|
|
|
```yaml
|
|
services:
|
|
sencho:
|
|
image: saelix/sencho:latest
|
|
container_name: sencho
|
|
restart: unless-stopped
|
|
ports:
|
|
- "1852:1852"
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock
|
|
- /opt/compose:/opt/compose # 1:1 path rule, see below
|
|
- sencho_data:/app/data
|
|
environment:
|
|
- COMPOSE_DIR=/opt/compose
|
|
|
|
volumes:
|
|
sencho_data:
|
|
```
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
<Accordion title="Prefer docker run?">
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name sencho \
|
|
--restart unless-stopped \
|
|
-p 1852:1852 \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
-v /opt/compose:/opt/compose \
|
|
-v sencho_data:/app/data \
|
|
-e COMPOSE_DIR=/opt/compose \
|
|
saelix/sencho:latest
|
|
```
|
|
|
|
</Accordion>
|
|
|
|
<Tip>
|
|
Sencho is mirrored on GitHub Container Registry at `ghcr.io/studio-saelix/sencho:latest` with the same tags and digests as Docker Hub. Pull from whichever registry your environment prefers.
|
|
</Tip>
|
|
|
|
<Note>
|
|
`JWT_SECRET` is generated on first boot and persisted to the database. You do not need to provide one.
|
|
</Note>
|
|
|
|
## The 1:1 path rule
|
|
|
|
The Compose directory must be mounted at the **same path** inside and outside the container. The example above mounts `/opt/compose` to `/opt/compose`, which is correct. If your stacks live somewhere else, adjust both sides of the mount to match.
|
|
|
|
<Warning>
|
|
This is the most common source of deployment problems. If the host and container paths differ, every relative volume in your Compose files will resolve to the wrong location once Sencho asks Docker to bring a stack up. See the [Configuration guide](/getting-started/configuration#compose-directory-the-11-path-rule) for the full explanation.
|
|
</Warning>
|
|
|
|
## First boot
|
|
|
|
Open `http://localhost:1852` in a browser. On a fresh install you land on the **Cold start** card, where Sencho asks you to create the first admin account.
|
|
|
|
<Frame>
|
|
<img src="/images/quickstart/setup-cold-start.png" alt="Sencho first-boot Cold start card with Username, Password, and Confirm password fields, a password strength indicator, and an Initialize console button" />
|
|
</Frame>
|
|
|
|
Pick a username, choose a password, confirm it, and click **Initialize console**. The username placeholder shows `admin`. The password must be at least eight characters, and the strength indicator labels the password **Weak**, **Fair**, or **Strong** as you type.
|
|
|
|
Sencho then runs a short **environment preflight**: it confirms the Docker engine and Compose plugin are reachable, the compose directory is writable and mounted at a matching host path, the dashboard is behind TLS, and there is disk headroom. Anything that needs attention shows an inline fix. The checks never block you, so click **Enter Sencho** to continue; you can re-run them anytime from **Settings · Recovery**.
|
|
|
|
<Frame>
|
|
<img src="/images/quickstart/setup-environment.png" alt="Sencho first-boot environment preflight with check rows for Docker engine, Docker Compose, Compose directory, path mapping, TLS, and disk space, each showing a pass or warning status with inline remediation text, a Re-run button, and an Enter Sencho button" />
|
|
</Frame>
|
|
|
|
<Note>
|
|
The Cold start card only appears the first time you open Sencho. Once the admin account exists, every subsequent visit goes to the regular sign-in screen.
|
|
</Note>
|
|
|
|
## After signing in
|
|
|
|
You land on **Home**, the default operational view. The health masthead reports **Healthy**, **Degraded**, or **Critical**, names the active node, shows how many nodes are registered, and lists any signals that need attention. The resource gauge strip tracks **CPU**, **Memory**, **Disk**, and **Network** with sparklines and threshold coloring. **Stack health** lists the active node's stacks, sorted by state then load, with uptime, CPU, memory, and a 10-minute CPU sparkline per row.
|
|
|
|
<Frame>
|
|
<img src="/images/quickstart/dashboard.png" alt="Sencho Home view with the health masthead, resource gauges with sparklines, Stack health table, Configuration Status, Fleet Heartbeat panel, and Recent Alerts" />
|
|
</Frame>
|
|
|
|
Below the stack table, **Configuration Status** summarizes notifications, alerts, automation, security, backups, thresholds, and crash detection. The neighboring activity card shows **Fleet Heartbeat** when remote nodes exist, or **Stack Restarts (7d)** on a local-only install. **Recent Alerts** shows the latest notification feed and includes **Clear All Notifications** when there is anything to clear.
|
|
|
|
On the local node, the top navigation includes **Home**, **Fleet**, **Resources**, **Security**, **App Store**, and **Logs**. Depending on license, role, and node context, it can also include **Update**, **Schedules**, **Console**, and **Audit**; hub-only views are hidden when a remote node is active. The right side of the top bar holds global search, notifications, and the profile menu entries **Settings**, **Documentation**, **Feedback**, **Appearance**, and **Log Out**.
|
|
|
|
The left sidebar is the stack workspace. Below the Sencho brand, it starts with the node switcher, then **Create Stack**, a bulk-mode toggle, and **Scan stacks folder** for re-indexing compose projects added outside Sencho. Use **Search stacks...** with the **All**, **Up**, **Down**, and **Updates** chips to narrow the list. On a fresh install with an empty stack list, Sencho scans your mounted compose directory automatically and shows what it found, including compose files that still need to be adopted into their own subfolder.
|
|
|
|
Click **Create Stack** in the sidebar and choose **Empty**, **From Git**, or **From Docker Run**. Use **Adopt existing files** when Sencho finds compose files that are loose at the compose directory root or one folder too deep (any `.yml` / `.yaml`, not only `compose.yaml`). Loose root files are also auto-promoted into stack folders on the next Sencho restart; adopt is the guided path especially for nested placements. Open **App Store** for a template-driven deploy flow. Once a stack exists, select it in the sidebar or in **Stack health** to open the stack workspace with container health, logs, files, compose editing, and stack actions.
|
|
|
|
## Where to next
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Configuration" icon="sliders" href="/getting-started/configuration">
|
|
Environment variables, volume mounts, reverse proxy, and the 1:1 path rule in detail.
|
|
</Card>
|
|
<Card title="Stack management" icon="layer-group" href="/features/stack-management">
|
|
Deploy, edit, restart, update, and roll back stacks from the stack workspace.
|
|
</Card>
|
|
<Card title="Multi-node" icon="server" href="/features/multi-node">
|
|
Add a remote Sencho instance and manage it from the same console.
|
|
</Card>
|
|
<Card title="App Store" icon="grid-2" href="/features/app-store">
|
|
Browse the default LinuxServer.io template catalogue and deploy in one click.
|
|
</Card>
|
|
<Card title="Recovery" icon="life-ring" href="/operations/recovery">
|
|
What to do if Sencho, a deploy, sign-in, Docker, or a node fails, and how to get back to a working state.
|
|
</Card>
|
|
</CardGroup>
|