mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
7d9dcc77d4
- Fix Cyrillic character in quickstart image ref and correct registry to Docker Hub (saelix/sencho) - Correct backup guide WAL references (Sencho uses SQLite default journal mode) - Add SSL/TLS reverse proxy examples for Nginx, Traefik, and new Caddy configuration - Add missing env vars (PORT, DATA_DIR, NODE_ENV, FRONTEND_URL, SSO_LDAP_DISPLAY_NAME) to .env.example - Add upgrade & migration guide documenting automatic schema migrations - Add self-hosting best practices (1:1 path rule, Docker socket security, resource recs) - Add architecture overview (system design, request flow, database schema, multi-node model) - Add development & contributor guide (setup, tests, code style, PR workflow) - Update OpenAPI spec from v0.23.0 to v0.25.3 with Registries and Image Updates endpoints - Update docs.json navigation with all new pages and API groups
137 lines
3.9 KiB
Plaintext
137 lines
3.9 KiB
Plaintext
---
|
|
title: Development Guide
|
|
description: Set up a local development environment and contribute to Sencho.
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **Node.js 22** or later
|
|
- **Docker** and **Docker Compose** installed and running
|
|
- **Git**
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/AnsoCode/Sencho.git
|
|
cd Sencho
|
|
|
|
# Install backend dependencies
|
|
cd backend && npm install
|
|
|
|
# Install frontend dependencies
|
|
cd ../frontend && npm install
|
|
```
|
|
|
|
---
|
|
|
|
## Running in development
|
|
|
|
Open two terminal windows:
|
|
|
|
**Terminal 1 — Backend** (Express + nodemon, port 3000):
|
|
|
|
```bash
|
|
cd backend
|
|
npm run dev
|
|
```
|
|
|
|
**Terminal 2 — Frontend** (Vite dev server, port 5173):
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
|
|
The Vite dev server proxies all `/api` and `/ws` requests to `localhost:3000`, so you access the app at `http://localhost:5173`.
|
|
|
|
On first boot, you'll see a setup screen to create an admin account.
|
|
|
|
<Note>
|
|
The backend requires a Docker socket to be available. On macOS and Linux this is `/var/run/docker.sock`. On Windows, ensure Docker Desktop is running.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Running tests
|
|
|
|
### Backend unit tests (Vitest)
|
|
|
|
```bash
|
|
cd backend
|
|
npm test
|
|
```
|
|
|
|
Runs all test files in `src/__tests__/`. Each test file runs in an isolated forked process with its own database instance.
|
|
|
|
### End-to-end tests (Playwright)
|
|
|
|
```bash
|
|
# From the project root
|
|
npm run test:e2e
|
|
```
|
|
|
|
E2E tests run against a live development instance (backend on port 3000, frontend on port 5173). Make sure both are running before executing tests.
|
|
|
|
For interactive test debugging:
|
|
|
|
```bash
|
|
npm run test:e2e:ui
|
|
```
|
|
|
|
---
|
|
|
|
## Code style
|
|
|
|
- **TypeScript** with `strict: true` in both packages. No `any` casts or `@ts-ignore`.
|
|
- **ESLint 9** flat config. Run `npm run lint` in both `backend/` and `frontend/` directories.
|
|
- **Frontend styling:** Tailwind CSS with [shadcn/ui](https://ui.shadcn.com/) components. See the design system section in `CLAUDE.md` for color, typography, and component patterns.
|
|
- **Backend patterns:** Express route handlers in `src/index.ts`, business logic in `src/services/`. All new endpoints must use `authMiddleware`. SQL must use parameterized queries.
|
|
|
|
---
|
|
|
|
## Pull request workflow
|
|
|
|
1. Create a branch from `main` (e.g. `feat/my-feature`, `fix/my-bug`)
|
|
2. Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages:
|
|
- `feat:` — new user-facing feature (bumps minor version)
|
|
- `fix:` — bug fix (bumps patch version)
|
|
- `docs:` — documentation changes (no version bump)
|
|
- `chore:`, `ci:`, `refactor:`, `test:`, `perf:` — internal changes (no version bump)
|
|
3. Update `CHANGELOG.md` under `## [Unreleased]` for user-facing changes
|
|
4. Update or create documentation in `/docs` if behavior changes
|
|
5. Open a PR targeting `main`
|
|
6. Ensure CI passes before requesting review
|
|
|
|
Keep PRs focused — one feature or fix per PR.
|
|
|
|
---
|
|
|
|
## Project structure
|
|
|
|
```
|
|
Sencho/
|
|
├── backend/ # Express.js API + Docker orchestration
|
|
│ ├── src/
|
|
│ │ ├── index.ts # Route definitions (monolithic)
|
|
│ │ ├── services/ # Business logic (17 services)
|
|
│ │ └── __tests__/ # Vitest unit tests
|
|
│ └── package.json
|
|
├── frontend/ # React 19 + Vite SPA
|
|
│ ├── src/
|
|
│ │ ├── components/ # UI components
|
|
│ │ ├── context/ # React context providers
|
|
│ │ ├── lib/ # Utilities (apiFetch, etc.)
|
|
│ │ └── App.tsx # Root router
|
|
│ └── package.json
|
|
├── docs/ # Mintlify documentation site
|
|
├── e2e/ # Playwright E2E test specs
|
|
├── Dockerfile # Multi-stage production build
|
|
├── docker-compose.yml # Quick-start deployment
|
|
└── package.json # Root scripts (test, test:e2e)
|
|
```
|
|
|
|
For more detail on how the components relate, see the [Architecture Overview](/reference/architecture).
|