Add README.md and RUNBOOK.md per engineering standards
Create the two required documentation files for MCNS: - README.md: project overview, quick-start (build/configure/run), links to ARCHITECTURE.md and RUNBOOK.md - RUNBOOK.md: operator-focused procedures with numbered steps covering health checks, start/stop/restart, backup/restore, log inspection, and incident playbooks for database corruption, certificate expiry, MCIAS outage, DNS resolution failures, and port conflicts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
42
README.md
Normal file
42
README.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# MCNS
|
||||
|
||||
Metacircular Networking Service -- an authoritative DNS server for the
|
||||
Metacircular platform. MCNS serves DNS zones backed by SQLite, forwards
|
||||
non-authoritative queries to upstream resolvers, and exposes a gRPC and
|
||||
REST management API authenticated through MCIAS. Records are updated
|
||||
dynamically via the API and visible to DNS immediately on commit.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Build the binary:
|
||||
|
||||
```bash
|
||||
make mcns
|
||||
```
|
||||
|
||||
Copy and edit the example configuration:
|
||||
|
||||
```bash
|
||||
cp deploy/examples/mcns.toml /srv/mcns/mcns.toml
|
||||
# Edit TLS paths, database path, MCIAS URL, upstream resolvers
|
||||
```
|
||||
|
||||
Run the server:
|
||||
|
||||
```bash
|
||||
./mcns server --config /srv/mcns/mcns.toml
|
||||
```
|
||||
|
||||
The server starts three listeners:
|
||||
|
||||
| Port | Protocol | Purpose |
|
||||
|------|----------|---------|
|
||||
| 53 | UDP + TCP | DNS (no auth) |
|
||||
| 8443 | TCP | REST management API (TLS, MCIAS auth) |
|
||||
| 9443 | TCP | gRPC management API (TLS, MCIAS auth) |
|
||||
|
||||
## Documentation
|
||||
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) -- full technical specification, database schema, API surface, and security model.
|
||||
- [RUNBOOK.md](RUNBOOK.md) -- operational procedures and incident response for operators.
|
||||
- [CLAUDE.md](CLAUDE.md) -- context for AI-assisted development.
|
||||
Reference in New Issue
Block a user