OpenFlare/docs/en/plan/Agent Unified OpenResty Binary Control Scheme.md

Agent Unified OpenResty Binary Control Scheme

Summary

Unify the Agent running model as "write to the managed configuration file, then call the openresty binary to execute -t, reload, start/restart". Docker deployment no longer has the Agent control another OpenResty container, but instead provides an independent ghcr.io/rain-kl/openflare-agent image; this image is based on openresty/openresty, with the Agent controller and OpenResty binary built-in.

Key Changes

• Agent runtime:

  • Remove the DockerExecutor / Docker container management logic from the production path.
  • Default to using openresty when openresty_path is not configured.
  • Uniformly execute binary calls with -c <main_config_path> to avoid misreading the OpenResty default configuration.
  • The apply flow is: backup -> write files -> openresty -t -c ... -> reload; if reload indicates it is not running, then start.
  • restart uses openresty -c ... -s quit followed by openresty -c ... to start, keeping fault tolerance for missing PIDs.

• Configurations and File Responsibilities:

  • Keep parser compatibility for old fields openresty_container_name, openresty_docker_image, and docker_binary, but mark them as deprecated and no longer involved in control logic.
  • Add access_log_path, defaulting to data_dir/var/log/openflare/access.log, and no longer placing access logs inside conf.d.
  • Add runtime_config_dir, defaulting to data_dir/etc/openflare, where pow_config.json is written.
  • cert_dir only writes certificate/key files; lua_dir only writes Lua code and static resources.
  • Support splitting files before writing: certificate files go into cert_dir, and pow_config.json goes into runtime_config_dir.

• Docker Agent Image:

  • Add openflare_agent/Dockerfile, with the runtime image based on openresty/openresty:alpine.
  • Defaults to OPENFLARE_OPENRESTY_PATH=openresty and OPENFLARE_DATA_DIR=/data.
  • Expose 80, 443, and 18081.
  • Support mounting /etc/openflare/agent.json, and also support environment variable configurations.
  • CI publishes independent multi-architecture images: ghcr.io/rain-kl/openflare-agent:<version> and latest.

• Agent Configuration Entry:

  • Keep -config + agent.json.
  • Add environment variable overrides/fallbacks: OPENFLARE_SERVER_URL, OPENFLARE_AGENT_TOKEN, OPENFLARE_DISCOVERY_TOKEN, OPENFLARE_NODE_NAME, OPENFLARE_NODE_IP, OPENFLARE_DATA_DIR, OPENFLARE_OPENRESTY_PATH, OPENFLARE_HEARTBEAT_INTERVAL, OPENFLARE_REQUEST_TIMEOUT, OPENFLARE_OPENRESTY_OBSERVABILITY_PORT.
  • If the configuration file does not exist but environment variables are sufficient, the Agent can start directly; if both exist, environment variables override file values.

• Scripts and Documentation:

  • install-agent.sh becomes a local OpenResty deployment script, adding --openresty-path and automatically finding openresty when not passed.
  • uninstall-agent.sh only uninstalls the Agent itself, and no longer deletes the Docker OpenResty container or image.
  • Update architecture, development constraints, deployment instructions, Agent guide, configuration item reference, README, and old Docker control descriptions in English image documents.

Public Interfaces

• Add Agent configuration fields:

  • access_log_path
  • runtime_config_dir

• Deprecated but compatibly read:

  • openresty_container_name
  • openresty_docker_image
  • docker_binary

• Add Docker image:

  • ghcr.io/rain-kl/openflare-agent

• Target Docker execution method examples:

  • Mount configuration file: -v ./agent.json:/etc/openflare/agent.json
  • Or environment variables: -e OPENFLARE_SERVER_URL=... -e OPENFLARE_AGENT_TOKEN=...

Test Plan

• openflare_agent/internal/config:

  • Default openresty_path is openresty.
  • Old Docker fields can be read but do not affect the executor.
  • Environment variables can start the Agent without a configuration file and can override the configuration file.
  • New default paths conform to responsibility boundaries.

• openflare_agent/internal/nginx:

  • Binary commands all include -c <main_config_path>.
  • Apply success, reload failure rollback, and start fallback when not running.
  • pow_config.json is no longer written to cert_dir or lua_dir.
  • Stale cert_dir/pow_config.json and lua_dir/pow_config.json will be cleaned up.
  • access log is rendered to access_log_path.
  • checksum can still uniformly include the main config, route config, certificates, and PoW config into comparisons.

• Integration Regression:

  • cd openflare_agent && GOCACHE=/tmp/openflare-go-cache go test ./...
  • cd openflare_server && GOCACHE=/tmp/openflare-go-cache go test ./...
  • Dockerfile build smoke test: build the Agent image and start it using env-only configuration to the executable stage.

Assumptions

• Docker Agent image name is fixed as ghcr.io/rain-kl/openflare-agent.
• Old Docker control fields are compatibly preserved but are no longer a supported behavior.
• This phase does not modify Server APIs, does not modify database models, and does not introduce remote command capabilities.
• The OpenResty main configuration template continues to be generated by the Server; the Agent is only responsible for local path replacement, file landing, and binary control.