StatePersistence.md

State Persistence

DockFlare maintains an internal state to ensure consistency and manage features like graceful deletion, even across restarts.

Purpose of the State File

DockFlare uses a JSON file (default: /app/data/state.json) to store information about:

1. Managed Ingress Rules: A list of hostnames and their associated service targets that DockFlare is currently managing based on container labels.
2. Deletion Timers: When a labeled container stops, DockFlare records the rule and the timestamp when its grace period expires.
3. Associated Container IDs: Links each managed rule back to the Docker container ID that created it.

How it Works

• Writing State: DockFlare updates the state.json file whenever:
  • A new rule is successfully added to Cloudflare.
  • A rule is marked for deletion (container stopped).
  • A rule is successfully deleted from Cloudflare after the grace period.
• Reading State (on Startup): When DockFlare starts:
  • It loads the existing state.json file (if it exists).
  • It queries the Docker API for currently running containers.
  • It queries the Cloudflare API for the current tunnel configuration and DNS records.
  • It performs a reconciliation process:
    • Compares running labeled containers against the state file and Cloudflare. Adds any missing rules found on running containers.
    • Checks rules in the state file against running containers. If a container associated with a rule in the state is no longer running, it ensures the rule is marked for deletion or deletes it if the grace period expired while DockFlare was down.
    • Compares rules in the state file against Cloudflare's configuration. Removes any rules found in Cloudflare that are not in the state file and not associated with a currently running labeled container (helping clean up potentially orphaned rules, though this depends on the reconciliation logic details).

Persistence Configuration

In the recommended Docker Compose setup, persistence is handled by a named volume:

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

volumes:
  # Defines the named volume managed by Docker
  dockflare_data:

This ensures that the state.json file within /app/data inside the container survives container restarts and updates.

If you are not using the volume mount, the state file will be ephemeral and lost whenever the container is removed. This means DockFlare will lose track of deletion timers and will need to fully reconcile its state from running containers and Cloudflare on every restart.

Resetting State

If you encounter persistent issues or want a completely fresh start (e.g., after major configuration changes or when Switching Between Modes), you might need to reset the state. You can do this by:

1. Stopping the DockFlare container (docker stop dockflare).
2. Removing the persistent volume (docker volume rm dockflare_data). Warning: This deletes the state.json file.
3. Restarting the DockFlare container (docker compose up -d).

DockFlare will then start with no prior state and rebuild it based on currently running containers and Cloudflare configuration.