OpenFlare/docs/en/guide/development.md

Local Development

You will learn how to set up a local OpenFlare development environment, run the Server, Agent, and frontend, execute tests and builds, and understand the boundaries contributors must follow.

This page is for contributors. Product boundaries, data model constraints, API conventions, and frontend layering are defined in Development Constraints. This page focuses on executable local workflows.

Repository Layout

Path	Responsibility
openflare_server	Gin + GORM + SQLite/PostgreSQL monolithic control plane
openflare_server/web	Next.js management UI, statically exported and served by the Go Server
openflare_agent	Go Agent binary running on nodes
scripts	Agent install and uninstall scripts
docs	VitePress documentation site

Requirements

Tool	Requirement
Go	1.25+
Node.js	18+
pnpm	Use corepack enable to follow the project-declared version
Docker	Needed for Server containers, local integration, and the Agent Docker image
OpenResty	Needed when running Agent locally
PostgreSQL	Optional. The Server uses SQLite when PostgreSQL is not configured.

Install Frontend Dependencies

cd openflare_server/web
corepack enable
pnpm install

Build static assets served by the Go Server:

pnpm build

Run the Server

SQLite:

cd openflare_server
export SESSION_SECRET='dev-session-secret'
export SQLITE_PATH='./openflare-dev.db'
export LOG_LEVEL='debug'
go run .

PostgreSQL:

cd openflare_server
export SESSION_SECRET='dev-session-secret'
export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
export LOG_LEVEL='debug'
go run .

Default URL:

http://localhost:3000

Default account: root / 123456.

Run the Frontend Dev Server

The frontend dev server listens on 3001 by default and proxies API requests through NEXT_DEV_BACKEND_URL:

cd openflare_server/web
export NEXT_DEV_BACKEND_URL='http://127.0.0.1:3000'
pnpm dev

Open:

http://localhost:3001

Run the Agent

Create a local agent.json:

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

Run:

cd openflare_agent
export LOG_LEVEL='debug'
go run ./cmd/agent -config ./agent.json

When openresty_path is not configured, the Agent runs openresty. For debugging, set openresty_path, main_config_path, route_config_path, access_log_path, cert_dir, lua_dir, and runtime_config_dir as needed.

Tests

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 lint
pnpm typecheck
pnpm test
pnpm test:e2e

Docs:

cd docs
pnpm build

Builds

Frontend static assets:

cd openflare_server/web
pnpm build

Server binary:

cd openflare_server
go build -o openflare-server .

Agent binary:

cd openflare_agent
go build -o openflare-agent ./cmd/agent

Debugging Entrypoints

Scenario	Command or Location
Server logs	LOG_LEVEL=debug go run .
Agent logs	LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json
Swagger	http://localhost:3000/swagger/index.html
Frontend API proxy	NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
OpenResty config test	openresty -t -c ./data/etc/nginx/nginx.conf

Change Acceptance

Before contributing, confirm that:

1. The change fits Product Boundary.
2. The implementation follows Development Constraints.
3. It does not break release, sync, rollback, or upgrade flows.
4. Documentation is updated when configuration, deployment, API, or product boundaries change.
5. Risky changes include tests or equivalent integration verification.

Database schema changes must bump the database version and include explicit migration and validation logic from the previous version.