mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
5289f01bfd
* feat(onboarding): add first-run environment checker Add a preflight that checks whether the host can run Docker deploys before a deploy fails for an avoidable reason. It verifies the Docker engine is reachable and permitted, the Compose plugin is present, the compose directory is writable and mounted at a matching host path, the dashboard is behind TLS, and the compose volume has disk headroom. Each result that needs attention carries a specific fix rather than a generic error, and the checks never block: an operator who knows their setup can continue. The checks run as the final step of first-boot setup and can be re-run any time from the Recovery settings tab. A new admin-only endpoint, GET /api/diagnostics/environment, backs both surfaces. * fix(onboarding): distinguish unverified path mapping and support parent binds Treat a container whose self-inspect fails as an unverified path-mapping warning instead of a false "not containerized" pass, so an unverifiable mapping never reads as healthy. Resolve the compose directory through the longest-prefix bind mount and compare the host path it resolves to, so a parent bind such as -v /opt:/opt correctly covers COMPOSE_DIR=/opt/compose instead of warning that the directory is not bind-mounted. * test(e2e): advance the setup wizard past the environment step in loginAs The first-run setup helper clicked "Initialize console" and immediately waited for the dashboard, but setup now shows an environment-preflight step before landing the console. Click "Enter Sencho" to complete onboarding before asserting the dashboard, so the first test on a fresh instance passes.
123 lines
5.4 KiB
Plaintext
123 lines
5.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 cockpit. Five minutes if your Compose directory is already in the right place, ten if you need to lay it out first.
|
|
|
|
<Note>
|
|
Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and avoid deploying it blindly on critical infrastructure without testing in their own environment first.
|
|
</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.
|
|
|
|
## 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, and an Initialize console button" />
|
|
</Frame>
|
|
|
|
Pick a username (the placeholder shows `admin`), choose a password, confirm it, and click **Initialize console**. The strength indicator under the password field expects at least eight characters.
|
|
|
|
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**.
|
|
|
|
<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 the dashboard. A status bar across the top tells you whether the fleet is healthy, the gauge strip below it shows CPU, memory, disk, and network at a glance, and the **Stack health** table sorts your stacks by load.
|
|
|
|
<Frame>
|
|
<img src="/images/quickstart/dashboard.png" alt="Sencho dashboard with status bar across the top, CPU/MEMORY/DISK/NETWORK gauges, and a Stack health table sorted by load" />
|
|
</Frame>
|
|
|
|
The top nav (HOME, FLEET, RESOURCES, APP STORE, LOGS, AUTO-UPDATE, CONSOLE, AUDIT, SCHEDULES) is your map of the cockpit. The sidebar on the left lists every stack Sencho discovered under `COMPOSE_DIR`; on a fresh install it is empty until you create one.
|
|
|
|
Click **Create Stack** in the sidebar to deploy your first stack, or open **App Store** in the top nav for a one-click template.
|
|
|
|
## 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 cockpit.
|
|
</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 190+ pre-configured templates 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>
|