OpenFlare/docs/en/guide/deployment.md

Deployment

You will learn: The recommended OpenFlare deployment model, Server and Agent requirements, source startup workflow, integration steps, upgrade paths, and uninstall entry points.

For production, use PostgreSQL for the Server database and set SESSION_SECRET explicitly. The recommended deployment method for the Agent is Docker deployment (i.e., running the Agent image that already includes OpenResty); it also supports shell-script installation or running manually.

Topology

Browser
  |
  v
OpenFlare Server :3000
  |
  | Agent API / heartbeat / config pull
  v
OpenFlare Agent
  |
  v
OpenResty binary
  |
  v
Origin service

Requirements

Server:

Item	Requirement
Go	1.25+, source run only
Node.js	18+, frontend source build only
Database	Writable SQLite directory or reachable PostgreSQL instance
Port	3000 by default

Agent:

Item	Requirement
OS	Install script supports Linux and macOS. systemd service is created only on Linux + systemd.
Architecture	amd64 or arm64
OpenResty	Required for local Agent installs, or specified via --openresty-path
Docker	Required only when running the Agent Docker image
Network	Agent node must reach the Server URL
GeoIP	WAF regional rules use local MaxMind mmdb; Agent initializes a built-in library and updates it periodically

[Needs confirmation: recommended production CPU, memory, and disk size]

Docker Compose Server

Create docker-compose.yml:

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
    container_name: openflare
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      SESSION_SECRET: replace-with-a-long-random-string
      DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
      GIN_MODE: release
      LOG_LEVEL: info
    volumes:
      - openflare-data:/data

volumes:
  postgres-data:
  openflare-data:

Start:

docker compose up -d
docker compose ps
docker compose logs -f openflare

Open http://localhost:3000. The default account is root / 123456; change it immediately.

Run Server from Source

Build the management UI first:

cd openflare_server/web
corepack enable
pnpm install
pnpm build

Then start Server:

cd openflare_server
export SESSION_SECRET='replace-with-a-long-random-string'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
# Optional: PostgreSQL takes precedence when set.
# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
go run .

Default port is 3000. You can also set it explicitly:

go run . --port 3000 --log-dir ./logs

Run Agent in Docker (Recommended)

Docker deployment is the recommended deployment method for the Agent. In Docker deployments, directly run the Agent image. This image is built on top of the OpenResty image and includes both the Agent controller and the OpenResty binary. When node_ip is not explicitly configured, the Agent prioritizes obtaining the real public egress IP via a third-party API, avoiding registering the Docker bridge address as the node IP.

Mounting the configuration file:

docker pull ghcr.io/rain-kl/openflare-agent:latest
docker rm -f openflare-agent 2>/dev/null || true
docker run -d --name openflare-agent --restart unless-stopped \
  -p 80:80 -p 443:443 \
  -v openflare-agent-data:/data \
  -v ./agent.json:/etc/openflare/agent.json:ro \
  ghcr.io/rain-kl/openflare-agent:latest

Using environment variables:

docker pull ghcr.io/rain-kl/openflare-agent:latest
docker rm -f openflare-agent 2>/dev/null || true
docker run -d --name openflare-agent --restart unless-stopped \
  -p 80:80 -p 443:443 \
  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
  ghcr.io/rain-kl/openflare-agent:latest

Connect Agent (Script Installation)

In addition to Docker deployment, you can also deploy the Agent on the local host using our installation script.

With discovery_token:

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

With node-specific agent_token:

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

Supported options:

Option	Description
--server-url	Server URL, required
--discovery-token	First-registration token, mutually exclusive with --agent-token
--agent-token	Node-specific token, mutually exclusive with --discovery-token
--install-dir	Install directory, default /opt/openflare-agent
--openresty-path	OpenResty binary path, auto-detected when omitted
--repo	GitHub repository for Agent downloads, default Rain-kl/OpenFlare
--no-service	Do not create a systemd service

Check status:

systemctl status openflare-agent
journalctl -u openflare-agent -f

Run Agent Manually

From source:

cd openflare_agent
export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json

Build and run:

cd openflare_agent
go build -o openflare-agent ./cmd/agent
export LOG_LEVEL='info'
./openflare-agent -config /path/to/agent.json

Minimal agent.json:

{
  "server_url": "http://127.0.0.1:3000",
  "agent_token": "replace-with-node-auth-token",
  "data_dir": "./data",
  "openresty_path": "openresty",
  "heartbeat_interval": 10000,
  "request_timeout": 10000
}

When openresty_path is not configured, Agent runs openresty.

By default, the Agent will attempt to upgrade to a WebSocket after a successful HTTP heartbeat. When the upgrade succeeds, the Server immediately notifies the Agent of any configuration publications or activations; if the WebSocket cannot be established or is unexpectedly disconnected, the Agent automatically falls back to HTTP heartbeat synchronization.

WAF regional rules rely on the Agent's local GeoLite2-Country.mmdb. Upon startup, the Agent initializes a built-in database at data_dir/etc/openflare/GeoLite2-Country.mmdb and attempts to update it periodically based on configuration; update failures only record warnings, and do not affect configuration synchronization or OpenResty reload.

Minimal Integration Flow

1. Start Server and sign in.
2. Prepare agent_token or discovery_token.
3. Start Agent and confirm the node is online.
4. Create an enabled site configuration.
5. Publish and activate a new version.
6. Check node detail and apply logs.
7. Visit the domain or verify with curl.

Upgrade and Uninstall

Server:

• Root users can check and upgrade stable Server releases from the top bar.
• Preview releases can be checked manually.
• Binary upload upgrades are also supported.

Agent:

• Agents follow stable releases by default.
• Agent autoupdate requires the GitHub Release to include both the target binary and a matching .sha256 checksum file; the download must pass SHA-256 validation before the local executable is replaced.
• The install script can be rerun to reinstall or upgrade.
• Preview upgrades require manual action.

Uninstall Agent:

curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash

The uninstall script stops Agent and removes the systemd service and install directory. It does not remove the local OpenResty installation.

Validation Commands

Server:

cd openflare_server
GOCACHE=/tmp/openflare-go-cache go test ./...

Agent:

cd openflare_agent
GOCACHE=/tmp/openflare-go-cache go test ./...

Frontend:

cd openflare_server/web
pnpm build

Swagger:

go install github.com/swaggo/swag/cmd/swag@v1.16.4
cd openflare_server
swag init -g main.go -o docs