StatePersistence.md

State Persistence

DockFlare maintains an internal state to ensure consistency, manage rules across restarts, and enable powerful features like graceful deletion and UI overrides.

The state.json File

DockFlare uses a JSON file, located at /app/data/state.json by default, to store a complete picture of its managed world. This is the application's "memory."

This state file stores critical information for each managed rule, including:

1. Core Rule Definition: The hostname, path, and service target for each ingress rule.
2. Rule Source: A flag indicating if the rule was generated from a docker container's labels or created manually through the Web UI.
3. Access Policy Configuration:
   • The ID of any associated Cloudflare Access Application created by DockFlare.
   • A UI Override Flag, which tells DockFlare if the Access Policy for a rule is being managed by the UI instead of the container's labels. This is the key to making UI-based changes persistent.
4. Graceful Deletion Timers: When a labeled container stops, DockFlare records when its grace period expires.
5. Associated Docker Information: For rules created from labels, it links the rule back to the specific Docker container ID.
6. Cloudflare Zone ID: The specific Cloudflare Zone ID associated with the rule's DNS record.

How State is Used

• Writing State: DockFlare updates the state.json file whenever a meaningful change occurs:
  • A new rule is created (from a container or the UI).
  • An Access Policy is modified via the UI.
  • A container stops, and its rule is marked for deletion.
  • A rule is successfully deleted from Cloudflare after its grace period expires.
• Reading State (on Startup): When DockFlare starts, a comprehensive reconciliation process begins:
  1. It loads the state.json file to understand the last known-good configuration.
  2. It queries the Docker API for all currently running containers and their labels.
  3. It compares the "desired state" (from running containers) with the "persisted state" (from state.json).
  4. It adds any new rules from running containers that aren't in its state.
  5. It verifies that rules in its state still correspond to running containers. If a container is gone, it ensures the rule is scheduled for deletion.
  6. Crucially, it respects the UI override flag, ensuring that even if a container's labels have changed, the UI-defined Access Policy remains in effect.

Configuring Persistence

In the recommended Docker Compose setup, persistence is handled by a named volume. This is essential for proper operation.

services:
  dockflare:
    # ... other config ...
    volumes:
      # Mounts the 'dockflare_data' volume to /app/data inside the container
      - dockflare_data:/app/data

volumes:
  # Defines the named volume, which Docker manages and preserves
  dockflare_data:
    name: dockflare_data

Without a persistent volume, the state.json file will be ephemeral and lost every time the container is recreated. This is not recommended, as DockFlare would lose track of deletion timers, manual rules, and all UI overrides.

Resetting State

If you encounter persistent issues or want a completely fresh start, you might need to reset the state.

1. Stop the DockFlare container (docker compose down).
2. Remove the persistent volume (docker volume rm dockflare_data). Warning: This permanently deletes state.json and all manual rules and UI overrides.
3. Restart the DockFlare container (docker compose up -d).

DockFlare will then start with a clean slate and rebuild its state based entirely on the currently running, labeled containers.