vite-press init

docs/en/guide/agent.md

@@ -0,0 +1,60 @@
+# Connect Agent
+
+OpenFlare Agent runs on proxy nodes. It handles registration, heartbeat, configuration sync, OpenResty file writes, validation, reload, rollback, and self-update.
+
+## Authentication
+
+| Method | Use case |
+| --- | --- |
+| `agent_token` | The node already exists or has a dedicated credential |
+| `discovery_token` | First-time auto-registration; Server exchanges it for a node token |
+
+At least one of them is required.
+
+## Install Script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --agent-token YOUR_AGENT_TOKEN
+```
+
+Or with discovery:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --discovery-token YOUR_DISCOVERY_TOKEN
+```
+
+## Configuration Example
+
+```json
+{
+  "server_url": "http://127.0.0.1:3000",
+  "agent_token": "replace-with-node-auth-token",
+  "data_dir": "./data",
+  "openresty_container_name": "openflare-openresty",
+  "openresty_docker_image": "openresty/openresty:alpine",
+  "openresty_observability_port": 18081,
+  "observability_replay_minutes": 15,
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
+```
+
+Without `openresty_path`, Agent uses Docker OpenResty by default.
+
+## Run from Source
+
+```bash
+cd openflare_agent
+export LOG_LEVEL='info'
+go run ./cmd/agent -config /path/to/agent.json
+```
+
+## Uninstall
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
+```

docs/en/guide/first-site.md

@@ -0,0 +1,32 @@
+# Publish First Site
+
+OpenFlare publishes complete configuration versions. After editing a site, publish and activate a new version before Agents apply it.
+
+## Create Site Configuration
+
+Required fields:
+
+| Field | Description |
+| --- | --- |
+| Site name | Business-unique identifier; defaults to the primary domain when omitted |
+| Domains | At least one domain; the first one is the primary domain |
+| Origin URL | Valid `http://` or `https://` upstream URL |
+| Enabled | Only enabled sites are rendered into releases |
+
+A domain can belong to only one site.
+
+## Bind Certificates
+
+HTTPS certificates are bound per domain. Domains without certificates are not automatically rendered into `443 ssl` server blocks.
+
+## Publish and Activate
+
+```text
+Edit rules -> Preview / diff -> Publish -> Create full version -> Activate -> Agent pulls -> Agent applies -> Agent reports
+```
+
+Server reads enabled sites, OpenResty template, performance options, and cache options, renders a full configuration, computes `checksum`, writes `config_versions`, then switches the active version.
+
+## Verify
+
+Check that the node is online, the node version matches the active version, the latest apply log succeeded, and the version page marks the new version as active.

docs/en/guide/index.md

@@ -0,0 +1,11 @@
+# Guide
+
+This section helps operators take OpenFlare from first boot to the first working reverse proxy configuration.
+
+Suggested order:
+
+1. [Quick Start](./quick-start.md): run Server with Docker Compose and complete the first login.
+2. [Run Server](./server.md): learn source startup, frontend build, and Swagger access.
+3. [Connect Agent](./agent.md): use `agent_token` or `discovery_token` to bring a node online.
+4. [Publish First Site](./first-site.md): create a site configuration, publish it, and verify node application.
+5. [Upgrade and Maintenance](./upgrade.md): understand upgrade, uninstall, validation, and maintenance entry points.

docs/en/guide/quick-start.md

@@ -0,0 +1,77 @@
+# Quick Start
+
+The minimal OpenFlare setup contains one Server and at least one Agent. Server owns the web console, release versions, and node state. Agent runs on proxy nodes and applies OpenResty configuration.
+
+## Run Server
+
+Docker Compose with PostgreSQL is recommended:
+
+```yaml
+services:
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: openflare
+      POSTGRES_USER: openflare
+      POSTGRES_PASSWORD: replace-with-strong-password
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  openflare:
+    image: ghcr.io/rain-kl/openflare:latest
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+    environment:
+      SESSION_SECRET: replace-with-random-string
+      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
+      GIN_MODE: release
+      LOG_LEVEL: info
+
+volumes:
+  postgres-data:
+```
+
+```bash
+docker compose up -d
+```
+
+Open `http://localhost:3000`.
+
+Default credentials:
+
+| Username | Password |
+| --- | --- |
+| `root` | `123456` |
+
+Change the default password immediately after first login.
+
+## Connect a Node
+
+Prepare a `discovery_token` or node-specific `agent_token` in the console, then run the install script on the node.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --agent-token YOUR_AGENT_TOKEN
+```
+
+The script installs Agent under `/opt/openflare-agent`, creates `openflare-agent.service`, and uses Docker OpenResty unless a local `openresty_path` is configured.
+
+## Publish the First Configuration
+
+1. Create a site configuration with a domain and origin URL.
+2. Preview the release or check the diff before publishing.
+3. Activate the new version.
+4. Wait for Agent to discover and apply it through heartbeat.
+
+Version numbers use `YYYYMMDD-NNN`. Historical versions are immutable; rollback reactivates an old version.

docs/en/guide/server.md

@@ -0,0 +1,52 @@
+# Run Server
+
+OpenFlare Server is the Gin + GORM control plane. It owns the web console, management API, Agent API, configuration rendering, release publishing, and state storage.
+
+## Requirements
+
+| Item | Requirement |
+| --- | --- |
+| Go | `1.24+` |
+| Node.js | `18+` |
+| Database | Writable SQLite path or reachable PostgreSQL instance |
+
+Set `SESSION_SECRET` explicitly in production and prefer PostgreSQL.
+
+## Build Frontend
+
+```bash
+cd openflare_server/web
+corepack enable
+pnpm install
+pnpm build
+```
+
+## Run from Source
+
+```bash
+cd openflare_server
+export SESSION_SECRET='replace-with-random-string'
+export SQLITE_PATH='./openflare.db'
+export LOG_LEVEL='info'
+# Optional PostgreSQL:
+# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
+go run .
+```
+
+The default port is `3000`.
+
+## Swagger
+
+After logging in, open:
+
+```text
+http://localhost:3000/swagger/index.html
+```
+
+Regenerate Swagger files locally:
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@v1.16.4
+cd openflare_server
+swag init -g main.go -o docs
+```

docs/en/guide/upgrade.md

@@ -0,0 +1,47 @@
+# Upgrade and Maintenance
+
+## Server Upgrade
+
+Root users can check and upgrade stable Server releases from the console header. Manual binary upload is also supported.
+
+Preview releases require manual selection. Stable releases are recommended for production.
+
+## Agent Upgrade
+
+Agents follow stable releases by default. Preview upgrades must be triggered manually.
+
+The install script can be re-run for reinstall or upgrade:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --agent-token YOUR_AGENT_TOKEN
+```
+
+## Data Maintenance
+
+The settings page controls observability cleanup:
+
+| Option | Description |
+| --- | --- |
+| `DatabaseAutoCleanupEnabled` | Enable daily cleanup |
+| `DatabaseAutoCleanupRetentionDays` | Retention days, minimum 1 |
+
+When enabled, Server cleans access logs, metric snapshots, and request reports at 03:00 every day.
+
+## Validation Commands
+
+```bash
+cd openflare_server
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+```bash
+cd openflare_agent
+GOCACHE=/tmp/openflare-go-cache go test ./...
+```
+
+```bash
+cd openflare_server/web
+pnpm build
+```