mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
25586fc8ab
* feat(ui): add Classic, Smart, and Compact desktop navigation styles Introduce a shared app-nav registry and reachable model so TopBar, the command palette, and mobile menus share one destination source. Smart bar is the default; Appearance gains a Navigation subsection with quick links. * fix(e2e): stop clearing top-nav prefs on every reload The desktop-navigation suite used addInitScript to wipe mode storage, which re-ran on reload and undid the classic/compact values under test. * fix(ui): harden nav PR docs and Compact quick-link coverage Drop the partial docs-refresh import that left missing image assets and a stale Display screenshot, keep navigation-scoped operator docs against main, and add an E2E path that proves Compact quick-link add, persist, and render after reload. * fix(ui): polish Compact quick links and menu mastheads Align Smart/Compact menus with Theme chrome, keep pin labels always visible, and drive add capacity from persisted pins (max five) with a trailing + picker and per-pin remove. * test(e2e): exact-match Compact Networking pin locator Avoid Playwright strict-mode clash with Actions for Networking. * fix(ui): simplify Compact quick link removal and fix + button trailing Remove the (...) dropdown per quick link in Compact mode. Right-click context menu remains as the sole on-bar removal affordance. Fix the + add-button to trail quick links rather than pinning to the far right by removing flex-1 from the quick-link rail.
135 lines
8.4 KiB
Plaintext
135 lines
8.4 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, baseline top navigation includes **Home**, **Resources**, **Networking**, **Security**, and **App Store**. **Fleet** appears when your role can read nodes. **Logs**, **Update**, and **Schedules** appear for admins. **Console** and **Audit** depend on license, role, and whether those surfaces are enabled; hub-only views are hidden when a remote node is active. Desktop presentation (Classic bar, Smart bar, or Compact launcher) is chosen under **Settings → Appearance → Navigation**. 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>
|