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:

```text
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.