### Example Zone and Policy Configuration

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/en/Zone-Default-Policies.md

Illustrates a mixed development zone setup with a default policy and a specific override for a subdomain.

```text
Zone: dev.company.com
Policy: Developer Team Authentication
Result: All dev services protected by default (*.dev.company.com)
Specific overrides: public-demo.dev.company.com → public-default-bypass
```

--------------------------------

### Install Dockflare with One-Liner Script

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/README.MD

Execute this script to install Dockflare. It guides you through choosing an install directory, a local UI port, and optionally configuring Cloudflare Tunnel and the Email profile.

```bash
bash <(curl -fsSL https://dockflare.app/install.sh)
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/chrispybacon-dev/dockflare/wiki/EnvironmentVariables.md

This example shows how to configure DockFlare using an .env file, including required settings, internal mode options, and optional customizations. It also includes commented-out examples for external mode.

```dotenv
# --- Required Settings ---
CF_API_TOKEN=your_cloudflare_api_token_here
CF_ACCOUNT_ID=your_cloudflare_account_id_here
CF_ZONE_ID=your_cloudflare_zone_id_here

# --- Configuration for Internal (Managed) Mode ---
TUNNEL_NAME=my-dockflare-tunnel
CLOUDFLARED_NETWORK_NAME=cloudflare-net

# --- Optional Customizations ---
# Use a custom label prefix (e.g., 'cf.ingress.')
LABEL_PREFIX=dockflare
# Set a 10-minute grace period
GRACE_PERIOD_SECONDS=600
# Set your timezone
TZ=America/New_York

# --- Example for External Mode (mutually exclusive with Internal Mode settings) ---
# USE_EXTERNAL_CLOUDFLARED=true
# EXTERNAL_TUNNEL_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

--------------------------------

### Start DockFlare Stack

Source: https://github.com/chrispybacon-dev/dockflare/wiki/Switching‐Between‐Modes.md

Use this command to start DockFlare after updating its configuration for mode switching.

```bash
docker compose up -d
```

--------------------------------

### Deploy Dockflare with Docker Compose

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

After setting up the docker-compose.yml, use this command to start the services in detached mode. Access the Dockflare setup wizard via HTTP.

```bash
docker compose up -d
# Then open http://your-server:5000 and complete the setup wizard
```

--------------------------------

### Example Output of Duplicate Policy Cleanup Utility (Dry Run)

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/CLI_USAGE.md

This is an example of the detailed output you can expect when running the duplicate policy cleanup utility in dry run mode, showing identified duplicates, actions that would be taken, and a summary.

```text
============================================================
DUPLICATE POLICY CLEANUP UTILITY
============================================================
Mode: DRY RUN (no changes will be made)

Step 1: Fetching all reusable policies from Cloudflare...
Found 15 total policies

Step 2: Grouping policies by name...

Step 3: Identifying duplicates...
✗ Found 2 policy names with duplicates:

  Policy: 'DockFlare-Default-Public-Access-Bypass' (3 instances)
  Policy: 'DockFlare-AccessGroup-idp-blocker' (3 instances)

Total policies to delete: 4

Step 4: Checking Access Applications for policy usage...
Found 12 Access Applications to check

Step 5: Processing duplicates...

Processing: 'DockFlare-Default-Public-Access-Bypass'
  ✓ Keeping: ID=abc123 (created: 2025-01-01T10:00:00Z)
  ✗ Would delete: ID=def456 (created: 2025-01-02T11:00:00Z)
  ✗ Would delete: ID=ghi789 (created: 2025-01-03T12:00:00Z)

Processing: 'DockFlare-AccessGroup-idp-blocker'
  ✓ Keeping: ID=jkl012 (created: 2025-01-01T09:00:00Z)
  ⚠ Found 2 Access Application(s) using duplicate policies:
    - App: 'DockFlare-app1.example.com' (domain: app1.example.com)
      Using policy: mno345
    - App: 'DockFlare-app2.example.com' (domain: app2.example.com)
      Using policy: pqr678
  📝 Updating applications to use kept policy ID jkl012...
    ✓ Updated app 'DockFlare-app1.example.com': mno345 → jkl012
    ✓ Updated app 'DockFlare-app2.example.com': pqr678 → jkl012
  ✗ Would delete: ID=mno345 (created: 2025-01-02T10:00:00Z)
  ✗ Would delete: ID=pqr678 (created: 2025-01-03T11:00:00Z)

Step 6: Updating state.json with correct policy IDs...
DRY RUN: Would update state.json with the following changes:
  Group 'public-default-bypass': def456 → abc123 (policy: DockFlare-Default-Public-Access-Bypass)
  Group 'idp-blocker': mno345 → jkl012 (policy: DockFlare-AccessGroup-idp-blocker)

============================================================
SUMMARY
============================================================
Total policies scanned: 15
Duplicate policy names found: 2
Policies that would be deleted: 4
Policies that would be kept: 2
============================================================

```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/CONTRIBUTING.md

