OpenFlare/docs/en/guide/usage.md

Usage

You will learn what sites, origins, certificates, versions, nodes, and observability mean in OpenFlare, and which order to follow for daily operations.

OpenFlare does not patch OpenResty configuration files online. You edit control-plane data in the UI; Agents pull and apply a full configuration only after you publish and activate a new version.

Core Concepts

Concept	Description
Site configuration	The reverse proxy aggregation object. One site can bind one or more domains.
Primary domain	The first item in the domains list.
Origin	The upstream service address, such as http://10.0.0.10:8080.
Configuration version	A full OpenResty configuration snapshot generated by a release. Historical versions are immutable.
Active version	The globally effective version. By default, all nodes consume the same active version.
Agent	The node-side process that registers, heartbeats, syncs, validates, reloads, and rolls back on failure.

Recommended Workflow

For a normal reverse proxy change:

1. Confirm that at least one Agent node is online.
2. Create or select an origin.
3. Create a site configuration with domains, upstreams, and site-level settings.
4. If HTTPS is needed, upload or select certificates and bind them per domain.
5. Preview the rendered configuration or review the diff.
6. Publish and activate a new version.
7. Check node details and apply logs.

Create a Site

A site requires at least:

Field	Requirement
Site name	Business-unique identifier. The primary domain is a common default.
Domains	At least one domain. The first domain is the primary domain. Each domain must be globally unique.
Origin URL	A valid http:// or https:// upstream address.
Enabled state	Only enabled sites are included in release rendering.

Example:

Field	Example
Site name	docs
Domain	docs.example.com
Origin URL	http://10.0.0.10:8080
Origin Host	docs.internal.example.com

Upstream rules:

• A single upstream may include a base path or query string, such as https://app.example.com/base?from=openflare.
• Multiple upstreams are used for load balancing and must be plain scheme://host[:port].
• Multiple upstreams in the same site should use the same protocol.

Manage Origins

Origins are a lightweight reusable address directory. When a site references an origin, the site still stores a renderable origin_url snapshot so historical versions can be replayed independently.

Recommended practices:

• Store frequently reused internal service addresses as origins.
• After changing an origin entry, check whether site snapshots need to be updated.
• Use preview or diff before publishing.

Enable HTTPS

HTTPS is bound per domain, not forced for the whole site.

1. Upload or create a certificate record.
2. Open the site configuration and select a certificate for each domain that needs HTTPS.
3. Domains without a certificate stay HTTP-only and are not automatically added to 443 ssl server blocks.
4. Publish and activate a new version.

If a site contains multiple domains, the Server groups HTTPS output by certificate while keeping all domains in the same site snapshot.

Release, Activate, and Roll Back

Standard flow:

Edit configuration -> Preview / diff -> Release -> Generate full version -> Activate version -> Agent pulls -> Agent applies locally -> Agent reports result

During release, the Server reads all enabled site configurations, OpenResty main template, performance options, cache options, and certificate assets. It renders a full configuration and calculates a checksum.

Rollback means reactivating an old version. The Agent then applies that version through the normal sync flow.

Nodes and Observability

Node pages answer three questions:

Question	Where to Check
Is the node online?	Node list or node detail
Which version is running?	Current version on the node detail page
Did the last apply succeed?	Apply logs

Access analytics and resource snapshots provide basic observability. OpenFlare only keeps access details for a controlled time window; it is not a general-purpose log platform. Use a dedicated logging system for long-term log search.

Common Scenarios

Add a Reverse Proxy for an Internal Service

1. Confirm the Agent node can reach the origin service.
2. Create a site configuration.
3. Add a domain, such as app.example.com.
4. Add an origin, such as http://10.0.0.20:8080.
5. Publish and activate the version.
6. Verify the domain from a browser or with curl.

Enable HTTPS for an Existing Domain

1. Prepare a certificate that covers the domain.
2. Upload or create the certificate record.
3. Bind the certificate to the domain in the site configuration.
4. Publish and activate a new version.
5. Verify with curl -I https://your-domain.

Roll Back a Failed Release

1. Open the configuration versions page.
2. Find the last known good version.
3. Activate that version again.
4. Check apply logs until the Agent reports success.
5. Fix the configuration and publish a new version.

Recommended Practices

• Set SESSION_SECRET explicitly in production and prefer PostgreSQL.
• Preview or diff changes before release.
• Check node details and apply logs after each release.
• Keep the network path from Agents to the Server stable.
• Do not manually edit OpenFlare-managed OpenResty files on nodes; the next release will overwrite them.