9ff4876b56
- Add CLI reference documentation with command examples - Add CLI quick reference card for quick lookups - Add troubleshooting guide for common issues - Add GitHub Actions release workflow for binary builds - Add CHANGELOG.md for release tracking - Add webhook integration examples - Add setup and verification script - Update README with installation instructions and CLI overview Addresses ELF-169: Document CLI and add standalone binary releases Co-Authored-By: Paperclip <noreply@paperclip.ing>
152 lines
4.6 KiB
Markdown
152 lines
4.6 KiB
Markdown
# El Foundation
|
|
|
|
Engineering repository for El Foundation.
|
|
|
|
## About
|
|
|
|
El Foundation builds institutions that outlast their founders. We create technology and organizations that compound in value over time. This repository is the source of truth for our engineering work.
|
|
|
|
## Getting Started
|
|
|
|
1. Read the [company charter](docs/company/charter.md) to understand why we exist.
|
|
2. Read the [operating model](docs/company/operating-model.md) to understand how decisions are made.
|
|
3. Read [CONTRIBUTING.md](CONTRIBUTING.md) before making any changes.
|
|
4. Read [docs/engineering/local-dev.md](docs/engineering/local-dev.md) for the day-to-day workflow.
|
|
5. Read [docs/engineering/hatch-architecture.md](docs/engineering/hatch-architecture.md) for the component map.
|
|
|
|
## Installation
|
|
|
|
### Pre-built Binaries (Recommended)
|
|
|
|
Download the latest binary for your platform from the [Releases page](https://github.com/elfoundation/hatch/releases):
|
|
|
|
- **Linux (x64)**: `hatch-linux-amd64`
|
|
- **Linux (ARM64)**: `hatch-linux-arm64`
|
|
- **macOS (Intel)**: `hatch-darwin-amd64`
|
|
- **macOS (Apple Silicon)**: `hatch-darwin-arm64`
|
|
- **Windows (x64)**: `hatch-windows-amd64.exe`
|
|
|
|
After downloading:
|
|
|
|
```bash
|
|
# Linux/macOS
|
|
chmod +x hatch-*
|
|
sudo mv hatch-* /usr/local/bin/hatch
|
|
|
|
# Windows (PowerShell)
|
|
Rename-Item hatch-windows-amd64.exe hatch.exe
|
|
# Move to a directory in your PATH
|
|
```
|
|
|
|
### Build from Source
|
|
|
|
Requires Go 1.25 or later:
|
|
|
|
```bash
|
|
git clone https://github.com/elfoundation/hatch.git
|
|
cd hatch
|
|
CGO_ENABLED=0 go build -o hatch ./cmd/hatch
|
|
sudo mv hatch /usr/local/bin/
|
|
```
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
├── .github/workflows/ # CI/CD definitions
|
|
├── cmd/hatch/ # Server entrypoint (Go binary)
|
|
├── docs/
|
|
│ ├── company/ # Founding documents (charter, org, etc.)
|
|
│ ├── engineering/ # Engineering standards, architecture, local dev
|
|
│ └── adrs/ # Architecture Decision Records
|
|
├── examples/ # Usage examples and integration guides
|
|
├── internal/ # Go packages (handler, store, ...)
|
|
├── Dockerfile # Multi-stage static binary build (golang → scratch)
|
|
├── docker-compose.yml # Local stack with optional Caddy sidecar
|
|
├── Caddyfile # TLS reverse proxy for the demo host
|
|
└── go.mod # Go module definition
|
|
```
|
|
|
|
## Hatch — Deploy in one command
|
|
|
|
Hatch is a self-hostable HTTP request inspector + mocker. Ship it to any VPS with Docker.
|
|
|
|
**[Read why we are building Hatch →](https://hatch.sh/blog/why-we-are-building-hatch)**
|
|
|
|
### Quick start (local dev, no HTTPS)
|
|
|
|
```bash
|
|
docker compose up --build
|
|
# Hatch UI: http://localhost:8080
|
|
# Health check: http://localhost:8080/healthz
|
|
```
|
|
|
|
Or run the binary directly:
|
|
|
|
```bash
|
|
go run ./cmd/hatch
|
|
# Health check: http://localhost:8080/healthz
|
|
```
|
|
|
|
### Production (with HTTPS via Caddy)
|
|
|
|
```bash
|
|
# Set your domain name
|
|
cp .env.example .env
|
|
# Edit HATCH_HOSTNAME in .env to your real domain
|
|
|
|
# Start Hatch + Caddy (auto-issues Let's Encrypt cert)
|
|
docker compose --profile with-caddy up -d --build
|
|
# Hatch UI: https://{your-domain}
|
|
# Capture endpoint: https://{your-domain}/{endpoint-id}
|
|
```
|
|
|
|
### Architecture
|
|
|
|
```
|
|
Internet → :443 (Caddy) → hatch:8080 (Go binary, internal network)
|
|
│
|
|
├─ Auto TLS (Let's Encrypt, or self-signed for localhost)
|
|
├─ Reverse proxy with security headers
|
|
└─ JSON access logs to stdout
|
|
```
|
|
|
|
Caddy terminates TLS and reverse-proxies to the Hatch Go binary. The Hatch container only listens on `127.0.0.1:8080` — it's never directly exposed to the internet.
|
|
|
|
## CLI Reference
|
|
|
|
Hatch includes a powerful CLI for interacting with the server from the command line:
|
|
|
|
```bash
|
|
# Capture requests
|
|
hatch capture https://api.example.com/webhook
|
|
|
|
# Inspect captured traffic
|
|
hatch inspect my-webhook
|
|
|
|
# Search for specific requests
|
|
hatch search my-webhook -query 'status:500'
|
|
|
|
# Replay requests to other services
|
|
hatch replay <request-id> -endpoint my-webhook -target https://httpbin.org/post
|
|
|
|
# Configure mock responses
|
|
hatch mock set my-webhook -status 200 -body '{"ok":true}'
|
|
|
|
# Generate OpenAPI documentation
|
|
hatch doc generate my-webhook > openapi.json
|
|
```
|
|
|
|
For detailed CLI documentation, see [docs/engineering/cli.md](docs/engineering/cli.md).
|
|
|
|
## Technology Stack
|
|
|
|
See [docs/engineering/tech-stack.md](docs/engineering/tech-stack.md) for current choices and rationale, and [docs/adrs/](docs/adrs/) for the decision records that produced them.
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## License
|
|
|
|
Hatch is released under the MIT License — see [LICENSE](LICENSE).
|