Install Node.js dependencies using npm. This should be done in the 'dockflare' subdirectory where the package.json file is located.

```bash
npm install
```

--------------------------------

### Start Agent Container

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Starts or reconciles the local cloudflared container managed by Dockflare. Ensures the agent is running.

```bash
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  https://dockflare.example.com/api/v2/agent/start
```

--------------------------------

### Setup Cloudflare Service Token

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/agents.html

Initiates the setup process for a Cloudflare service token. It adds a loading state to the button and disables it during the API call, then updates the UI based on the result.

```javascript
document.getElementById('btn-cf-token-setup').addEventListener('click', async () => { const btn = document.getElementById('btn-cf-token-setup'); btn.classList.add('loading'); btn.disabled = true; const result = await apiCall('/api/v2/agents/cf-service-token/setup', 'POST'); btn.classList.remove('loading'); btn.disabled = false; if (result && result.status === 'success') { await dfAlert(t('js.alert.cf_setup_success'), t('js.alert.cf_setup_success_title')); loadCfTokenStatus(); } });
```

--------------------------------

### POST /api/v2/agent/start

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Starts or reconciles the local cloudflared container managed by DockFlare.

```APIDOC
## POST /api/v2/agent/start

### Description
Starts (or reconciles) the local cloudflared container managed by DockFlare.

### Method
POST

### Endpoint
`/api/v2/agent/start`

### Request Example
```bash
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  https://dockflare.example.com/api/v2/agent/start
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Cloudflared container started."
}
```
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/CONTRIBUTING.md

Install Python dependencies using pip. It is recommended to do this within a virtual environment to avoid conflicts.

```bash
pip install -r requirements.txt
```

--------------------------------

### Authentication Example

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Demonstrates how to authenticate API requests using a Bearer token. This is required for most API calls.

```APIDOC
## Authentication

All API calls require the `Authorization: Bearer <MASTER_API_KEY>` header unless noted. Agent endpoints use per-agent API keys. UI-only endpoints require session login.

```bash
# All API calls require this header (except agent endpoints and UI-only endpoints)
curl -H "Authorization: Bearer $DOCKFLARE_API_KEY" https://dockflare.example.com/api/v2/ping

# Response:
# {"status": "ok", "timestamp": 1748000000}
```
```

--------------------------------

### Docker Compose for Wildcard Domains

Source: https://github.com/chrispybacon-dev/dockflare/wiki/UsingMultipleDomainsIndexedLabels.md

This example demonstrates using a wildcard hostname label to route all subdomains of a given domain to a single service.

```yaml
version: '3.8'

services:
  # Your DockFlare service definition...
  dockflare:
    # ... (Configuration from Quick Start) ...
    networks:
      - cloudflare-net

  # This service will handle all requests to *.apps.example.com
  wildcard-handler:
    image: traefik/whoami # An example service that can show what hostname it received
    container_name: wildcard-handler
    restart: unless-stopped
    networks:
      - cloudflare-net
    labels:
      # --- DockFlare Labels ---
      - "dockflare.enable=true"

      # Define the wildcard hostname. This will match anything.apps.example.com.
      - "dockflare.hostname=*.apps.example.com"

      # Define the single target service for all matching subdomains
      - "dockflare.service=http://wildcard-handler:80"

