Skip to content

Commit 068fc74

Browse files
docs: update README with Docker quickstart, new features, and docs links
- Lead with docker compose up as recommended quickstart - Add missing features to table: SLOs, WAF, SSO, MFA, notifications, topology, GraphQL, developer portal - Add new UI pages: services, topology, certificates, SLOs, alerts, WAF, notifications, secrets - Add Documentation section linking to docs/ directory - Update tech stack with Absinthe and OpenTelemetry - Link header documentation to docs/index.md
1 parent 9f59284 commit 068fc74

1 file changed

Lines changed: 53 additions & 33 deletions

File tree

README.md

Lines changed: 53 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323

2424
<p align="center">
2525
<a href="https://github.com/raskell-io/sentinel">Sentinel Proxy</a> •
26-
<a href="https://sentinel.raskell.io/docs/">Documentation</a> •
26+
<a href="docs/index.md">Documentation</a> •
2727
<a href="https://github.com/raskell-io/sentinel/discussions">Discussions</a>
2828
</p>
2929

@@ -73,7 +73,16 @@ Every mutation is audit-logged with actor, action, and diff.
7373
| **Multi-Tenant** | Organizations, projects, and scoped API keys with RBAC |
7474
| **GitOps** | GitHub webhook integration — auto-compile bundles on push |
7575
| **Audit Logging** | Every mutation logged with who, what, when, and resource diff |
76-
| **Observability** | Prometheus metrics, structured JSON logging, health endpoints |
76+
| **SLO/SLI Monitoring** | Define SLOs with error budget tracking and burn rate alerts |
77+
| **Alerting** | Threshold, anomaly, and SLO burn rate alert rules with silencing |
78+
| **WAF** | ~60 OWASP CRS rules, policy system, anomaly detection, analytics |
79+
| **SSO** | OIDC (with PKCE) and SAML 2.0 with JIT provisioning and group mapping |
80+
| **TOTP MFA** | Time-based one-time passwords with recovery codes |
81+
| **Notifications** | Route events to Slack, PagerDuty, Teams, Email, or webhooks |
82+
| **Service Topology** | Visual graph of services, upstreams, middlewares, and policies |
83+
| **GraphQL API** | Absinthe-powered with real-time subscriptions |
84+
| **Developer Portal** | Auto-generated API docs from OpenAPI specs per project |
85+
| **Observability** | Prometheus metrics, OpenTelemetry tracing, structured JSON logging |
7786
| **LiveView UI** | K8s-style sidebar layout with real-time updates across all views |
7887
| **Node Simulator** | Built-in fleet simulator for testing rollout logic without real nodes |
7988

@@ -87,39 +96,53 @@ The control plane provides a comprehensive LiveView UI with real-time updates:
8796
| **Nodes** | `.../nodes` | Node list with status, labels, bundle versions, and health |
8897
| **Bundles** | `.../bundles` | Bundle management with diff viewer, SBOM inspector, and promotion pipeline |
8998
| **Rollouts** | `.../rollouts` | Rollout list with progress tracking, controls, and node-level status |
99+
| **Services** | `.../services` | Service routing configuration with upstream, middleware, and policy attachment |
100+
| **Topology** | `.../topology` | Visual service graph showing services, upstreams, and policies |
101+
| **Certificates** | `.../certificates` | TLS certificate management with ACME/Let's Encrypt support |
90102
| **Drift** | `.../drift` | Drift events with filtering and manual resolution |
91103
| **Node Groups** | `.../node-groups` | Label-based node organization |
92104
| **Environments** | `.../environments` | Promotion pipeline configuration |
93-
| **Health Checks** | `.../health-checks` | Custom health check definitions |
105+
| **SLOs** | `.../slos` | SLO definitions with error budget tracking and burn rate |
106+
| **Alerts** | `.../alerts` | Alert rules with firing state, silencing, and acknowledgment |
107+
| **WAF** | `.../waf-policies` | WAF policy management with rule overrides and analytics |
108+
| **Notifications** | `.../notifications` | Notification channels and routing rules with delivery tracking |
109+
| **Secrets** | `.../secrets` | Encrypted secret management with rotation and environment scoping |
94110
| **Webhooks** | `.../webhooks` | GitHub integration configuration |
95111
| **Schedule** | `/schedule` | Calendar view of scheduled rollouts |
96112
| **Approvals** | `/approvals` | Pending rollout approval queue |
97113
| **API Keys** | `/api-keys` | Scoped API key management |
98114
| **Audit Log** | `/audit` | Searchable audit trail with export |
99-
| **Profile** | `/profile` | User settings and password management |
115+
| **Profile** | `/profile` | User settings and MFA configuration |
100116

