docs: add GitBook public documentation

README.md

@@ -11,12 +11,13 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/TerrifiedBug/vectorflow/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/TerrifiedBug/vectorflow/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/TerrifiedBug/vectorflow?style=flat-square)](https://github.com/TerrifiedBug/vectorflow/releases)
 [![License](https://img.shields.io/badge/License-AGPL--3.0-blue?style=flat-square)](LICENSE)
+[![Docs](https://img.shields.io/badge/Docs-GitBook-blue?style=flat-square)](https://terrifiedbug.gitbook.io/vectorflow)
 
 **🔀 Design, deploy, and monitor [Vector](https://vector.dev) data pipelines — visually**
 
 Stop hand-editing YAML. Build observability pipelines with drag-and-drop<br>and deploy them across your entire fleet from a single dashboard.
 
-[Quick Start](#-quick-start) · [Deployment](#-deployment) · [Features](#-features) · [Configuration](#%EF%B8%8F-configuration) · [Development](#-development)
+[Documentation](https://terrifiedbug.gitbook.io/vectorflow) · [Quick Start](#-quick-start) · [Deployment](#-deployment) · [Features](#-features) · [Configuration](#%EF%B8%8F-configuration) · [Development](#-development)
 
 </div>
 

docs/public/.gitbook.yaml

@@ -0,0 +1,5 @@
+root: ./
+
+structure:
+  readme: README.md
+  summary: SUMMARY.md

docs/public/.gitbook/gitbook-skill.md

@@ -0,0 +1,64 @@
+# GitBook Documentation Editing Skill
+
+This guide enables AI tools to write GitBook-compatible markdown.
+
+## Key Formatting Elements
+
+GitBook extends standard markdown with custom blocks:
+
+### Tabs
+{% tabs %}
+{% tab title="Docker" %}
+Content for Docker tab
+{% endtab %}
+{% tab title="Standalone" %}
+Content for Standalone tab
+{% endtab %}
+{% endtabs %}
+
+### Hints / Callouts
+{% hint style="info" %}
+Informational callout
+{% endhint %}
+
+{% hint style="warning" %}
+Warning callout
+{% endhint %}
+
+{% hint style="danger" %}
+Danger callout
+{% endhint %}
+
+{% hint style="success" %}
+Success callout
+{% endhint %}
+
+### Steppers
+{% stepper %}
+{% step %}
+### Step Title
+Step content
+{% endstep %}
+{% endstepper %}
+
+### Expandable Content
+<details>
+<summary>Click to expand</summary>
+Hidden content here
+</details>
+
+## Configuration
+
+- **.gitbook.yaml** -- Space configuration (root directory, readme/summary paths)
+- **SUMMARY.md** -- Table of contents defining sidebar navigation
+- **/.gitbook/vars.yaml** -- Space-level reusable variables
+
+## Writing Guidelines
+
+- Use hierarchical headings (H1-H3)
+- Keep paragraphs short, use bullet points
+- Include code snippets and practical examples
+- Minimize jargon
+- Use tabs for platform-specific content (Docker vs Standalone, Linux vs macOS)
+- Use hints for important callouts
+- Use steppers for sequential procedures

docs/public/README.md

@@ -0,0 +1,47 @@
+# Introduction
+
+VectorFlow is a visual pipeline management platform for [Vector](https://vector.dev), the high-performance observability data pipeline. It gives teams a web-based UI for designing, deploying, and monitoring Vector pipelines across an entire fleet of nodes -- no hand-edited TOML required.
+
+![VectorFlow Dashboard](screenshots/dashboard.png)
+
+## Why VectorFlow?
+
+Observability pipelines are critical infrastructure, yet managing them usually means juggling config files across dozens of servers. VectorFlow replaces that workflow with a centralized control plane:
+
+- **Visual Pipeline Editor** -- Drag-and-drop sources, transforms, and sinks onto a canvas. The editor generates valid Vector configuration automatically.
+- **Fleet Management** -- Enroll agents on every node and push pipeline updates from a single dashboard. See which agents are online, what they are running, and roll back instantly.
+- **Multi-Environment Support** -- Maintain separate development, staging, and production environments. Promote pipelines through your deployment lifecycle with confidence.
+- **VRL Snippet Testing** -- Write and test Vector Remap Language transforms interactively before they reach production.
+- **Real-Time Metrics** -- Monitor throughput, error rates, and pipeline health at a glance.
+- **Alerting** -- Define alert rules so you know the moment a pipeline degrades.
+
+## Technology
+
+| Layer | Technology |
+|-------|------------|
+| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS |
+| Flow Editor | React Flow (@xyflow/react) |
+| Code Editor | Monaco Editor with VRL syntax |
+| API | tRPC (type-safe RPC) |
+| Authentication | NextAuth (credentials + OIDC) |
+| Database | PostgreSQL, Prisma ORM |
+| Agent | Go (zero external dependencies) |
+| Data Engine | Vector (vector.dev) |
+
+{% hint style="info" %}
+**Get started in 5 minutes.** Follow the [Quick Start](getting-started/quick-start.md) guide to spin up VectorFlow with Docker and build your first pipeline.
+{% endhint %}
+
+## Quick Links
+
+| | |
+|---|---|
+| **Getting Started** | [Quick Start](getting-started/quick-start.md) -- Install and run VectorFlow |
+| **Deploy** | [Server](getting-started/deploy-server.md) -- Set up the VectorFlow server |
+| | [Agents](getting-started/deploy-agents.md) -- Enroll agents on your nodes |
+| **Learn** | [Pipeline Editor](user-guide/pipeline-editor.md) -- Build pipelines visually |
+| | [Fleet Management](user-guide/fleet.md) -- Manage your agent fleet |
+| **Operate** | [Architecture](operations/architecture.md) -- Understand how it all fits together |
+| | [Configuration](operations/configuration.md) -- Environment variables and settings |
+| **Reference** | [API](reference/api.md) -- Full API documentation |
+| | [Pipeline YAML](reference/pipeline-yaml.md) -- Pipeline configuration format |

docs/public/SUMMARY.md

@@ -0,0 +1,37 @@
+# Summary
+
+* [Introduction](README.md)
+
+## Getting Started
+
+* [Quick Start](getting-started/quick-start.md)
+* [Deploy the Server](getting-started/deploy-server.md)
+* [Deploy Agents](getting-started/deploy-agents.md)
+* [Your First Pipeline](getting-started/first-pipeline.md)
+
+## User Guide
+
+* [Dashboard](user-guide/dashboard.md)
+* [Pipelines](user-guide/pipelines.md)
+* [Pipeline Editor](user-guide/pipeline-editor.md)
+* [VRL Snippets](user-guide/vrl-snippets.md)
+* [Environments](user-guide/environments.md)
+* [Fleet Management](user-guide/fleet.md)
+* [Alerts](user-guide/alerts.md)
+* [Templates](user-guide/templates.md)
+
+## Operations
+
+* [Architecture](operations/architecture.md)
+* [Configuration](operations/configuration.md)
+* [Authentication](operations/authentication.md)
+* [Backup & Restore](operations/backup-restore.md)
+* [Security](operations/security.md)
+* [Upgrading](operations/upgrading.md)
+
+## Reference
+
+* [API Reference](reference/api.md)
+* [Agent Reference](reference/agent.md)
+* [Database Schema](reference/database.md)
+* [Pipeline YAML](reference/pipeline-yaml.md)

docs/public/getting-started/deploy-agents.md

@@ -0,0 +1,208 @@
+# Deploy Agents
+
+The VectorFlow agent (`vf-agent`) is a lightweight Go binary that runs on each node in your fleet. It manages Vector processes, pulls pipeline configurations from the server, and reports health via heartbeats.
+
+{% hint style="info" %}
+**Pull-based architecture** -- agents poll the server for config updates. No inbound ports are required on your fleet nodes. The agent initiates all connections, making it firewall-friendly and easy to deploy behind NAT.
+{% endhint %}
+
+## How it works
+
+1. The agent starts and **enrolls** with the VectorFlow server using a one-time enrollment token
+2. After enrollment, the server issues a persistent **node token** stored on disk
+3. The agent **polls** the server every 15 seconds (configurable) for pipeline configuration changes
+4. When a new config is received, the agent writes it to disk and starts or restarts the Vector process
+5. The agent sends **heartbeats** with host metrics (CPU, memory, disk, network) so the server can track fleet health
+
+Each pipeline runs as an isolated Vector process -- a crash in one pipeline does not affect others.
+
+## Enrollment flow
+
+{% stepper %}
+{% step %}
+### Generate an enrollment token
+
+In the VectorFlow UI, navigate to the **Fleet** page. Select the environment you want to enroll the agent into, then click **Add Node**.
+
+VectorFlow generates a one-time enrollment token. Copy it -- you will need it in the next step.
+
+{% hint style="warning" %}
+Enrollment tokens are single-use. Each agent needs its own token. Generate a new one for each node you want to enroll.
+{% endhint %}
+{% endstep %}
+
+{% step %}
+### Deploy the agent
+
+Choose one of the deployment methods below and start the agent with the enrollment token.
+{% endstep %}
+
+{% step %}
+### Verify enrollment
+
+Once the agent starts, it enrolls with the server and appears on the **Fleet** page with an **Online** status. You can now deploy pipelines to this node.
+
+If the agent does not appear, check its logs for enrollment errors (`docker compose logs -f` or `journalctl -u vf-agent -f`).
+{% endstep %}
+{% endstepper %}
+
+## Deployment methods
+
+{% tabs %}
+{% tab title="Docker" %}
+The simplest approach -- ideal for containerized environments.
+
+```bash
+mkdir -p vectorflow-agent && cd vectorflow-agent
+
+curl -sSfL -o docker-compose.yml \
+  https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/docker/agent/docker-compose.yml
+```
+
+Create a `.env` file with your server URL and enrollment token:
+
+```bash
+cat > .env << 'EOF'
+VF_URL=https://your-vectorflow-server:3000
+VF_TOKEN=paste-enrollment-token-here
+EOF
+```
+
+Start the agent:
+
+```bash
+docker compose up -d
+```
+
+The Docker image bundles Vector, so no additional dependencies are needed. Two named volumes persist agent state and Vector data across restarts:
+
+| Volume | Mount point | Contents |
+|--------|-------------|----------|
+| `vectorflow-agent-data` | `/var/lib/vf-agent` | Node token, pipeline configs |
+| `vectorflow-vector-data` | `/var/lib/vector` | Vector checkpoints and buffer data |
+
+The agent container uses `network_mode: host` so Vector can bind to local ports (e.g., for syslog or socket sources).
+
+{% hint style="warning" %}
+After the first successful enrollment, the agent persists a node token to disk. The `VF_TOKEN` enrollment token is no longer needed. You can remove it from your `.env` file, but leaving it has no effect.
+{% endhint %}
+{% endtab %}
+
+{% tab title="Install script" %}
+The install script downloads the agent binary, installs Vector if needed, and configures a systemd service -- all in one command.
+
+```bash
+curl -sSfL https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/agent/install.sh | \
+  sudo bash -s -- --url https://vectorflow.example.com --token <enrollment-token>
+```
+
+**Managing the service:**
+
+```bash
+systemctl status vf-agent          # Check status
+journalctl -u vf-agent -f          # Follow logs
+sudo systemctl restart vf-agent    # Restart
+```
+
+**Upgrading:**
+
+```bash
+# Upgrade to the latest release
+curl -sSfL https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/agent/install.sh | sudo bash
+
+# Install a specific version
+curl -sSfL https://raw.githubusercontent.com/TerrifiedBug/vectorflow/main/agent/install.sh | \
+  sudo bash -s -- --version v0.3.0
+```
+
+Existing configuration at `/etc/vectorflow/agent.env` is preserved during upgrades.
+
+**Uninstalling:**
+
+```bash
+sudo systemctl stop vf-agent
+sudo systemctl disable vf-agent
+sudo rm /etc/systemd/system/vf-agent.service
+sudo systemctl daemon-reload
+sudo rm /usr/local/bin/vf-agent
+sudo rm -rf /var/lib/vf-agent /etc/vectorflow
+```
+{% endtab %}
+
+{% tab title="Standalone binary" %}
+Download the binary from the [Releases](https://github.com/TerrifiedBug/vectorflow/releases) page and run it directly. Useful for testing or environments without systemd.
+
+```bash
+# Download the latest release for your platform
+curl -sSfL -o vf-agent \
+  https://github.com/TerrifiedBug/vectorflow/releases/latest/download/vf-agent-linux-amd64
+chmod +x vf-agent
+```
+
+Run with environment variables:
+
+```bash
+VF_URL=https://your-vectorflow-server:3000 \
+VF_TOKEN=paste-enrollment-token-here \
+./vf-agent
+```
+
+Or with a manual systemd unit:
+
+```ini
+# /etc/systemd/system/vf-agent.service
+[Unit]
+Description=VectorFlow Agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/vectorflow/agent.env
+ExecStart=/usr/local/bin/vf-agent
+Restart=on-failure
+RestartSec=5
+
+# Security hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/vf-agent
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Make sure Vector is installed and available in `PATH`, or set the `VF_VECTOR_BIN` variable to point to the binary.
+{% endtab %}
+{% endtabs %}
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VF_URL` | Yes | -- | VectorFlow server URL (e.g., `https://vectorflow.example.com:3000`) |
+| `VF_TOKEN` | First run | -- | One-time enrollment token from the UI. Not needed after successful enrollment. |
+| `VF_DATA_DIR` | No | `/var/lib/vf-agent` | Directory for agent state (node token, pipeline configs). Mapped to a Docker volume by default. |
+| `VF_VECTOR_BIN` | No | `vector` | Path to the Vector binary. Set automatically in the Docker image. |
+| `VF_POLL_INTERVAL` | No | `15s` | How often the agent polls for config changes. Uses Go duration format (`15s`, `1m`, `30s`). |
+| `VF_LOG_LEVEL` | No | `info` | Log verbosity: `debug`, `info`, `warn`, or `error`. |
+
+## Troubleshooting
+
+**Agent does not appear in Fleet**
+
+- Verify `VF_URL` is correct and reachable from the agent host
+- Check that the enrollment token has not already been used
+- Look at agent logs for `enrollment failed` errors
+
+**Agent shows as "Unhealthy"**
+
+- The server marks a node unhealthy after 3 missed heartbeats (default: 45 seconds)
+- Check network connectivity between the agent and server
+- Verify the agent process is running (`systemctl status vf-agent` or `docker ps`)
+
+**Pipeline not starting on agent**
+
+- Confirm the pipeline is deployed to the correct environment
+- Check agent logs for Vector process errors
+- Verify Vector is installed and accessible at the path in `VF_VECTOR_BIN`