```

--------------------------------

### Public Blog Zone Configuration

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/en/Zone-Default-Policies.md

Example configuration for a public blog zone where all subdomains are intended to be publicly accessible.

```text
Zone: blog.example.com
Policy: public-default-bypass
Result: All subdomains publicly accessible (*.blog.example.com)
```

--------------------------------

### DockFlare Missing @login_required Decorator Example

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/SECURITY AUDIT/SECURITY_FIX_PLAN_v3.0.3.md

This example highlights a new IdP endpoint that lacks the necessary @login_required decorator, making it vulnerable to unauthenticated access.

```python
@api_v2_bp.route('/idp/sync', methods=['POST'])
def api_sync_idps():  # ⚠️ NO @login_required
```

--------------------------------

### Manual Docker Compose Setup for DockFlare Agent

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/en/Multi-Server-Agent.md

Configure the DockFlare agent using a manual `docker-compose.yml` setup on the agent host. This requires setting environment variables for master URL, API key, and optionally the Docker host and cloudflared image.

```bash
# .env on the agent host
DOCKFLARE_MASTER_URL=https://dockflare.example.com
DOCKFLARE_API_KEY=agent_api_key_goes_here
DOCKER_HOST=tcp://docker-socket-proxy:2375
# Optional: pin the cloudflared image (accepts repo:tag or repo@sha256:<digest>)
# Defaults to cloudflare/cloudflared:latest when not set
CLOUDFLARED_IMAGE=cloudflare/cloudflared:latest
LOG_LEVEL=info
TZ=Europe/Zurich

```

--------------------------------

### Get Agent Deploy Info

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Retrieve master URL, API key, and image for agent deployment. Requires an authorization token.

```bash
curl -H "Authorization: Bearer $KEY" \
  https://dockflare.example.com/api/v2/agents/deploy-info/key_abc123
```

--------------------------------

### GET /api/v2/agents/deploy-script/<key_id>

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Returns a shell deploy script for a given pre-generated key, intended for execution on a remote host.

```APIDOC
## GET /api/v2/agents/deploy-script/<key_id>

### Description
Returns a shell deploy script for a given pre-generated key (for pasting on remote host).

### Method
GET

### Endpoint
`/api/v2/agents/deploy-script/<key_id>`

### Parameters
#### Path Parameters
- **key_id** (string) - Required - The ID of the pre-generated key.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **script** (string) - The shell script for deploying the agent.

#### Response Example
```json
{
  "status": "success",
  "script": "#!/bin/bash\ndocker run -d --name dockflare-agent ..."
}
```
```

--------------------------------

### Internal Tools Zone Configuration

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/en/Zone-Default-Policies.md

Example configuration for an internal tools zone where all subdomains require authentication with a company email.

```text
Zone: internal.company.com
Policy: Company Email Authentication
Result: All subdomains require @company.com email (*.internal.company.com)
```

--------------------------------

### GET /api/v2/agents/deploy-info/<key_id>

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Retrieves structured deploy information, including master URL, key, and image, for agent deployment.

```APIDOC
## GET /api/v2/agents/deploy-info/<key_id>

### Description
Returns structured deploy information (master URL, key, image) for agent deployment.

### Method
GET

### Endpoint
/api/v2/agents/deploy-info/<key_id>

### Parameters
#### Path Parameters
- **key_id** (string) - Required - The unique identifier for the agent key.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **master_url** (string) - The URL of the Dockflare master.
- **api_key** (string) - The API key for the agent.
- **image** (string) - The Docker image to be used for the agent.

### Response Example
```json
{
  "status": "success", 
  "master_url": "https://dockflare.example.com", 
  "api_key": "...", 
  "image": "alplat/dockflare-agent:stable"
}
```
```

--------------------------------

### Clone DockFlare Repository

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/CONTRIBUTING.md

Clone your forked repository locally to start making changes. Ensure you are using the correct repository URL.

```bash
git clone https://github.com/ChrispyBacon-dev/DockFlare.git
```

--------------------------------

### GET /api/v2/agents/<agent_id>/commands

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Agent polls this endpoint to retrieve pending commands such as starting tunnels or redeploying services.

```APIDOC
## GET /api/v2/agents/<agent_id>/commands

### Description
Agent polls this endpoint for pending commands (start tunnel, stop tunnel, redeploy, etc.).

### Method
GET

### Endpoint
/api/v2/agents/<agent_id>/commands

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **commands** (array) - A list of pending commands for the agent.
  - **id** (string) - The unique identifier of the command.
  - **type** (string) - The type of command (e.g., 'start_tunnel').
  - **params** (object) - Parameters required for the command.

