Paul Payne
f39a551aad
- Introduced `uv.lock` for dependency management with various packages including `pytest`, `colorama`, and `pluggy`. - Added `pyrightconfig.json` for Python type checking configuration. - Expanded `recommendations.md` with detailed scaling recommendations and project management strategies. - Created shared `ruff.toml` for consistent linting across projects. - Developed `Castle Tools` with various utilities including Android backup, browser automation, document conversion, and search tools. - Implemented `backup-collect` and `schedule` tools for system administration tasks. - Enhanced `search` functionality with indexing and querying capabilities using Tantivy. - Added comprehensive documentation for each tool, including usage examples and installation instructions.
108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
# Castle
|
|
|
|
A declarative local control plane. Castle manages a collection of independent services, tools, and libraries from a single CLI, with a unified gateway, systemd integration, and standardized project scaffolding.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install the castle CLI
|
|
cd cli && uv tool install --editable . && cd ..
|
|
|
|
# Sync all projects (git submodules + dependencies)
|
|
castle sync
|
|
|
|
# See what's here
|
|
castle list
|
|
|
|
# Start everything (all services + Caddy gateway)
|
|
castle services start
|
|
|
|
# Visit the dashboard
|
|
open http://localhost:9000
|
|
```
|
|
|
|
## Creating Projects
|
|
|
|
```bash
|
|
castle create my-api --type service --description "Does something useful"
|
|
cd my-api && uv sync
|
|
castle test my-api
|
|
castle service enable my-api
|
|
```
|
|
|
|
Three project types are supported:
|
|
|
|
- **service** — FastAPI app with health endpoint, pydantic-settings, systemd unit, gateway route
|
|
- **tool** — CLI tool with argparse, stdin/stdout, Unix pipe conventions
|
|
- **library** — Python package with src/ layout, no entry point
|
|
|
|
## CLI Reference
|
|
|
|
```
|
|
castle list [--type TYPE] [--json] List all projects
|
|
castle create NAME --type TYPE Scaffold a new project
|
|
castle test [PROJECT] Run tests (one or all)
|
|
castle lint [PROJECT] Run linter (one or all)
|
|
castle sync Update submodules + install deps
|
|
castle gateway start|stop|reload Manage Caddy reverse proxy
|
|
castle service enable|disable NAME Manage a systemd service
|
|
castle service status Show all service statuses
|
|
castle services start|stop Start/stop everything
|
|
```
|
|
|
|
## Registry
|
|
|
|
`castle.yaml` at the repo root is the single source of truth. It defines every project's type, port, gateway path, data directory, command, and environment variables. The CLI reads this for all operations — generating Caddyfiles, systemd units, and dashboard HTML.
|
|
|
|
```yaml
|
|
gateway:
|
|
port: 9000
|
|
|
|
projects:
|
|
central-context:
|
|
type: service
|
|
port: 9001
|
|
path: /central-context
|
|
command: uv run central-context
|
|
working_dir: central-context
|
|
data_dir: /data/castle/central-context
|
|
description: Content storage API
|
|
health: /health
|
|
env:
|
|
CENTRAL_CONTEXT_DATA_DIR: ${data_dir}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
castle.yaml ← project registry
|
|
cli/ ← castle CLI (castle-component)
|
|
central-context/ ← content storage API (git submodule)
|
|
notification-bridge/ ← notification forwarder (git submodule)
|
|
devbox-connect/ ← SSH tunnel manager
|
|
mboxer/ ← MBOX converter (git submodule)
|
|
toolkit/ ← personal utility scripts (git submodule)
|
|
event-bus/ ← inter-service event bus (castle-component)
|
|
ruff.toml ← shared lint config
|
|
pyrightconfig.json ← shared type checking config
|
|
```
|
|
|
|
**Independence principle:** Regular projects never depend on castle. They accept configuration (data dir, port, URLs) via environment variables. Only castle-components (CLI, gateway, event bus) know about castle internals like `castle.yaml`. This keeps projects portable and independently publishable.
|
|
|
|
**Gateway:** Caddy reverse proxy at port 9000. All services are accessible under one address (`localhost:9000/central-context/*` → `localhost:9001/*`). A dashboard with live health checks is served at the root.
|
|
|
|
**Systemd:** The CLI generates user units under `~/.config/systemd/user/castle-*.service`. `castle services start` brings up everything in one command.
|
|
|
|
**Data:** Service data lives in `/data/castle/<service-name>/`, outside the repo. Secrets live in `~/.castle/secrets/`.
|
|
|
|
## Current Projects
|
|
|
|
| Project | Type | Port | Description |
|
|
|---------|------|------|-------------|
|
|
| central-context | service | 9001 | Content storage API |
|
|
| notification-bridge | service | 9002 | Desktop notification forwarder |
|
|
| devbox-connect | tool | — | SSH tunnel manager |
|
|
| mboxer | tool | — | MBOX to EML converter |
|
|
| toolkit | tool | — | Personal utility scripts |
|
|
| event-bus | castle-component | 9010 | Inter-service event bus |
|