Volt CLI: source-available under AGPSL v5.0

Complete infrastructure platform CLI: - Container runtime (systemd-nspawn) - VoltVisor VMs (Neutron Stardust / QEMU) - Stellarium CAS (content-addressed storage) - ORAS Registry - GitOps integration - Landlock LSM security - Compose orchestration - Mesh networking Copyright (c) Armored Gates LLC. All rights reserved. Licensed under AGPSL v5.0
2026-03-21 00:30:23 -05:00
commit 0ebe75b2ca
155 changed files with 63317 additions and 0 deletions
--- a/docs/gitops.md
+++ b/docs/gitops.md
@@ -0,0 +1,333 @@
+# Volt GitOps
+
+Volt includes built-in GitOps pipelines that automatically deploy workloads when code is pushed to a Git repository. No external CI/CD system required — Volt handles the entire flow from webhook to deployment.
+
+## Overview
+
+A GitOps pipeline links a Git repository branch to a Volt workload. When a push is detected on the tracked branch:
+
+1. **Webhook received** — GitHub, GitLab, or Bitbucket sends a push event (or SVN revision changes are detected via polling)
+2. **Validate** — The webhook signature is verified against the configured HMAC secret
+3. **Clone** — The repository is cloned (or pulled if already cached)
+4. **Detect** — Volt looks for `volt-manifest.yaml` or `Voltfile` in the repo root
+5. **Deploy** — The workload is updated according to the manifest
+6. **Log** — The result (success or failure) is recorded in the deploy history
+
+```
+┌──────────┐    push     ┌──────────────┐   clone    ┌──────────┐   deploy   ┌──────────┐
+│  GitHub  │───────────→ │ Volt GitOps  │──────────→ │   Repo   │──────────→ │ Workload │
+│  GitLab  │  webhook    │   Server     │            │ (cached) │            │          │
+│Bitbucket │             │  :9090       │            └──────────┘            └──────────┘
+│   SVN    │  polling    │              │
+└──────────┘             └──────────────┘
+```
+
+## Supported Providers
+
+| Provider | Method | Signature Validation |
+|----------|--------|---------------------|
+| GitHub | Webhook (`POST /hooks/github`) | HMAC-SHA256 (`X-Hub-Signature-256`) |
+| GitLab | Webhook (`POST /hooks/gitlab`) | Secret token (`X-Gitlab-Token`) |
+| Bitbucket | Webhook (`POST /hooks/bitbucket`) | HMAC-SHA256 |
+| SVN | Polling (configurable interval) | N/A |
+
+## Quick Start
+
+### 1. Create a Pipeline
+
+```bash
+volt gitops create \
+  --name web-app \
+  --repo https://github.com/myorg/myapp \
+  --provider github \
+  --branch main \
+  --workload web \
+  --secret my-webhook-secret
+```
+
+### 2. Start the Webhook Server
+
+```bash
+# Foreground (for testing)
+volt gitops serve --port 9090
+
+# Or install as a systemd service (production)
+sudo volt gitops install-service
+sudo systemctl enable --now volt-gitops.service
+```
+
+### 3. Configure Your Git Provider
+
+Add a webhook in your repository settings:
+
+**GitHub:**
+- Payload URL: `https://your-server:9090/hooks/github`
+- Content type: `application/json`
+- Secret: `my-webhook-secret` (must match `--secret`)
+- Events: "Just the push event"
+
+**GitLab:**
+- URL: `https://your-server:9090/hooks/gitlab`
+- Secret token: `my-webhook-secret`
+- Trigger: Push events
+
+**Bitbucket:**
+- URL: `https://your-server:9090/hooks/bitbucket`
+- Events: Repository push
+
+### 4. Push and Deploy
+
+Push to your tracked branch. The pipeline will automatically detect the push, clone the repo, and deploy the workload.
+
+```bash
+# Check pipeline status
+volt gitops status
+
+# View deploy history
+volt gitops logs --name web-app
+```
+
+## Creating Pipelines
+
+### GitHub
+
+```bash
+volt gitops create \
+  --name web-app \
+  --repo https://github.com/myorg/myapp \
+  --provider github \
+  --branch main \
+  --workload web \
+  --secret my-webhook-secret
+```
+
+The `--secret` flag sets the HMAC secret used to validate webhook signatures. This ensures only authentic GitHub push events trigger deployments.
+
+### GitLab
+
+```bash
+volt gitops create \
+  --name api \
+  --repo https://gitlab.com/myorg/api \
+  --provider gitlab \
+  --branch develop \
+  --workload api-svc \
+  --secret my-gitlab-secret
+```
+
+### Bitbucket
+
+```bash
+volt gitops create \
+  --name frontend \
+  --repo https://bitbucket.org/myorg/frontend \
+  --provider bitbucket \
+  --branch main \
+  --workload frontend-app \
+  --secret my-bitbucket-secret
+```
+
+### SVN (Polling)
+
+For SVN repositories, Volt polls for revision changes instead of using webhooks:
+
+```bash
+volt gitops create \
+  --name legacy-app \
+  --repo svn://svn.example.com/trunk \
+  --provider svn \
+  --branch trunk \
+  --workload legacy-app \
+  --poll-interval 60
+```
+
+The `--poll-interval` flag sets how often (in seconds) Volt checks for new SVN revisions. Default: 60 seconds.
+
+## Repository Structure
+
+Volt looks for deployment configuration in the repository root:
+
+```
+myapp/
+├── volt-manifest.yaml    # Preferred — workload manifest
+├── Voltfile              # Alternative — Voltfile format
+├── volt-compose.yaml     # Alternative — Constellation definition
+├── src/
+└── ...
+```
+
+The lookup order is:
+1. `volt-manifest.yaml`
+2. `Voltfile`
+3. `volt-compose.yaml`
+
+## Pipeline Management
+
+### List Pipelines
+
+```bash
+volt gitops list
+volt gitops list -o json
+```
+
+### Check Status
+
+```bash
+volt gitops status
+```
+
+Output:
+```
+NAME        REPO                                   BRANCH   PROVIDER   LAST DEPLOY    STATUS
+web-app     https://github.com/myorg/myapp         main     github     2m ago         success
+api         https://gitlab.com/myorg/api            develop  gitlab     1h ago         success
+legacy      svn://svn.example.com/trunk             trunk    svn        5m ago         failed
+```
+
+### Manual Sync
+
+Trigger a deployment manually without waiting for a webhook:
+
+```bash
+volt gitops sync --name web-app
+```
+
+This is useful for:
+- Initial deployment
+- Re-deploying after a failed webhook
+- Testing the pipeline
+
+### View Deploy History
+
+```bash
+volt gitops logs --name web-app
+volt gitops logs --name web-app --limit 50
+```
+
+Output:
+```
+TIMESTAMP              COMMIT       BRANCH   STATUS    DURATION   NOTES
+2025-07-14 15:30:01    abc1234      main     success   12s        webhook (github)
+2025-07-14 14:15:22    def5678      main     success   8s         manual sync
+2025-07-14 10:00:03    789abcd      main     failed    3s         Voltfile parse error
+```
+
+### Delete a Pipeline
+
+```bash
+volt gitops delete --name web-app
+```
+
+## Webhook Server
+
+### Foreground Mode
+
+For testing or development:
+
+```bash
+volt gitops serve --port 9090
+```
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/hooks/github` | GitHub push webhooks |
+| `POST` | `/hooks/gitlab` | GitLab push webhooks |
+| `POST` | `/hooks/bitbucket` | Bitbucket push webhooks |
+| `GET` | `/healthz` | Health check |
+
+### Production Deployment (systemd)
+
+Install the webhook server as a systemd service for production use:
+
+```bash
+# Install the service unit
+sudo volt gitops install-service
+
+# Enable and start
+sudo systemctl enable --now volt-gitops.service
+
+# Check status
+systemctl status volt-gitops.service
+
+# View logs
+journalctl -u volt-gitops.service -f
+```
+
+The installed service runs the webhook server on port 9090 by default. To customize, edit the service:
+
+```bash
+volt service edit volt-gitops
+```
+
+## Security
+
+### Webhook Signature Validation
+
+Always configure a webhook secret (`--secret`) for GitHub and Bitbucket pipelines. Without a secret, any HTTP POST to the webhook endpoint could trigger a deployment.
+
+**GitHub** — Volt validates the `X-Hub-Signature-256` header against the configured HMAC-SHA256 secret.
+
+**GitLab** — Volt validates the `X-Gitlab-Token` header against the configured secret.
+
+**Bitbucket** — Volt validates the HMAC-SHA256 signature.
+
+If signature validation fails, the webhook is rejected with `403 Forbidden` and no deployment occurs.
+
+### Network Security
+
+In production, place the webhook server behind the Volt ingress proxy with TLS:
+
+```bash
+volt ingress create --name gitops-webhook \
+  --hostname webhooks.example.com \
+  --path /hooks \
+  --backend localhost:9090 \
+  --tls auto
+```
+
+## Troubleshooting
+
+### Webhook Not Triggering
+
+1. Check the webhook server is running:
+   ```bash
+   volt gitops status
+   systemctl status volt-gitops.service
+   ```
+
+2. Check the pipeline exists:
+   ```bash
+   volt gitops list
+   ```
+
+3. Verify the webhook URL is correct in your Git provider settings
+
+4. Check the webhook secret matches
+
+5. Check deploy logs for errors:
+   ```bash
+   volt gitops logs --name <pipeline>
+   ```
+
+### Deploy Fails After Webhook
+
+1. Check the deploy logs:
+   ```bash
+   volt gitops logs --name <pipeline>
+   ```
+
+2. Verify the repo contains a valid `volt-manifest.yaml` or `Voltfile`
+
+3. Try a manual sync to see detailed error output:
+   ```bash
+   volt gitops sync --name <pipeline>
+   ```
+
+## See Also
+
+- [CLI Reference — GitOps Commands](cli-reference.md#volt-gitops--gitops-pipelines)
+- [Architecture — GitOps Pipeline](architecture.md#gitops-pipeline)
+- [Compose / Voltfile Format](compose.md)
+- [Ingress Proxy](networking.md#ingress-proxy)