### Response Example (no pending commands)
```json
{
  "commands": []
}
```

### Response Example (with command)
```json
{
  "commands": [
    {
      "id": "cmd_001",
      "type": "start_tunnel",
      "params": {}
    }
  ]
}
```
```

--------------------------------

### Docker Compose with Wildcard Hostname

Source: https://github.com/chrispybacon-dev/dockflare/wiki/UsingWildcardDomains.md

Configure a wildcard route for *.apps.example.com pointing to a single backend service. This example uses traefik/whoami to demonstrate receiving requests.

```yaml
version: '3.8'

services:
  # Your DockFlare service definition...
  dockflare:
    # ... (Configuration from Quick Start) ...
    networks:
      - cloudflare-net

  # This service will handle all requests to *.apps.example.com
  wildcard-handler:
    image: traefik/whoami # An example service that can show what hostname it received
    container_name: wildcard-handler
    restart: unless-stopped
    networks:
      - cloudflare-net
    labels:
      # --- DockFlare Labels ---
      - "dockflare.enable=true"

      # Define the wildcard hostname. This will match anything.apps.example.com.
      - "dockflare.hostname=*.apps.example.com"

      # Define the single target service for all matching subdomains
      - "dockflare.service=http://wildcard-handler:80"
```

--------------------------------

### Basic Ingress Configuration Example

Source: https://github.com/chrispybacon-dev/dockflare/wiki/ContainerLabels.md

A basic Docker Compose service definition demonstrating the essential labels for enabling and configuring a container's ingress via Dockflare.

```yaml
services:
  my-app:
    image: nginx
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=my-app.example.com"
      - "dockflare.service=http://my-app:80"
```

--------------------------------

### Process Docker Container Start Event

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Processes a Docker container start event by reading dockflare labels, building ingress rules, handling access policy setup, updating state, and triggering a Cloudflare configuration update. This is called automatically by the docker_event_listener.

```python
from app.core.docker_handler import process_container_start
import docker

client = docker.from_env()
container = client.containers.get("my-container-id")
# Called automatically by docker_event_listener on "start" action
process_container_start(container)
# Result: managed_rules updated, DNS record created, tunnel config pushed to Cloudflare
```

--------------------------------

### Example Access Group Configuration

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/en/Identity-Providers.md

This configuration demonstrates how to restrict access to users who authenticate via a specific IdP (e.g., google-main) and have an email address matching a defined list or domain.

```text
- Identity Providers: google-main
- Allowed Emails: admin@example.com, user@example.com, @contractor-domain.com
```

--------------------------------

### Docker Compose Configuration for Dockflare Email Services

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/email.html

This YAML file defines the services, volumes, and networks for a Dockflare setup with email capabilities. Replace `TLD` placeholders with your domain and run `docker compose --profile email up -d` to start the services.

```yaml
version: '3.8'