101117
## Quick Start
102118

103-
### Prerequisites
119+
### Docker Compose (Recommended)
104120

105-
- [mise](https://mise.jdx.dev/) (manages Elixir 1.15+ / OTP 26+ and task runner)
106-
- PostgreSQL (production) or SQLite (development)
107-
- A [Sentinel](https://github.com/raskell-io/sentinel) binary (for config validation)
121+
The fastest way to get running. Starts the control plane, PostgreSQL, and MinIO with a single command:
108122

109-
### Development
123+
```bash
124+
git clone https://github.com/raskell-io/sentinel-control-plane.git
125+
cd sentinel-control-plane
126+
docker compose up
127+
```
128+
129+
This builds the image, runs database migrations automatically, and serves the control plane at [localhost:4000](http://localhost:4000). MinIO console is available at [localhost:9001](http://localhost:9001) (credentials: `minioadmin` / `minioadmin`).
130+
131+
### Local Development
132+
133+
For development with hot-reloading and SQLite (no external databases needed):
110134

111135
```bash
112-
# Clone and setup
113136
git clone https://github.com/raskell-io/sentinel-control-plane.git
114137
cd sentinel-control-plane
115138
mise install
116139
mise run setup
117-
118-
# Start the development server
119140
mise run dev
120141
```
121142

122-
Visit [localhost:4000](http://localhost:4000). Default login: `admin@localhost` / `changeme123456`.
143+
Visit [localhost:4000](http://localhost:4000).
144+
145+
**Prerequisites:** [mise](https://mise.jdx.dev/) (manages Elixir/OTP), Docker (for MinIO), and optionally a [Sentinel](https://github.com/raskell-io/sentinel) binary for config validation.
123146

124147
### Development Commands
125148

@@ -135,24 +158,6 @@ mise run db:migrate # Run pending migrations
135158
mise run routes # List all routes
136159
```
137160

138-
### Local Dev Stack (Docker Compose)
139-
140-
Starts PostgreSQL, MinIO (S3), and the control plane together:
141-
142-
```bash
143-
docker compose -f docker-compose.dev.yml up
144-
```
145-
146-
### Production Docker
147-
148-
```bash
149-
docker build -t sentinel-cp .
150-
docker run -p 4000:4000 \
151-
-e DATABASE_URL="postgres://user:pass@host/sentinel_cp" \
152-
-e SECRET_KEY_BASE="$(mix phx.gen.secret)" \
153-
sentinel-cp
154-
```
155-
156161
## API
157162

158163
**📚 Interactive API Documentation:** [/api/docs](http://localhost:4000/api/docs) — powered by [Scalar](https://github.com/scalar/scalar)
@@ -238,11 +243,26 @@ POST /api/v1/webhooks/github # Auto-compile on push (signature verified)
238243
## Tech Stack
239244

240245
- **Elixir / Phoenix 1.8** — Web framework with LiveView for real-time UI
241-
- **Oban** — Reliable background jobs for bundle compilation and rollout orchestration
246+
- **Oban** — Reliable background jobs for compilation, rollouts, monitoring, and notifications
247+
- **Absinthe** — GraphQL API with real-time subscriptions
242248
- **PostgreSQL** — Persistent state (SQLite for development)
243249
- **S3 / MinIO** — Bundle artifact storage
244-
- **Ed25519** — Bundle signing via JOSE
250+
- **Ed25519** — Bundle and JWT signing via JOSE
245251
- **PromEx** — Prometheus metrics integration
252+
- **OpenTelemetry** — Distributed tracing for API, Ecto, and Phoenix
253+
254+
## Documentation
255+
256+
Full documentation is available in the [`docs/`](docs/index.md) directory:
257+
258+
- [Getting Started](docs/getting-started.md) — Install, first project, first rollout
259+
- [Architecture](docs/architecture.md) — System design and data flow
260+
- [Core Concepts](docs/core-concepts.md) — Orgs, projects, bundles, nodes, rollouts
261+
- [Configuration Management](docs/configuration-management.md) — Services, upstreams, certificates, secrets
262+
- [Deployment & Rollouts](docs/deployment-and-rollouts.md) — Strategies, health gates, approvals
263+
- [Security](docs/security.md) — WAF, auth policies, signing, SSO, MFA
264+
- [Observability](docs/observability.md) — SLOs, alerts, Prometheus, OpenTelemetry
265+
- [API Reference](docs/api-reference.md) — REST, Node, and GraphQL APIs
246266

247267
## Related
248268

0 commit comments

Comments
 (0)