98 lines
3.9 KiB
Markdown
98 lines
3.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
`turboci-admin` is a Next.js (Pages Router) admin panel for TurboCI, a CI/CD deployment system. It manages deployments, services, and servers across cloud providers.
|
|
|
|
## Commands
|
|
|
|
### Development
|
|
|
|
```bash
|
|
bun run project:init # Full first-time setup: install deps, init twui submodule, generate DB schema
|
|
bun run dev # Next.js dev server on port 3772 (web only)
|
|
bun run pm2:dev # Start all 3 processes (web + cron + websocket) via PM2 in dev/watch mode
|
|
bun run pm2:start # Start all 3 processes via PM2 in production mode
|
|
bun run pm2:kill # Kill all PM2 processes
|
|
```
|
|
|
|
### Build & Database
|
|
|
|
```bash
|
|
bun run build # Production Next.js build
|
|
bun run db:schema # Regenerate SQLite types from schema (run after DB changes)
|
|
```
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
bun run docker:start # Rebuild and start all containers
|
|
bun run docker:logs # Tail Docker logs
|
|
```
|
|
|
|
### Submodule (twui)
|
|
|
|
```bash
|
|
bun run twui:update # Pull latest twui component library
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Process Model
|
|
|
|
The app runs as **three separate processes**, managed by PM2 (dev) or Docker Compose (prod):
|
|
|
|
| Process | Entry Point | Description |
|
|
|---|---|---|
|
|
| `turboci-web` | Next.js (port 3772) | Pages Router app + API routes |
|
|
| `turboci-websocket` | `src/websocket/index.ts` | Bun native WebSocket server (port from `WEB_SOCKET_PORT` env) |
|
|
| `turboci-cron` | `src/cron/index.ts` | Polls every 30s (`AppData.CronInterval`) to check services |
|
|
|
|
### Database
|
|
|
|
- **ORM**: `@moduletrace/nsqlite` — SQLite with Bun
|
|
- **Config**: `nsqlite.config.js` — DB name `turboci-admin`, stored in `src/db/`
|
|
- **Types**: Auto-generated in `src/db/types.ts` via `bun run db:schema`
|
|
- **Tables**: `users`, `users_ports`
|
|
|
|
### Key Directories
|
|
|
|
- `src/pages/` — Next.js pages and API routes (`/api/*`)
|
|
- `src/websocket/` — Bun WebSocket server; events are dispatched via a switch in `socket-message.ts`
|
|
- `src/cron/` — Background cron job (service health checks)
|
|
- `src/functions/` — Business logic (auth, deployment users, pages, ttyd)
|
|
- `src/utils/` — Utilities including SSH execution, config file access, port management
|
|
- `src/components/` — React components organized by page
|
|
- `src/types/index.ts` — All shared TypeScript types including `TCIConfig`, `WebSocketEvents`, `PagePropsType`
|
|
- `src/data/app-data.ts` — Central constants (`AppData`): cookie names, port ranges, timeouts
|
|
- `src/exports/client-exports.ts` — Re-exports from `@moduletrace/datasquirel` (use `_n` for number coercion, `EJSON` for WebSocket serialization)
|
|
- `twui/` — Git submodule: internal Tailwind UI component library
|
|
|
|
### TurboCI Config Files (Runtime)
|
|
|
|
The app reads deployment config from the host at runtime:
|
|
|
|
- `/root/.turboci/.config/turboci.json` — Main deployment config (`TCIGlobalConfig` type)
|
|
- `/root/.turboci/.ssh/turboci` — SSH private key for connecting to deployment servers
|
|
- `/root/.turboci/deployment_id` — Current deployment identifier
|
|
|
|
Use `grabDirNames()` (`src/utils/grab-dir-names.ts`) to get these paths, never hardcode them.
|
|
|
|
### WebSocket Event Flow
|
|
|
|
Client sends EJSON-serialized `WebSocketDataType` → `socket-message.ts` dispatches by `event` field → handler in `src/websocket/events/`. Connected users tracked in `global.WEBSOCKET_CONNECTED_USERS_DATA`.
|
|
|
|
### Auth
|
|
|
|
Cookie-based auth using `@moduletrace/datasquirel`. Cookie names are in `AppData` (`AuthCookieName`, `AuthCSRFCookieName`). Use `userAuth` (`src/utils/user-auth.ts`) in API routes and `getServerSideProps`.
|
|
|
|
### Environment Variables
|
|
|
|
Required in `.env` (see `test.env` for reference keys):
|
|
- `DSQL_ENCRYPTION_PASSWORD` / `DSQL_ENCRYPTION_SALT` — Used by datasquirel for auth token encryption
|
|
- `PORT` — Web server port (default 3772)
|
|
- `WEB_SOCKET_PORT` — WebSocket server port
|
|
- `HOST` — Full host URL (e.g. `http://localhost:3772`)
|