services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy:v0.4.1
    container_name: docker-socket-proxy
    restart: unless-stopped
    logging:
      driver: "none"
    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
      - CONTAINERS=1
      - EVENTS=1
      - NETWORKS=1
      - IMAGES=1
      - POST=1
      - PING=1
      - INFO=1
      - EXEC=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - dockflare-internal

  dockflare-init:
    image: alpine:3.20
    command: ["sh", "-c", "chown -R ${DOCKFLARE_UID:-65532}:${DOCKFLARE_GID:-65532} /app/data"]
    volumes:
      - dockflare_data:/app/data
    networks:
      - dockflare-internal
    restart: "no"

  dockflare:
    image: alplat/dockflare:stable
    container_name: dockflare
    restart: unless-stopped
    ports:
      - "5000:5000"
    labels:
      - dockflare.enable=true
      - dockflare.hostname=dockflare.TLD  # replace with your domain
      - dockflare.service=http://dockflare:5000
    volumes:
      - dockflare_data:/app/data
    environment:
      - REDIS_URL=redis://redis:6379/0
      - REDIS_DB_INDEX=0
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
    depends_on:
      docker-socket-proxy:
        condition: service_started
      dockflare-init:
        condition: service_completed_successfully
      redis:
        condition: service_started
    networks:
      - cloudflare-net
      - dockflare-internal

  redis:
    image: redis:7-alpine
    container_name: dockflare-redis
    restart: unless-stopped
    command: ["redis-server", "--save", "", "--appendonly", "no"]
    logging:
      driver: "none"
    volumes:
      - dockflare_redis:/data
    networks:
      - dockflare-internal

  dockflare-mail-manager:
    image: alplat/dockflare-mail-manager:stable
    container_name: dockflare-mail-manager
    restart: unless-stopped
    profiles: ["email"]
    environment:
      - DOCKFLARE_MASTER_URL=http://dockflare:5000
      - MAIL_DATA_PATH=/data
    volumes:
      - mail_data:/data
    depends_on:
      dockflare:
        condition: service_started
    networks:
      - cloudflare-net
      - dockflare-internal

  dockflare-webmail:
    image: alplat/dockflare-webmail:stable
    container_name: dockflare-webmail
    restart: unless-stopped
    profiles: ["email"]
    environment:
      - DOCKFLARE_MASTER_URL=https://dockflare.TLD  # replace with your domain
    labels:
      - dockflare.enable=true
      - dockflare.hostname=mail.dockflare.TLD  # replace with your domain
      - dockflare.service=http://dockflare-webmail:80
    depends_on:
      dockflare-mail-manager:
        condition: service_started
    networks:
      - cloudflare-net
      - dockflare-internal

volumes:
  dockflare_data:
  dockflare_redis:
  mail_data:

networks:
  cloudflare-net:
    name: cloudflare-net
    external: true
  dockflare-internal:
    name: dockflare-internal

```

--------------------------------

### Configure Multi-Hostname Access

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/en/Container-Labels.md

This example demonstrates exposing two different hostnames from a single container. The first hostname (`app.example.com`) routes to the main web interface on port 80. The second hostname (`api.example.com`) routes to the API on port 3000 and is secured with a specific Access Group.

```yaml
services:
  my-multi-service:
    image: my-app
    labels:
      - "dockflare.enable=true"

      # --- Definition 0 ---
      - "dockflare.0.hostname=app.example.com"
      - "dockflare.0.service=http://my-multi-service:80"

      # --- Definition 1 ---
      - "dockflare.1.hostname=api.example.com"
      - "dockflare.1.service=http://my-multi-service:3000"
      - "dockflare.1.access.group=api-access-policy"
```

--------------------------------

### Start Docker Event Listeners

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Starts background threads that subscribe to Docker events. These events are filtered by a label prefix and are used to trigger container start and stop processing.

```APIDOC
## start_event_listeners(stop_event)

### Description
Background thread function that subscribes to Docker events filtered by label prefix and dispatches to `process_container_start` or `schedule_container_stop`.

### Signature
start_event_listeners(stop_event)

### Parameters
#### Path Parameters
- **stop_event** (threading.Event) - Required - An event object to signal the listeners to stop.

### Usage
```python
from app.core.docker_handler import start_event_listeners
import threading

stop_event = threading.Event()
threads = start_event_listeners(stop_event)
for t in threads:
    t.start()
# Listens for: dockflare.enable, cloudflare.tunnel.enable, and custom prefix
# Reconnects automatically on connection errors (up to 5 consecutive failures)
```
```

--------------------------------

### Enable Dockflare with Hostname and Service Target

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/README.MD

Use these labels to enable Dockflare for a service, define its hostname, and specify the service target. This example configures 'picoshare'.

```yaml
services:
  picoshare:
    image: mtlynch/picoshare
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=files.example.com"
      - "dockflare.service=http://picoshare:8080"
      - "dockflare.access.group=nas-family"
