OpenFlare/docs/en/design/development.md

Local Development

You will learn: How to build OpenFlare's local development environment, start the Server, the Agent, and the Admin Frontend, run test and build commands, and understand the boundaries to respect before contributing code.

This page is aimed at contributors. Product boundaries, data model constraints, API conventions, and frontend layering specifications are governed by Development Constraints; this page only provides actionable workflows for local development.

Repository Structure

For details on the physical directory structure and responsibilities of each module (Server, Agent, Frontend, etc.), see Repository Structure.

Environment Requirements

Item	Requirement
Go	1.25+
Node.js	18+
pnpm	Recommended enabling via corepack enable
Docker	Required for Server containers, local integration testing, and Agent Docker images
OpenResty	Required to execute openresty locally when running the Agent
PostgreSQL	Optional; if not configured, the Server defaults to SQLite

Initializing Frontend Dependencies

cd openflare_server/web
corepack enable
pnpm install

Build the static assets hosted by the Go Server:

pnpm build

Starting the Server

SQLite Mode:

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

PostgreSQL Mode:

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 access URL:

http://localhost:3000

The default credentials are root / 123456.

Starting the Frontend Dev Server

The frontend dev server listens to port 3001 by default and proxies requests to the backend via NEXT_DEV_BACKEND_URL:

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

Access:

http://localhost:3001

Starting 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

If openresty_path is not configured, the Agent calls openresty by default. For debugging, you can explicitly configure openresty_path, main_config_path, route_config_path, access_log_path, cert_dir, lua_dir, and runtime_config_dir.

Running 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

Building

Admin 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

Context	Command or Path
Server Logs	LOG_LEVEL=debug go run .
Agent Logs	LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json
Swagger Docs	http://localhost:3000/swagger/index.html
Frontend API Proxy	NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
OpenResty Validation	openresty -t -c ./data/etc/nginx/nginx.conf

Code Style & Change Admission

Before contributing, verify:

1. The requirement matches Product Boundaries.
2. The implementation conforms to Development Constraints.
3. The change does not disrupt publishing, sync, rollback, or upgrading lifecycles.
4. Update corresponding documentation if configurations, deployments, APIs, or boundaries change.
5. High-risk edits must be accompanied by unit tests or equivalent integration testing.

Database schema alterations must elevate the database version number and supply explicit migration and validation methods from the previous version.