siujamo
9a790e1211
- README with project overview, architecture diagram, and quick start - CONTRIBUTING with development setup and code style guidelines - CHANGELOG starting at 0.1.0 (unreleased, under active development)
70 lines
2.4 KiB
Markdown
70 lines
2.4 KiB
Markdown
# Pipely
|
|
|
|
High-concurrency, low-bandwidth OTA (Over-the-Air) update management and distribution server built in Go. Designed to distribute updates to thousands of devices under constrained network conditions (**10 Mbps** bandwidth ceiling).
|
|
|
|
## Features
|
|
|
|
- **Device Management** — Registration, heartbeat tracking, and online/offline detection
|
|
- **Artefact Versioning** — Upload and manage update packages with SHA-256 integrity verification
|
|
- **Delta Updates** — BSDiff-style binary diffs for JAR files to minimise bandwidth
|
|
- **Gated Rollout** — Token-based concurrency control prevents network saturation
|
|
- **Resumable Downloads** — HTTP Range support (`206 Partial Content`) for interrupted transfers
|
|
- **Per-Connection Throttling** — Token-bucket rate limiting keeps total bandwidth under 10 Mbps
|
|
- **JWT Authentication** — Secure admin API with configurable token expiry
|
|
- **Web Admin Panel** — React-based dashboard for version uploads, deployment management, and user administration
|
|
|
|
## Architecture
|
|
|
|
```
|
|
daemon (mcd) Pipely Server Admin Browser
|
|
│ │ │
|
|
├─ POST /devices/register ──────>│ │
|
|
├─ POST /devices/heartbeat ─────>│ │
|
|
├─ GET /devices/check-update ──>│ │
|
|
├─ GET /packages/download/:id ─>│ (rate-limited + gated) │
|
|
├─ POST /deployments/:id/status >│ │
|
|
│ │<── JWT login ────────────────┤
|
|
│ │<── CRUD artefacts/deployments┤
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.26+
|
|
- PostgreSQL 16+
|
|
- pnpm (for building the admin panel)
|
|
|
|
### Running
|
|
|
|
```bash
|
|
# Clone
|
|
git clone git@onixbyte.dev:onixbyte/pipely.git
|
|
cd pipely
|
|
|
|
# Configure (copy and edit)
|
|
cp .env.example .env
|
|
|
|
# Build the admin panel
|
|
cd web && pnpm install && pnpm build && cd ..
|
|
|
|
# Run
|
|
go run cmd/server/main.go
|
|
```
|
|
|
|
The server starts on `:8080` by default. The admin panel is served at `/`.
|
|
|
|
Default login: **admin** / **admin**
|
|
|
|
### Environment Variables
|
|
|
|
See `.env.example` for all configuration options with descriptions and examples.
|
|
|
|
## API
|
|
|
|
The daemon-facing API is documented in `docs/daemon-api.yaml` (OpenAPI 3.0).
|
|
|
|
## Licence
|
|
|
|
TBD
|