```

--------------------------------

### Initialize Theme and Set Data Attribute

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/setup/base.html

This script initializes the theme by checking local storage or user's system preference. It then sets a 'data-theme' attribute on the HTML element to apply the correct theme styles.

```javascript
(function(){var t=localStorage.getItem('theme')||(window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light');document.documentElement.setAttribute('data-theme',t);})();
```

--------------------------------

### Docker Compose with Indexed Labels for Multiple Domains

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/dockflare/app/templates/docs/ch-barnduetsch/Using-Multiple-Domains-Indexed-Labels.md

This example demonstrates how to configure a Docker service with multiple ingress rules using indexed labels. Rule 0 handles the web UI publicly, while Rule 1 secures the API with an access group. Base labels provide fallback values for common configurations.

```yaml
services:
  my-app:
    image: my-application
    restart: unless-stopped
    networks:
      - cloudflare-net
    labels:
      - "dockflare.enable=true"

      # --- Base Labels (Fallback) ---
      # This service is used by rule 0, as it's not specified there.
      - "dockflare.service=http://my-app:80" 

      # --- Rule 0: The Web UI ---
      - "dockflare.0.hostname=app.example.com"
      # No 'service' label here, so it falls back to the base one.
      # No 'access.group' label, so it's public.

      # --- Rule 1: The API ---
      - "dockflare.1.hostname=api.example.com"
      # Override the service to point to the API port.
      - "dockflare.1.service=http://my-app:3000"
      # Add a specific access policy for this rule only.
      - "dockflare.1.access.group=api-users-policy"
```

--------------------------------

### Restart DockFlare Container

Source: https://github.com/chrispybacon-dev/dockflare/wiki/SwitchingBetweenModes.md

Start DockFlare after updating its configuration for external mode. Use `docker start` or `docker compose up -d --force-recreate` if the container or volume was removed.

```bash
docker start dockflare
```

```bash
# Or if you removed the container/volume:
# docker compose up -d --force-recreate
```

--------------------------------

### POST /api/v2/agents/cf-service-token/setup

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Sets up a Cloudflare Zero Trust service token for agent-to-master authentication.

```APIDOC
## POST /api/v2/agents/cf-service-token/setup

### Description
Sets up a Cloudflare Zero Trust service token for agent-to-master authentication (replaces IP-based trust).

### Method
POST

### Endpoint
/api/v2/agents/cf-service-token/setup

### Request Example
```bash
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  https://dockflare.example.com/api/v2/agents/cf-service-token/setup
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **client_id** (string) - The client ID for the service token.
- **client_secret** (string) - The client secret for the service token.

### Response Example
```json
{
  "status": "success",
  "client_id": "xxx.access",
  "client_secret": "yyy"
}
```
```

--------------------------------

### Start Docker Event Listeners

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Starts background threads that subscribe to Docker events filtered by a label prefix. These threads dispatch events to `process_container_start` or `schedule_container_stop`. Reconnects automatically on connection errors.

```python
from app.core.docker_handler import start_event_listeners
import threading

stop_event = threading.Event()
threads = start_event_listeners(stop_event)
for t in threads:
    t.start()
# Listens for: dockflare.enable, cloudflare.tunnel.enable, and custom prefix
# Reconnects automatically on connection errors (up to 5 consecutive failures)
```

--------------------------------

### Process Container Start Event

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Processes a Docker container start event. It reads Dockflare labels, builds ingress rules, sets up access policies, updates state, and triggers a Cloudflare configuration update.

```APIDOC
## process_container_start(container_obj)

### Description
Processes a Docker container start event. Reads `dockflare.*` labels, builds ingress rule(s), handles access policy setup, updates state, and calls `update_cloudflare_config()`.

### Signature
process_container_start(container_obj)

### Parameters
#### Path Parameters
- **container_obj** (docker.models.containers.Container) - Required - The Docker container object that has started.

### Usage
```python
from app.core.docker_handler import process_container_start
import docker

client = docker.from_env()
container = client.containers.get("my-container-id")
# Called automatically by docker_event_listener on "start" action
process_container_start(container)
# Result: managed_rules updated, DNS record created, tunnel config pushed to Cloudflare
```
```

--------------------------------

### GET /api/v2/idp/list

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Lists all configured identity providers.

```APIDOC
## GET /api/v2/idp/list

### Description
Lists all configured identity providers.

### Method
GET

### Endpoint
/api/v2/idp/list

### Request Example
```bash
curl -b "session=..." https://dockflare.example.com/api/v2/idp/list
```
```

--------------------------------

### GET /api/v2/auth/providers

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Lists configured OAuth/OIDC providers.

```APIDOC
## GET /api/v2/auth/providers

### Description
Lists configured OAuth/OIDC providers.

### Method
GET

### Endpoint
/api/v2/auth/providers

### Request Example
```bash
curl -b "session=..." https://dockflare.example.com/api/v2/auth/providers
```

### Response
#### Success Response (200)
- **providers** (array) - A list of configured OAuth providers.
  - **id** (string) - The unique identifier for the provider.
  - **type** (string) - The type of the provider (e.g., google, oidc).
  - **name** (string) - The display name of the provider.
  - **enabled** (boolean) - Indicates if the provider is enabled.

### Response Example
```json
{
  "providers": [{"id": "google", "type": "google", "name": "Google", "enabled": true}]
}
```
```

--------------------------------

### GET /api/v2/auth/settings

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Returns current authentication configuration.

```APIDOC
## GET /api/v2/auth/settings

### Description
Returns current authentication configuration.

### Method
GET

### Endpoint
/api/v2/auth/settings

### Request Example
```bash
curl -b "session=..." https://dockflare.example.com/api/v2/auth/settings
```

### Response
#### Success Response (200)
- **disable_password_login** (boolean) - Indicates if password login is disabled.
- **oauth_providers** (array) - A list of configured OAuth providers.
- **authorized_users** (array) - A list of email addresses authorized for login.

### Response Example
```json
{
  "disable_password_login": false,
  "oauth_providers": [...],
  "authorized_users": ["admin@example.com"]
}
```
```

--------------------------------

### Register New Agent

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Register an agent with the Master using its pre-generated API key. The agent automatically calls this on startup. Requires agent key authentication.

```bash
# Agent calls this with its own key in Authorization header
curl -X POST \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "homelab-server-2",
    "hostname": "homelab2.local",
    "docker_host": "unix:///var/run/docker.sock"
  }' \
  https://dockflare.example.com/api/v2/agents/register
```

--------------------------------

### GET /api/v2/tunnels/account

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Lists all Cloudflare tunnels configured in the account.

```APIDOC
## GET /api/v2/tunnels/account

### Description
Lists all Cloudflare tunnels in the configured account.

### Method
GET

### Endpoint
`/api/v2/tunnels/account`

### Response
#### Success Response (200)
- **tunnels** (array) - A list of tunnel objects, each containing `id`, `name`, and `status`.

#### Response Example
```json
{
  "tunnels": [
    {"id": "abc123", "name": "dockflare-tunnel", "status": "healthy"},
    ...
  ]
}
```
```

--------------------------------

### Get Lightweight Service Snapshot

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Retrieves a concise list of managed services, including their hostname, service URL, status, and source. Requires API key authentication.

```bash
curl -H "Authorization: Bearer $KEY" https://dockflare.example.com/api/v2/services

# Response:
# {
#   "services": [
#     {"hostname": "app.example.com", "service": "http://myapp:80", "status": "active", "source": "docker"},
#     {"hostname": "tool.example.com", "service": "https://internal:443", "status": "pending_deletion", "source": "manual"}
#   ]
# }
```

--------------------------------

### GET /api/v2/reconciliation-status

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Returns the current reconciliation progress status.

```APIDOC
## GET /api/v2/reconciliation-status

### Description
Returns the current reconciliation progress.

### Method
GET

### Endpoint
`/api/v2/reconciliation-status`

### Response
#### Success Response (200)
- **in_progress** (boolean) - Indicates if reconciliation is currently running.
- **progress** (integer) - The percentage of completion.
- **total_items** (integer) - The total number of items to process.
- **processed_items** (integer) - The number of items already processed.
- **status** (string) - The overall status of the reconciliation.

#### Response Example
```json
{
  "in_progress": false,
  "progress": 100,
  "total_items": 5,
  "processed_items": 5,
  "status": "Complete"
}
```
```

--------------------------------

### GET /api/v2/auth/users

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Lists authorized users for OAuth login allowlist.

```APIDOC
## GET /api/v2/auth/users

### Description
Lists authorized users (for OAuth login allowlist).

### Method
GET

### Endpoint
/api/v2/auth/users

### Request Example
```bash
curl -b "session=..." https://dockflare.example.com/api/v2/auth/users
```

### Response
#### Success Response (200)
- **authorized_users** (array) - A list of email addresses authorized for OAuth login.

### Response Example
```json
{
  "authorized_users": ["admin@example.com", "user2@example.com"]
}
```
```

--------------------------------

### GET /api/v2/agents

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Retrieves a list of all registered agents and their current status.

```APIDOC
## GET /api/v2/agents

### Description
Lists all registered agents and their status.

### Method
GET

### Endpoint
/api/v2/agents

### Response
#### Success Response (200)
- **agents** (object) - An object containing details for each registered agent.
  - **agent_id** (string) - The unique identifier of the agent.
    - **display_name** (string) - The display name of the agent.
    - **status** (string) - The current status of the agent (e.g., 'online').
    - **last_heartbeat** (string) - The timestamp of the last agent heartbeat.
    - **assigned_tunnel_id** (string) - The ID of the tunnel assigned to the agent.
    - **container_count** (integer) - The number of containers managed by the agent.

### Response Example
```json
{
  "agents": {
    "agent_xyz789": {
      "display_name": "homelab-server-2",
      "status": "online",
      "last_heartbeat": "2026-05-08T10:00:00Z",
      "assigned_tunnel_id": "abc123",
      "container_count": 3
    }
  }
}
```
```

--------------------------------

### Enable Dockflare with Access Policy and Email

Source: https://github.com/chrispybacon-dev/dockflare/blob/stable/README.MD

Configure Dockflare for a service with a specific access policy and authorized email addresses. This example sets up an 'internal-tool' with an 'authenticate' policy.

```yaml
services:
  internal-tool:
    image: nginx:latest
    labels:
      - "dockflare.enable=true"
      - "dockflare.hostname=tool.example.com"
      - "dockflare.service=http://internal-tool:80"
      - "dockflare.access.policy=authenticate"
      - "dockflare.access.email=admin@example.com,@example.com"
```

--------------------------------

### Docker Compose for Multiple Domains

Source: https://github.com/chrispybacon-dev/dockflare/wiki/UsingMultipleDomainsIndexedLabels.md

This example configures a single container to handle multiple ingress rules using indexed labels for different hostnames, paths, and access policies.

```yaml
version: '3.8'

services:
  # Your DockFlare service definition...
  dockflare:
    # ... (Configuration from Quick Start) ...
    networks:
      - cloudflare-net

  # A single container exposing multiple rules
  multi-app-gateway:
    image: traefik/whoami # A simple service that echoes request info
    container_name: multi-app-gateway
    restart: unless-stopped
    networks:
      - cloudflare-net
    labels:
      # 1. Enable DockFlare for this container (only needed once)
      - "dockflare.enable=true"

      # --- Rule 0: The main public website ---
      - "dockflare.0.hostname=www.example.com"
      - "dockflare.0.service=http://multi-app-gateway:80"
      # This rule is public by default as no access.policy is set.

      # --- Rule 1: The secure API on a specific path ---
      - "dockflare.1.hostname=www.example.com"
      - "dockflare.1.path=/api"
      - "dockflare.1.service=http://multi-app-gateway:80"
      - "dockflare.1.access.policy=authenticate" # API requires login

      # --- Rule 2: A status page on a different domain ---
      - "dockflare.2.hostname=status.other-domain.org"
      - "dockflare.2.service=http://multi-app-gateway:80"
      - "dockflare.2.zonename=other-domain.org" # Specify the correct zone
      - "dockflare.2.access.policy=bypass" # Explicitly public

```

--------------------------------

### Basic API Authentication with cURL

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Demonstrates how to authenticate API calls using a bearer token. Ensure the DOCKFLARE_API_KEY environment variable is set.

```bash
# All API calls require this header (except agent endpoints and UI-only endpoints)
curl -H "Authorization: Bearer $DOCKFLARE_API_KEY" https://dockflare.example.com/api/v2/ping
```

--------------------------------

### GET /api/v2/idp/types

Source: https://context7.com/chrispybacon-dev/dockflare/llms.txt

Returns supported Cloudflare Access identity provider types.

```APIDOC
## GET /api/v2/idp/types

### Description
Returns supported Cloudflare Access identity provider types.

### Method
GET

### Endpoint
/api/v2/idp/types

### Request Example
```bash
curl -b "session=..." https://dockflare.example.com/api/v2/idp/types
```

### Response
#### Success Response (200)
- **types** (array) - A list of supported identity provider types.

### Response Example
```json
{
  "types": ["oidc", "saml", "google", "github", "azureAD", ...]
}
```
```