docs

dockflare/app/templates/docs/Access-Policy-Best-Practices.md

@@ -0,0 +1,106 @@
+# Access Policy Best Practices & Examples
+
+DockFlare's most powerful security feature is **Access Groups**. They provide a centralized, reusable, and maintainable way to secure your services using Cloudflare Zero Trust.
+
+## The "Golden Rule": Use Access Groups
+
+The single most important best practice is to **use Access Groups for all your common access policies**.
+
+Access Groups are policy templates you create in the DockFlare Web UI. Instead of defining complex rules with multiple labels on every container, you create a policy once and apply it with a single, clean label.
+
+---
+
+## How to Create and Use Access Groups
+
+Creating an Access Group is a simple process done entirely within the DockFlare UI.
+
+### Step 1: Create the Access Group
+
+1.  Navigate to the **Access Policies** page from the main navigation bar in the DockFlare UI.
+2.  Click the **"Add Access Group"** button.
+3.  Give your group a **unique and descriptive ID**. This ID is what you will use in your Docker labels. For example: `admin-users`, `home-network`, `geo-block`.
+4.  Define your policy rules. You can add multiple rules to a single group.
+5.  Set the **Action** for the policy (e.g., `Allow`, `Block`).
+6.  Save the group.
+
+### Step 2: Apply the Access Group
+
+Once created, you have two ways to apply your Access Group to a service:
+
+#### A) With a Docker Label (The Recommended Way)
+
+For any new or existing container, simply add the `dockflare.access.group` label with the ID of the group you created.
+
+```yaml
+services:
+  grafana:
+    image: grafana/grafana
+    labels:
+      - "dockflare.enable=true"
+      - "dockflare.hostname=monitoring.example.com"
+      - "dockflare.service=http://grafana:3000"
+      # Apply the entire policy with one simple label:
+      - "dockflare.access.group=admin-users"
+```
+You can also apply multiple groups by using `dockflare.access.groups` with a comma-separated list of IDs:
+`dockflare.access.groups=admin-users,home-network`
+
+#### B) Via the Web UI (For Manual Rules or Overrides)
+
+You can also apply an Access Group to any rule directly from the dashboard:
+1.  Find the ingress rule you want to modify on the main dashboard.
+2.  Click the **"Manage Rule"** button.
+3.  In the editing modal, select your desired Access Group(s) from the "Access Groups" dropdown menu.
+4.  Save the changes.
+
+This is perfect for applying policies to manually created rules (for non-Docker services) or for temporarily overriding a policy defined by Docker labels.
+
+---
+
+## Policy Examples
+
+Here are some common policy configurations you can create within an Access Group.
+
+### Example 1: Authenticate by Email
+
+This is the most common use case: allowing only specific users who can authenticate with your configured Identity Provider (e.g., Google, GitHub, or a one-time PIN sent to their email).
+
+*   **Group ID:** `admin-users`
+*   **Rule 1:**
+    *   **Type:** `Email`
+    *   **Value:** `user1@example.com`
+*   **Rule 2:**
+    *   **Type:** `Email`
+    *   **Value:** `user2@example.com`
+*   **Action:** `Allow`
+
+This policy will require any user trying to access the service to log in, and only `user1@example.com` and `user2@example.com` will be granted access.
+
+### Example 2: Allow Your Home IP Address
+
+This policy restricts access to your home network, allowing you to access services without needing to log in when you are at home.
+
+1.  **Find Your Public IP:** In your browser, search for "what is my ip". Your public IP address will be displayed (e.g., `203.0.113.55`).
+2.  **Create the Access Group:**
+    *   **Group ID:** `home-network`
+    *   **Rule 1:**
+        *   **Type:** `IP`
+        *   **Value:** `203.0.113.55/32` (The `/32` CIDR notation means this rule applies only to this single IP address).
+    *   **Action:** `Allow`
+
+This policy will grant access to anyone coming from your specific home IP address.
+
+### Example 3: Geo-Fencing (Blocking Multiple Countries)
+
+This policy can be used to block traffic from a list of specific countries, while allowing traffic from everywhere else.
+
+*   **Group ID:** `geo-block`
+*   **Rule 1: Block List**
+    *   **Type:** `Country`
+    *   **Value:** `RU, CN, KP` (Enter multiple country codes, separated by commas).
+    *   **Action:** `Block`
+*   **Rule 2: Allow Everyone Else**
+    *   **Type:** `Everyone`
+    *   **Action:** `Allow`
+
+This policy will explicitly block users from Russia, China, and North Korea, while allowing users from all other countries to access the service. You can then combine this with an authentication policy by applying multiple groups (e.g., `dockflare.access.groups=geo-block,admin-users`).

dockflare/app/templates/docs/Accessing-the-Web-UI.md

@@ -0,0 +1,27 @@
+# Accessing the Web UI
+
+Once you have successfully started the DockFlare container, you can access the web UI to manage your settings, view the status of your tunnels, and manually configure ingress rules.
+
+## Default URL
+
+By default, the DockFlare web UI is accessible on port `5000`. To access it, open your web browser and navigate to the following URL:
+
+```
+http://<your-server-ip>:5000
+```
+
+Replace `<your-server-ip>` with the IP address of the server where DockFlare is running.
+
+## First-Time Setup
+
+The first time you access the web UI, you will be guided by the **Pre-Flight Setup Wizard**. This wizard will help you with the initial configuration of DockFlare, including setting up a password for the web UI.
+
+## Logging In
+
+After the initial setup, you will be presented with a login screen every time you access the web UI. Use the password you created during the setup process to log in.
+
+## Disabling Password Login
+
+For advanced use cases, such as placing the DockFlare dashboard behind another authentication proxy (like Cloudflare Access), you can disable the built-in password login. This option is available in the **Settings** page under the **Security** section.
+
+**Warning:** Disabling password login will make your DockFlare dashboard publicly accessible. Only do this if you have another authentication method in place.

dockflare/app/templates/docs/Basic-Usage-Single-Domain.md

@@ -0,0 +1,82 @@
+# Basic Usage (Single Domain)
+
+This guide demonstrates the most common use case for DockFlare: exposing a single Docker container to the internet on a public hostname.
+
+## Prerequisites
+
+Before you start, make sure you have:
+1.  Completed the [Quick Start](Quick-Start-Docker-Compose.md) guide.
+2.  DockFlare is running and connected to your Cloudflare account.
+3.  You have a service you want to expose (we will use `nginx` in this example).
+
+## Example: Exposing an NGINX Container
+
+Let's say you want to expose a standard NGINX web server at the hostname `nginx.example.com`.
+
+### 1. Add the Service to your `docker-compose.yml`
+
+Modify your `docker-compose.yml` file to include the `nginx` service. The key is to add the `dockflare.*` labels to its configuration.
+
+```yaml
+version: '3.8'
+
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    container_name: dockflare
+    restart: unless-stopped
+    ports:
+      - "5000:5000"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./dockflare_data:/app/data
+    networks:
+      - cloudflare-net
+
+  # Add your new service here
+  nginx-webserver:
+    image: nginx:latest
+    container_name: my-nginx
+    restart: unless-stopped
+    networks:
+      - cloudflare-net # Must be on the same network as DockFlare
+    labels:
+      # --- DockFlare Configuration ---
+      - "dockflare.enable=true"
+      - "dockflare.hostname=nginx.example.com"
+      - "dockflare.service=http://nginx-webserver:80"
+
+volumes:
+  dockflare_data:
+
+networks:
+  cloudflare-net:
+    name: cloudflare-net
+    external: true
+```
+
+### 2. Understanding the Labels
+
+*   `dockflare.enable=true`: This tells DockFlare to manage this container.
+*   `dockflare.hostname=nginx.example.com`: This is the public URL where your service will be available. DockFlare will create a DNS record for this hostname in your Cloudflare account.
+*   `dockflare.service=http://nginx-webserver:80`: This tells Cloudflare Tunnel where to send the traffic. It's the internal address of the NGINX container. Note that we are using the service name (`nginx-webserver`) as the hostname, which is possible because both containers are on the same Docker network.
+
+### 3. Deploy the Service
+
+Save your `docker-compose.yml` file and run the following command to start the new service:
+
+```bash
+docker compose up -d
+```
+
+### 4. Verification
+
+DockFlare will detect the new container and automatically perform the following actions:
+1.  Add an ingress rule to your Cloudflare Tunnel for `nginx.example.com`.
+2.  Create a CNAME record for `nginx.example.com` in your Cloudflare DNS, pointing to the tunnel.
+
+You can verify this in a few ways:
+*   **DockFlare Web UI**: The `nginx.example.com` service will appear on the dashboard.
+*   **Cloudflare Dashboard**: You will see the new CNAME record in your DNS settings and the new ingress rule in your tunnel configuration.
+
+After a few moments for DNS to propagate, you should be able to navigate to `https://nginx.example.com` in your browser and see the default NGINX welcome page.

dockflare/app/templates/docs/Common-Issues.md

@@ -0,0 +1,61 @@
+# Common Issues
+
+This page lists some of the common issues that users may encounter and how to resolve them.
+
+---
+
+### Issue: The DockFlare container fails to start or is in a restart loop.
+
+**Solution:**
+1.  **Check the Docker logs:** The first step is always to check the logs of the DockFlare container. Run the following command:
+    ```bash
+    docker logs dockflare
+    ```
+2.  **Look for Errors:** Look for any error messages. Common causes include:
+    *   An invalid `docker-compose.yml` file (e.g., incorrect syntax, volume mounting issues).
+    *   Problems with the Docker daemon itself.
+    *   Permission issues with the Docker socket (`/var/run/docker.sock`).
+
+---
+
+### Issue: DNS records are not being created in Cloudflare.
+
+**Solution:**
+1.  **Check the DockFlare Logs:** Look for any error messages related to the Cloudflare API. The logs will often tell you exactly why the API call failed.
+2.  **Verify API Token Permissions:** This is the most common cause. Ensure that your Cloudflare API Token has the required permissions. At a minimum, you need:
+    *   `Zone:DNS:Edit` for every zone you want DockFlare to manage.
+    *   `Zone:Zone:Read`
+3.  **Verify Zone Configuration:**
+    *   Ensure that the **Zone ID** you provided during setup is correct.
+    *   If you are using the `dockflare.zonename` label, double-check that the zone name is spelled correctly.
+
+---
+
+### Issue: An Access Policy (Zero Trust) is not being applied to a service.
+
+**Solution:**
+1.  **Check API Token Permissions:** Ensure your API token has the `Account:Access: Apps and Policies:Edit` permission.
+2.  **Check for UI Overrides:** In the DockFlare dashboard, check if the rule has a "UI Override" status. UI overrides take precedence over labels.
+3.  **Check Access Group ID:** If you are using `dockflare.access.group`, make sure the ID you specified in the label **exactly** matches the ID you created for the Access Group on the "Access Policies" page.
+4.  **Check the Cloudflare Dashboard:** Log in to your Cloudflare Zero Trust dashboard. Navigate to **Access -> Applications** to see if the Access Application was created. Sometimes, Cloudflare will show an error there that is not visible in the API response.
+
+---
+
+### Issue: I get an `ERR_TOO_MANY_REDIRECTS` error when trying to access my service.
+
+**Solution:**
+This error almost always happens due to a misconfiguration of SSL/TLS settings between your origin service and Cloudflare.
+
+1.  **Check Cloudflare SSL/TLS Mode:** In your Cloudflare dashboard, go to the SSL/TLS settings for your domain. Ensure your encryption mode is set to **Full (Strict)**.
+2.  **Avoid Double Redirects:** The "Flexible" SSL mode in Cloudflare can cause this issue if your backend application is also trying to redirect from HTTP to HTTPS. The browser gets stuck in a loop.
+3.  **Use `https` in your service URL:** If your backend service supports HTTPS, use `https://` in your `dockflare.service` label (e.g., `dockflare.service=https://my-app:443`). This ensures the connection from `cloudflared` to your service is also encrypted.
+
+---
+
+### Issue: The managed `cloudflared-agent` container fails to start with a "stale network" error.
+
+**Solution:**
+This can happen if the Docker network the agent was using was removed and recreated. DockFlare is designed to handle this automatically.
+
+1.  **Restart DockFlare:** A simple restart of the DockFlare container (`docker compose restart dockflare`) should resolve this.
+2.  **How it Works:** On startup, DockFlare checks the health of its managed agent. If it detects this specific issue, it will automatically remove the broken agent container and create a new one with the correct configuration. This was a specific bug fixed in version `v1.9.5`. Ensure you are on a recent version of DockFlare.

dockflare/app/templates/docs/Container-Labels.md

@@ -0,0 +1,73 @@
+# Container Labels Reference
+
+DockFlare is configured primarily through Docker labels attached to your containers. This page provides a comprehensive reference for all supported labels.
+
+## Basic Configuration
+
+These labels control the fundamental routing and service definition for a container.
+
+| Label | Description | Example |
+| :--- | :--- | :--- |
+| `dockflare.enable` | **Required.** The master switch. Must be set to `true` for DockFlare to manage the container. | `dockflare.enable=true` |
+| `dockflare.hostname` | **Required.** The public-facing hostname for your service. | `dockflare.hostname=myservice.example.com` |
+| `dockflare.service` | **Required.** The internal URL of the service that Cloudflare Tunnel should connect to. Can be `http`, `https`, `tcp`, `ssh`, `rdp`, `http_status:XXX`, or `bastion`. | `dockflare.service=http://my-app-container:8080` |
+| `dockflare.path` | The URL path to route to this service. Useful for exposing multiple services on the same hostname. | `dockflare.path=/api` |
+| `dockflare.zonename` | The name of the Cloudflare Zone (domain) where the DNS record should be created. Overrides the global configuration. | `dockflare.zonename=another-domain.com` |
+| `dockflare.no_tls_verify` | If set to `true`, disables TLS certificate verification for the connection between `cloudflared` and your origin service. Useful for origins with self-signed certificates. | `dockflare.no_tls_verify=true` |
+| `dockflare.originsrvname` | Sets a specific Server Name Indication (SNI) hostname for the TLS connection to the origin. This is also known as "Origin Server Name" in the Cloudflare dashboard. | `dockflare.originsrvname=internal.service.local` |
+| `dockflare.httpHostHeader` | Overrides the `Host` header sent from `cloudflared` to your origin service. | `dockflare.httpHostHeader=custom-host.internal` |
+
+---
+
+## Access Policy Configuration
+
+These labels allow you to dynamically create and manage Cloudflare Access applications to secure your services.
+
+**Note:** It is highly recommended to use **Access Groups** (`dockflare.access.group`) for managing policies. Using individual labels is best for one-off, unique configurations. If `dockflare.access.group` or `dockflare.access.groups` is used, all other `dockflare.access.*` labels are ignored.
+
+| Label | Description | Example |
+| :--- | :--- | :--- |
+| `dockflare.access.group` | The ID of a single, pre-configured Access Group to apply to this service. The ID can be found on the "Access Policies" page in the DockFlare UI. | `dockflare.access.group=internal-tools-policy` |
+| `dockflare.access.groups` | A comma-separated list of Access Group IDs to apply. This allows you to layer multiple policies onto a single service. | `dockflare.access.groups=allow-team-a,allow-admins` |
+| `dockflare.access.policy` | The primary policy type. Can be `bypass` (public), `authenticate` (requires login), or `default_tld` (inherits from a `*.domain.com` policy). If unset, the service will be public. | `dockflare.access.policy=authenticate` |
+| `dockflare.access.name` | A custom name for the Cloudflare Access Application. Defaults to `DockFlare-{hostname}`. | `dockflare.access.name=My Web App Access` |
+| `dockflare.access.session_duration` | The session duration for authenticated users (e.g., `24h`, `30m`). Defaults to `24h`. | `dockflare.access.session_duration=1h` |
+| `dockflare.access.app_launcher_visible` | If `true`, makes the application visible in the Cloudflare Access App Launcher. | `dockflare.access.app_launcher_visible=true` |
+| `dockflare.access.allowed_idps` | A comma-separated list of allowed Identity Provider (IdP) UUIDs. You can find these in your Cloudflare Zero Trust dashboard. | `dockflare.access.allowed_idps=uuid1,uuid2` |
+| `dockflare.access.auto_redirect_to_identity` | If `true`, users will be immediately redirected to the IdP login page instead of the Cloudflare Access splash page. | `dockflare.access.auto_redirect_to_identity=true` |
+| `dockflare.access.custom_rules` | A JSON string representing an array of Cloudflare Access Policy rules. This provides maximum flexibility for complex, one-off policies. | `dockflare.access.custom_rules='[{"email":{"email":"user@example.com"},"action":"allow"}]'` |
+
+---
+
+## Indexed Labels for Multiple Domains
+
+DockFlare supports defining multiple hostnames for a single container using indexed labels. This is useful for exposing different ports or paths of the same service on different public hostnames.
+
+To use indexed labels, prefix the label with an integer, starting from `0`.
+
+*   An indexed hostname (`<index>.hostname`) is always required.
+*   Other labels at the same index (e.g., `<index>.service`, `<index>.path`) will override the base (non-indexed) labels for that specific hostname.
+*   If an indexed label is not provided, it will fall back to the value of the corresponding base label.
+
+### Example
+
+This example exposes two hostnames from a single container:
+1.  `app.example.com` routes to the main web interface on port `80`.
+2.  `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"
+```

dockflare/app/templates/docs/Content-Security-Policy-(CSP).md

@@ -0,0 +1,23 @@
+# Content Security Policy (CSP)
+
+## What is a Content Security Policy?
+
+A Content Security Policy (CSP) is a web security standard that helps prevent certain types of attacks, most notably Cross-Site Scripting (XSS) and data injection attacks. It works by telling the browser which sources of content (scripts, styles, images, etc.) are trusted and allowed to be loaded on a web page.
+
+## DockFlare's CSP
+
+The DockFlare application itself has a web interface. To protect this interface and ensure its security, DockFlare implements a strict Content Security Policy on its own UI.
+
+This is an important internal security feature designed to protect you, the administrator, from potential browser-based vulnerabilities when you are using the DockFlare dashboard.
+
+## Scope of the CSP
+
+It is important to understand that DockFlare's CSP applies **only to the DockFlare Web UI itself**.
+
+It does **not** affect, modify, or add any CSP headers to the traffic that is being proxied through your Cloudflare Tunnel to your own applications. If you want to implement a CSP on your own applications, you must configure that within the applications themselves (e.g., by setting the `Content-Security-Policy` HTTP header in your web server or application code).
+
+## Configuration
+
+DockFlare's CSP is an integral part of its security posture and is **not user-configurable**. The policy is carefully crafted to be as restrictive as possible while still allowing the UI to function correctly.
+
+If you are interested in learning more about how Content Security Policies work in general, the [MDN Web Docs on CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) is an excellent resource.

dockflare/app/templates/docs/Contributing.md

@@ -0,0 +1,26 @@
+# Contributing to DockFlare
+
+First off, thank you for considering contributing to DockFlare! Community contributions are incredibly valuable. This document provides some guidelines for contributing.
+
+## How You Can Help
+
+*   **Reporting Bugs:** Open an **Issue** on GitHub with detailed steps to reproduce the bug.
+*   **Suggesting Enhancements & Ideas:** Start a **Discussion** on the GitHub repository's "Discussions" tab.
+*   **Improving Documentation:** Your feedback or pull requests to improve the documentation are welcome.
+*   **Submitting Pull Requests:** If you'd like to contribute code, please follow the guidelines below.
+
+## Guidelines for Pull Requests
+
+1.  **Discuss First:** For significant changes, please open an Issue or start a Discussion first to align on the approach.
+2.  **Branching:** Create a new branch for your feature or bug fix (`feature/your-feature` or `fix/your-bug`).
+3.  **Code Style:** Follow PEP 8 for Python. Use clear variable and function names.
+4.  **Testing:** Test your changes thoroughly and describe the testing process in your pull request.
+5.  **Documentation:** Update the `README.md` or this documentation if your changes affect user-facing functionality.
+6.  **Submit the PR:** Open a Pull Request against the `unstable` branch of the main DockFlare repository. Provide a clear description of your changes.
+
+## Community & Support
+
+*   For **bug reports**, please use the [GitHub Issues](https://github.com/ChrispyBacon-dev/DockFlare/issues) tracker.
+*   For **feature requests, questions, ideas, or general discussion**, please use the [GitHub Discussions](https://github.com/ChrispyBacon-dev/DockFlare/discussions) board.
+
+This is a summary of the full `CONTRIBUTING.md`. For more details, please see the [original file](https://github.com/ChrispyBacon-dev/DockFlare/blob/main/CONTRIBUTING.md) in the repository.

dockflare/app/templates/docs/Debugging-&-Logs.md

@@ -0,0 +1,59 @@
+# Debugging & Logs
+
+When troubleshooting issues with DockFlare, your primary tools are the logs generated by the DockFlare container and its managed `cloudflared` agent.
+
+## 1. Checking the DockFlare Container Logs
+
+The most important source of information is the log output from the DockFlare container itself. These logs provide a detailed, real-time view of what DockFlare is doing.
+
+### What You'll Find in the Logs:
+*   Detection of Docker container start/stop events.
+*   Processing of `dockflare.*` labels.
+*   Calls being made to the Cloudflare API.
+*   Success messages or detailed error responses from the Cloudflare API.
+*   The status of background tasks like resource cleanup.
+
+### How to View the Logs:
+To view the logs, use the following Docker command in your terminal:
+```bash
+# View the full log history
+docker logs dockflare
+
+# Follow the logs in real-time
+docker logs -f dockflare
+```
+
+## 2. Using the Web UI Real-time Logs
+
+For convenience, the DockFlare dashboard includes a **real-time log viewer** at the bottom of the main page.
+
+This viewer streams the exact same logs that you would see with `docker logs -f dockflare`, but provides an easy way to see what's happening right now without leaving your browser. This is particularly useful for watching the actions DockFlare takes immediately after you start or stop a container.
+
+## 3. Checking the `cloudflared` Agent Logs
+
+If you suspect the issue is with the connection between your server and the Cloudflare network, you can check the logs of the `cloudflared` agent container directly.
+
+### How to View Agent Logs:
+First, you need to find the name of the agent container. By default, it is named `cloudflared-agent-<tunnel-name>`, where `<tunnel-name>` is the name of the tunnel configured in your DockFlare settings.
+
+You can find the exact name with `docker ps`.
+
+Once you have the name, run:
+```bash
+# Replace with the actual container name
+docker logs cloudflared-agent-dockflare-tunnel
+```
+
+These logs are useful for diagnosing:
+*   Connection errors to the Cloudflare edge.
+*   Authentication issues with your tunnel token.
+*   Protocol-level errors for the traffic being proxied.
+
+**Note:** This only applies if you are using the default **Internal Mode**. If you are using [External Mode](External-cloudflared-Mode.md), you will need to check the logs of your own `cloudflared` agent process.
+
+## 4. Checking the Cloudflare Dashboard
+
+Finally, don't forget to use the Cloudflare dashboard as a debugging tool.
+*   **DNS Page:** Check if the CNAME records were created as you expected.
+*   **Zero Trust Dashboard:** Go to **Access -> Tunnels** to check the status of your tunnel and its ingress rules.
+*   **Zero Trust Dashboard:** Go to **Access -> Applications** to check the configuration and health of your Zero Trust policies. The "Last Seen" status on policies can be very informative.

dockflare/app/templates/docs/External-cloudflared-Mode.md

@@ -0,0 +1,10 @@
+# External `cloudflared` Mode
+
+DockFlare provides an advanced "External `cloudflared` Mode" for users who want to manage the `cloudflared` agent themselves.
+
+This topic is covered in detail on the **[Internal vs. External `cloudflared`](Internal-vs-External-cloudflared.md)** page.
+
+Please refer to that page for a complete explanation of:
+*   The difference between Internal and External modes.
+*   The pros and cons of each approach.
+*   How to configure DockFlare to use an external `cloudflared` agent.

dockflare/app/templates/docs/Health-Checks.md

@@ -0,0 +1,47 @@
+# Health Checks
+
+DockFlare includes a dedicated health check endpoint that can be used with Docker's built-in health check mechanism. This allows Docker to monitor the health of the DockFlare application and automatically restart it if it becomes unresponsive.
+
+## The `/ping` Endpoint
+
+DockFlare exposes a simple HTTP endpoint at `/ping`.
+
+*   **Purpose:** To provide a simple way for automated systems to check if the DockFlare web server is running and responsive.
+*   **Authentication:** This endpoint is **exempt from authentication**. You do not need to be logged in to access it, which is what allows Docker's internal health check mechanism to use it.
+*   **Healthy Response:** A healthy, running DockFlare application will respond to a request at `/ping` with an **HTTP 200 OK** status code.
+*   **Version Information:** The body of the response from the `/ping` endpoint also contains the running version of the DockFlare application.
+
+## How to Configure a Health Check in Docker Compose
+
+You can add a `healthcheck` section to the `dockflare` service in your `docker-compose.yml` file to have Docker automatically monitor the application's health.
+
+```yaml
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    container_name: dockflare
+    restart: unless-stopped
+    # ... other settings
+    healthcheck:
+      # The command to run to check health.
+      # curl is used to make an HTTP request to the ping endpoint.
+      test: ["CMD", "curl", "-f", "http://localhost:5000/ping"]
+      # How often to run the check
+      interval: 1m30s
+      # How long to wait for a response
+      timeout: 10s
+      # How many consecutive failures before marking as unhealthy
+      retries: 3
+      # How long to wait after the container starts before running the first check
+      start_period: 40s
+```
+
+### Breakdown of the `healthcheck` configuration:
+
+*   `test`: This is the command that Docker runs inside the container. `curl -f` will make an HTTP request to the `/ping` endpoint and will exit with a non-zero status code if the response is not HTTP 200 OK.
+*   `interval`: Docker will run this check every 90 seconds.
+*   `timeout`: Docker will wait up to 10 seconds for the command to complete.
+*   `retries`: If the check fails 3 times in a row, Docker will mark the container as `unhealthy`.
+*   `start_period`: Docker will wait 40 seconds after the container has started before performing the first health check. This gives the application time to initialize properly.
+
+With this configuration in place, you can check the health of your container by running `docker ps`. The status column will show `(healthy)` if the health check is passing. If the container becomes unhealthy, Docker will automatically restart it based on the `restart` policy (e.g., `unless-stopped`).

dockflare/app/templates/docs/Home.md

@@ -0,0 +1,39 @@
+# Welcome to the DockFlare Documentation!
+
+DockFlare is a powerful, self-hosted ingress controller that simplifies Cloudflare Tunnel and Zero Trust management. It uses Docker labels for automated configuration while providing a robust web UI for manual service definitions and policy overrides.
+
+This documentation provides comprehensive information for DockFlare. Whether you're a new user or an experienced one, you'll find everything you need to know to get the most out of DockFlare.
+
+## Table of Contents
+
+*   **[Home](Home.md)**
+*   **Getting Started**
+    *   [Prerequisites](Prerequisites.md)
+    *   [Quick Start (Docker Compose)](Quick-Start-Docker-Compose.md)
+    *   [Accessing the Web UI](Accessing-the-Web-UI.md)
+*   **Core Concepts**
+    *   [How DockFlare Works](How-DockFlare-Works.md)
+    *   [Access Policy Best Practices](Access-Policy-Best-Practices.md)
+    *   [Internal vs External `cloudflared`](Internal-vs-External-cloudflared.md)
+    *   [State-Persistence](State-Persistence.md)
+*   **Configuration**
+    *   [Container Labels](Container-Labels.md)
+*   **Usage Guide**
+    *   [Basic Usage (Single Domain)](Basic-Usage-Single-Domain.md)
+    *   [Using Multiple Domains (Indexed Labels)](Using-Multiple-Domains-Indexed-Labels.md)
+    *   [Using Wildcard Domains](Using-Wildcard-Domains.md)
+    *   [Managing DNS Zones](Managing-DNS-Zones.md)
+    *   [Understanding Graceful Deletion](Understanding-Graceful-Deletion.md)
+    *   [Using the Web UI](Using-the-Web-UI.md)
+*   **Advanced Topics**
+    *   [External `cloudflared` Mode](External-cloudflared-Mode.md)
+    *   [Switching Between Modes](Switching-Between-Modes.md)
+    *   [Monitoring with Prometheus & Grafana](Monitoring-with-Prometheus-&-Grafana.md)
+    *   [Performance Tuning](Performance-Tuning.md)
+    *   [Content Security Policy (CSP)](Content-Security-Policy.md)
+*   **Troubleshooting**
+    *   [Common Issues](Common-Issues.md)
+    *   [Debugging & Logs](Debugging-Logs.md)
+    *   [Health Checks](Health-Checks.md)
+*   **[Contributing](Contributing.md)**
+*   **[License](License.md)**

dockflare/app/templates/docs/How-DockFlare-Works.md

@@ -0,0 +1,33 @@
+# How DockFlare Works
+
+DockFlare acts as a bridge between your Docker environment and the Cloudflare network, automating the process of exposing services securely to the internet. It continuously monitors your Docker host and uses the Cloudflare API to manage Tunnels, DNS records, and Access Policies on your behalf.
+
+## Core Workflow
+
+The core workflow can be broken down into a few key steps:
+
+1.  **Docker Event Monitoring**: DockFlare listens for Docker socket events, such as `start` and `stop` for containers.
+
+2.  **Label Detection**: When a new container is started, DockFlare inspects it for `dockflare.` labels. If a container has `dockflare.enable=true`, DockFlare knows it needs to manage it.
+
+3.  **Cloudflare API Interaction**: Based on the labels, DockFlare communicates with the Cloudflare API to configure the necessary resources:
+    *   **Cloudflare Tunnel**: It adds an ingress rule to your designated Cloudflare Tunnel. This rule points the public hostname to the container's internal network address (e.g., `http://my-app:8080`).
+    *   **DNS Management**: It creates a CNAME DNS record in your Cloudflare DNS zone, pointing your desired public hostname (e.g., `my-app.example.com`) to your Cloudflare Tunnel.
+    *   **Access Policies**: If you've specified access control labels, DockFlare creates or updates a Cloudflare Access Application to secure your service with Zero Trust policies (e.g., requiring a login from your identity provider).
+
+4.  **Automatic Cleanup**: When a managed container is stopped or removed, DockFlare automatically triggers a cleanup process. It removes the corresponding ingress rule from the Cloudflare Tunnel and, if no other service is using the hostname, deletes the DNS record and the Access Application. This prevents stale records and keeps your Cloudflare configuration clean.
+
+## Layered Configuration Model
+
+DockFlare uses a flexible, layered approach to configuration, giving you both automation and fine-grained control:
+
+1.  **Docker Labels (Base Layer)**: This is the primary, automated method. You define a service's entire configuration—hostname, internal service URL, and access policy—directly in your `docker-compose.yml` or Docker run command. This is the "source of truth" for automated services.
+
+2.  **Access Groups (Abstraction Layer)**: To avoid repeating complex access policies across many services, you can create reusable **Access Groups** in the Web UI. These are templates that bundle a set of access rules (e.g., "allow company emails" or "allow access from specific countries"). You can then apply a whole policy to a container with a single label (`dockflare.access.group=my-policy-group`), simplifying your container labels significantly.
+
+3.  **Web UI Overrides (Control Layer)**: The Web UI provides the ultimate level of control. From the dashboard, you can:
+    *   **Override** the access policy of any service, whether it was defined by labels or an Access Group. These overrides are persistent and will not be undone by a container restart.
+    *   **Create Manual Ingress Rules** for services that are not running in Docker (e.g., a service on another machine in your network).
+    *   **Revert** a service's configuration back to what is defined in its Docker labels, discarding any UI overrides.
+
+This layered model allows you to "set it and forget it" with Docker labels for most services, while still having the power to handle exceptions and complex scenarios through the Web UI.

dockflare/app/templates/docs/Internal-vs-External-cloudflared.md

@@ -0,0 +1,55 @@
+# Internal vs. External `cloudflared`
+
+DockFlare can operate in two modes for managing the `cloudflared` agent, which is the piece of software that actually creates the persistent connection between your server and the Cloudflare network. Understanding these two modes is key to choosing the right setup for your environment.
+
+## Internal Mode (Default)
+
+In Internal Mode, DockFlare takes full responsibility for managing the `cloudflared` agent.
+
+### How it Works
+When DockFlare starts, it will automatically:
+1.  Create a dedicated Docker container running the `cloudflare/cloudflared` image.
+2.  Configure this agent container to connect to your Cloudflare account and use the tunnel specified in your DockFlare settings.
+3.  Ensure the agent is running and restart it if it fails.
+4.  Automatically apply any relevant settings, such as enabling the Prometheus metrics endpoint.
+
+This is the **default and recommended** mode for most users.
+
+### Pros
+*   **Simplicity:** It's a "zero-configuration" setup. DockFlare handles everything for you.
+*   **Guaranteed Compatibility:** DockFlare ensures that the agent is configured in a way it can work with.
+*   **Centralized Management:** Everything related to your tunnels is managed by DockFlare.
+
+### Cons
+*   **Less Control:** You have limited control over the `cloudflared` agent's configuration beyond what DockFlare exposes.
+
+---
+
+## External `cloudflared` Mode
+
+In External Mode, you are responsible for running and managing the `cloudflared` agent yourself. DockFlare will connect to this existing agent instead of creating its own.
+
+### How it Works
+DockFlare will **not** create a `cloudflared` container. Instead, it will assume that you have a `cloudflared` agent running somewhere that it can use. This could be:
+*   A `cloudflared` process running directly on the host OS (e.g., as a `systemd` service).
+*   A `cloudflared` container that you manage yourself with a separate `docker-compose.yml` file or Docker run command.
+*   A `cloudflared` agent running on a different machine entirely.
+
+This is an **advanced mode** intended for users with specific needs or complex existing setups.
+
+### Pros
+*   **Maximum Control:** You have full control over the `cloudflared` agent, including its version, command-line arguments, and lifecycle.
+*   **Integration with Existing Setups:** Perfect if you already have a `cloudflared` agent running for other purposes.
+*   **Decoupling:** Decouples the lifecycle of DockFlare from the lifecycle of the `cloudflared` agent.
+
+### Cons
+*   **Complexity:** You are responsible for ensuring the `cloudflared` agent is running, configured correctly, and connected to the correct tunnel.
+*   **Configuration Overhead:** You need to configure DockFlare to use this external agent.
+
+### How to Enable External Mode
+To enable External Mode, you must set the following environment variables for the DockFlare container:
+
+*   `USE_EXTERNAL_CLOUDFLARED=true`: This enables the external mode.
+*   `EXTERNAL_TUNNEL_ID`: This must be set to the UUID of the tunnel that your external `cloudflared` agent is configured to use.
+
+When these variables are set, DockFlare will skip its internal agent management and will instead send all ingress rule configurations to the tunnel specified by `EXTERNAL_TUNNEL_ID`.

dockflare/app/templates/docs/License.md

@@ -0,0 +1,26 @@
+# License
+
+DockFlare is open-source software licensed under the **GNU General Public License v3.0**.
+
+The full text of the license is available in the repository.
+
+## Key Permissions
+
+*   **Commercial use:** You are allowed to use this software for commercial purposes.
+*   **Modification:** You are allowed to modify the software.
+*   **Distribution:** You are allowed to distribute the software.
+*   **Private use:** You are allowed to use the software for private purposes.
+
+## Key Conditions
+
+*   **Disclose source:** If you distribute the software, you must make the source code available.
+*   **License and copyright notice:** You must include the original license and copyright notice with the software.
+*   **State changes:** If you modify the software, you must state that you have made changes.
+*   **Same license:** You must release any modifications under the same license (GPL-3.0).
+
+## Key Limitations
+
+*   **Liability:** The software is provided "as is," without any warranty. The authors are not liable for any damages.
+*   **Trademark use:** The license does not grant you any rights to use the trademarks of the project.
+
+For the complete terms and conditions, please refer to the [LICENSE.MD file](https://github.com/ChrispyBacon-dev/DockFlare/blob/main/LICENSE.MD) in the DockFlare repository.

dockflare/app/templates/docs/Managing-DNS-Zones.md

@@ -0,0 +1,71 @@
+# Managing DNS Zones
+
+DockFlare is capable of managing DNS records across multiple domains (Cloudflare Zones) within the same Cloudflare account. This allows you to run services on `service-a.domain-one.com` and `service-b.another-domain.org` from the same DockFlare instance.
+
+## Default Zone
+
+During the initial setup of DockFlare, you provide a **Zone ID**. This is the **default zone** where DockFlare will create all DNS records. If you only plan to use a single domain, this is all you need to worry about.
+
+## Overriding the Zone with a Label
+
+To manage a service on a domain other than the default one, you can use the `dockflare.zonename` label.
+
+This label tells DockFlare to create the DNS record for that specific service in the specified Cloudflare Zone.
+
+### Prerequisites
+
+For this to work, you must ensure that the **Cloudflare API Token** you are using has `Zone:DNS:Edit` permissions for **all the zones** you intend to manage.
+
+### Example
+
+Let's say your default zone is `example.com`, but you also want to run a service on `media.io`.
+
+```yaml
+services:
+  # This service will be created in the default zone (example.com)
+  service-one:
+    image: nginx
+    labels:
+      - "dockflare.enable=true"
+      - "dockflare.hostname=nginx.example.com"
+      - "dockflare.service=http://service-one:80"
+
+  # This service will be created in the 'media.io' zone
+  service-two:
+    image: portainer/portainer-ce
+    labels:
+      - "dockflare.enable=true"
+      - "dockflare.hostname=portainer.media.io"
+      - "dockflare.service=http://service-two:9000"
+      # Override the default zone for this service
+      - "dockflare.zonename=media.io"
+```
+
+When you deploy this, DockFlare will:
+1.  Create a CNAME record for `nginx.example.com` in the `example.com` zone.
+2.  Create a CNAME record for `portainer.media.io` in the `media.io` zone.
+
+Both hostnames will be added as ingress rules to the same Cloudflare Tunnel.
+
+## Viewing DNS Records in the UI
+
+The DockFlare Web UI has a feature on the **Settings** page that allows you to view all Cloudflare Tunnels on your account and the DNS records pointing to them.
+
+To ensure that the UI can find DNS records across all your different zones, you can use the `TUNNEL_DNS_SCAN_ZONE_NAMES` environment variable.
+
+### `TUNNEL_DNS_SCAN_ZONE_NAMES`
+
+This environment variable accepts a comma-separated list of zone names that the UI should scan when looking for DNS records.
+
+**Example `docker-compose.yml`:**
+```yaml
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    # ... other settings
+    environment:
+      # Tell the UI to scan these zones in addition to the default one
+      - TUNNEL_DNS_SCAN_ZONE_NAMES=media.io,another-domain.org
+```
+
+This will ensure that the DNS record viewer in the UI provides a complete picture of all the domains pointing to your tunnels.

dockflare/app/templates/docs/Monitoring-with-Prometheus-&-Grafana.md

@@ -0,0 +1,52 @@
+# Monitoring with Prometheus & Grafana
+
+The `cloudflared` agent that DockFlare manages can expose a wide range of performance and health metrics in the Prometheus format. By collecting and visualizing these metrics, you can gain valuable insights into your tunnel's traffic, latency, and error rates.
+
+This guide explains how to enable the metrics endpoint and provides a quick setup for a monitoring stack using Prometheus and Grafana.
+
+## Step 1: Enable the Metrics Endpoint in DockFlare
+
+The first step is to tell DockFlare to enable the Prometheus metrics endpoint on its managed `cloudflared` agent.
+
+You can do this by setting the `CLOUDFLARED_METRICS_PORT` environment variable for your DockFlare container.
+
+**Example `docker-compose.yml`:**
+```yaml
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    # ... other settings
+    environment:
+      # Enable the metrics endpoint on port 2000 inside the container
+      - CLOUDFLARED_METRICS_PORT=2000
+```
+When you restart DockFlare with this variable, it will automatically recreate its managed `cloudflared` agent with the metrics server enabled on the specified port.
+
+**Note:** This feature is only available in the default **Internal Mode**. If you are using [External Mode](External-cloudflared-Mode.md), you are responsible for enabling the metrics endpoint on your own `cloudflared` agent.
+
+## Step 2: Set Up a Monitoring Stack
+
+If you don't already have a monitoring stack, you can quickly set one up using Docker Compose. The DockFlare repository provides an example setup in the `/examples` directory.
+
+For a complete, copy-paste guide on how to set up Prometheus and Grafana to monitor DockFlare, please refer to the **[`grafana quick setup.md`](https://github.com/ChrispyBacon-dev/DockFlare/blob/main/examples/grafana%20quick%20setup.md)** file in the repository.
+
+This guide will walk you through:
+1.  Creating the necessary directory structure.
+2.  Adding Prometheus and Grafana services to your `docker-compose.yml`.
+3.  Configuring Prometheus to scrape metrics from the `cloudflared` agent.
+4.  Provisioning Grafana with the Prometheus data source automatically.
+
+## Step 3: Import the Pre-made Grafana Dashboard
+
+To make visualization easy, DockFlare provides a pre-made Grafana dashboard that is designed to work perfectly with the metrics exposed by the `cloudflared` agent.
+
+1.  The dashboard is available as **[`dashboard.json`](https://github.com/ChrispyBacon-dev/DockFlare/blob/main/examples/dashboard.json)** in the `/examples` directory of the repository.
+2.  Download this file.
+3.  Log in to your Grafana instance.
+4.  Go to the "Dashboards" section and click "Import".
+5.  Upload the `dashboard.json` file.
+6.  Select your Prometheus data source and import the dashboard.
+
+You will now have a complete overview of your Cloudflare Tunnel's performance, including request counts, error rates, connection latency, and more.
+
+![Grafana Dashboard Example](https://raw.githubusercontent.com/ChrispyBacon-dev/DockFlare/main/images/grafana_dashboard_example.png)

dockflare/app/templates/docs/Performance-Tuning.md

@@ -0,0 +1,69 @@
+# Performance Tuning
+
+For the vast majority of users, DockFlare's default settings provide a good balance of performance and resource utilization. However, in very large or highly dynamic environments, you may benefit from tuning some of the advanced performance-related parameters.
+
+These settings are configured via environment variables in your `docker-compose.yml` file.
+
+---
+
+## `CLEANUP_INTERVAL_SECONDS`
+
+This variable controls how often DockFlare's background task runs to clean up expired resources (i.e., rules from stopped containers whose grace period has elapsed).
+
+*   **Default:** `60` seconds
+*   **Description:** A shorter interval means that stale resources are removed more quickly from your Cloudflare configuration. A longer interval reduces the frequency of background checks, which can slightly lower resource usage.
+*   **When to Tune:** If you have a very dynamic environment with many short-lived containers and want their resources cleaned up almost immediately, you could lower this value (e.g., to `30`). For most users, the default is fine.
+
+**Example:**
+```yaml
+environment:
+  - CLEANUP_INTERVAL_SECONDS=30
+```
+
+---
+
+## `MAX_CONCURRENT_DNS_OPS`
+
+This variable sets the maximum number of concurrent DNS operations (create, delete) that DockFlare will perform at one time.
+
+*   **Default:** `3`
+*   **Description:** This is a direct performance tuning knob for environments with a large number of services. When DockFlare starts up or when many containers are started at once, this setting limits how many parallel requests are made to the Cloudflare API for DNS changes.
+*   **When to Tune:** If you are managing hundreds of services and notice that the initial startup or a mass deployment is slow to create all the DNS records, you can try increasing this value (e.g., to `5` or `10`). Be aware that setting this too high could lead to Cloudflare API rate limiting.
+
+**Example:**
+```yaml
+environment:
+  - MAX_CONCURRENT_DNS_OPS=5
+```
+
+---
+
+## `RECONCILIATION_BATCH_SIZE`
+
+This controls the batch size for various background reconciliation tasks.
+
+*   **Default:** `3`
+*   **Description:** Some background tasks in DockFlare process items in batches to avoid overwhelming the system or the Cloudflare API. This setting controls the size of those batches.
+*   **When to Tune:** This is a very advanced setting. For most users, the default value should not be changed. If you have an extremely large number of rules (many hundreds or thousands), you might experiment with a slightly larger batch size, but it's generally not necessary.
+
+**Example:**
+```yaml
+environment:
+  - RECONCILIATION_BATCH_SIZE=5
+```
+
+---
+
+## `SCAN_ALL_NETWORKS`
+
+This variable changes how DockFlare discovers the IP address of containers.
+
+*   **Default:** `false`
+*   **Description:** By default, DockFlare expects that the target container is on the same Docker network as DockFlare itself. When `SCAN_ALL_NETWORKS` is set to `true`, DockFlare will inspect all the networks a container is attached to in order to find a shared network.
+*   **When to Tune:** This should only be enabled if you have a complex Docker networking setup where your application containers are not on the same network as DockFlare. Be aware that enabling this can have a performance impact in environments with a very large number of Docker networks, as it requires more inspection work from DockFlare.
+
+**Example:**
+```yaml
+environment:
+  - SCAN_ALL_NETWORKS=true
+```

dockflare/app/templates/docs/Prerequisites.md

@@ -0,0 +1,16 @@
+# Prerequisites
+
+Before you begin, ensure you have the following:
+
+*   **Docker & Docker Compose:** DockFlare is a Docker-based application, so you'll need both Docker and Docker Compose installed on your system.
+*   **A Cloudflare Account:** You'll need a Cloudflare account to manage your domains and create API tokens.
+*   **Your Cloudflare Account ID:** You can find your Account ID in the Cloudflare dashboard.
+*   **The Zone ID for the domain you wish to use:** Each domain in Cloudflare has a unique Zone ID.
+*   **A Cloudflare API Token:** You'll need to create a Cloudflare API token with the following permissions:
+    *   `Account:Cloudflare Tunnel:Edit`
+    *   `Account:Account Settings:Read`
+    *   `Account:Access: Apps and Policies:Edit`
+    *   `Zone:Zone:Read`
+    *   `Zone:DNS:Edit`
+
+![Cloudflare API Permissions](images/cf.png)

dockflare/app/templates/docs/Quick-Start-Docker-Compose.md

@@ -0,0 +1,61 @@
+# Quick Start (Docker Compose)
+
+This guide will walk you through the fastest way to get DockFlare up and running using Docker Compose.
+
+### 1. Create the `docker-compose.yml` file
+
+First, create a `docker-compose.yml` file with the following content. This configuration uses the stable image of DockFlare, maps the required Docker socket, and sets up a persistent volume for your configuration.
+
+```yaml
+version: '3.8'
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    container_name: dockflare
+    restart: unless-stopped
+    ports:
+      - "5000:5000" # Exposes the web UI
+    volumes:
+      # Mount the Docker socket (read-only)
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      
+      # This volume is crucial for persisting your encrypted configuration
+      - ./dockflare_data:/app/data
+    networks:
+      - cloudflare-net
+
+# This volume stores your encrypted credentials and state
+volumes:
+  dockflare_data:
+
+# It is recommended to use an external network for your services
+networks:
+  cloudflare-net:
+   name: cloudflare-net
+   external: true
+```
+
+**Note:** Before running the compose file, ensure the external network `cloudflare-net` exists. If not, you can create it with the command: `docker network create cloudflare-net`.
+
+### 2. Run DockFlare
+
+Once you have saved the `docker-compose.yml` file, you can start DockFlare with the following command:
+
+```bash
+docker compose up -d
+```
+
+This will pull the latest stable image and start the DockFlare container in the background.
+
+### 3. Complete the Pre-Flight Setup
+
+After starting the container, open your web browser and navigate to `http://<your-server-ip>:5000`.
+
+You will be greeted by the **Pre-Flight Setup Wizard**. This one-time process will guide you through:
+1.  Creating a password for the Web UI.
+2.  Entering your Cloudflare credentials (Account ID, Zone ID, and API Token).
+3.  Configuring your initial Cloudflare Tunnel.
+
+### 4. For Existing Users (Upgrading)
+
+If you are upgrading from an older version of DockFlare that used a `.env` file, DockFlare will automatically detect it. You will be guided through a simple migration process to import your existing settings and create a password for the new secure setup.

dockflare/app/templates/docs/State-Persistence.md

@@ -0,0 +1,49 @@
+# State Persistence
+
+DockFlare is a stateful application. It needs to keep track of the services it manages, UI overrides, and other configuration details. This state is persisted to disk to ensure that your configuration is not lost if the DockFlare container is restarted or recreated.
+
+## How State is Stored
+
+DockFlare stores its state in two main files located in the `/app/data` directory inside the container:
+
+1.  `dockflare_config.dat`: This is the most critical file. It contains all your core settings and sensitive information in an **encrypted** format. This includes:
+    *   Your Cloudflare API Token and Account ID.
+    *   Your DockFlare UI password hash.
+    *   Core settings configured through the UI, such as the Tunnel Name and Zone IDs.
+
+2.  `state.json`: This file stores the dynamic state of your managed services in a plain JSON format. This includes:
+    *   The list of all ingress rules DockFlare is managing, whether they come from Docker labels or were created manually in the UI.
+    *   Any UI overrides applied to access policies.
+    *   All Access Groups you have created.
+    *   The "pending deletion" status for services that have been stopped but are still within their grace period.
+
+## The Importance of a Persistent Volume
+
+Because all of your configuration is stored in the `/app/data` directory, it is **absolutely crucial** that you map this directory to a persistent volume on your host machine.
+
+If you do not use a persistent volume, **all your settings, UI password, and rule configurations will be lost** every time the DockFlare container is removed and recreated (e.g., when you update the image).
+
+### Recommended Docker Compose Configuration
+
+The recommended `docker-compose.yml` configuration handles this for you automatically by defining a named volume and mounting it to `/app/data`:
+
+```yaml
+services:
+  dockflare:
+    # ... other settings
+    volumes:
+      # This line ensures your data is persisted
+      - ./dockflare_data:/app/data
+
+volumes:
+  # This defines the named volume on your host
+  dockflare_data:
+```
+
+With this configuration, your `dockflare_config.dat` and `state.json` files will be stored in a directory named `dockflare_data` on your host, safely preserving your setup across container updates.
+
+## Backup and Restore
+
+The `state.json` file can be backed up and restored. The DockFlare UI provides a "Backup & Restore" feature on the **Settings** page that allows you to download a copy of your `state.json` and upload it to restore your configuration.
+
+**Note:** The backup and restore feature only includes the `state.json` file. It does **not** include the encrypted `dockflare_config.dat` file. To fully back up your DockFlare instance, you should back up the entire `/app/data` directory.

dockflare/app/templates/docs/Switching-Between-Modes.md

@@ -0,0 +1,81 @@
+# Switching Between Modes
+
+You can switch DockFlare between **Internal** (default) and **External** `cloudflared` modes at any time. This guide explains the process for a smooth transition.
+
+For a detailed comparison of the two modes, please see the [Internal vs. External `cloudflared`](Internal-vs-External-cloudflared.md) page.
+
+---
+
+## Switching from Internal to External Mode
+
+This process involves setting up your own `cloudflared` agent and then telling DockFlare to use it.
+
+**Step 1: Set Up Your External `cloudflared` Agent**
+
+First, you need to set up and run your own `cloudflared` agent. This could be a process on the host OS or another Docker container.
+
+*   Ensure it is configured to use a specific Cloudflare Tunnel.
+*   Make a note of the **Tunnel ID** (UUID).
+*   Start the agent and confirm it is running correctly and shows as "connected" in your Cloudflare dashboard.
+
+**Step 2: Reconfigure and Restart DockFlare**
+
+Next, you need to update the environment variables for your DockFlare container to tell it to switch to external mode.
+
+In your `docker-compose.yml`:
+```yaml
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    # ... other settings
+    environment:
+      # Enable external mode
+      - USE_EXTERNAL_CLOUDFLARED=true
+      # Provide the ID of your running tunnel
+      - EXTERNAL_TUNNEL_ID=your-tunnel-uuid-goes-here
+```
+
+**Step 3: Deploy the Change**
+
+Run `docker compose up -d` to recreate the DockFlare container with the new environment variables.
+
+When the updated DockFlare container starts:
+1.  It will detect that `USE_EXTERNAL_CLOUDFLARED` is `true`.
+2.  It will **stop and remove** its own managed `cloudflared-agent` container.
+3.  It will begin sending all its ingress rule configurations to the tunnel specified by `EXTERNAL_TUNNEL_ID`.
+
+Your services will now be served by your externally managed `cloudflared` agent.
+
+---
+
+## Switching from External to Internal Mode
+
+This process is simpler as it involves letting DockFlare take back control.
+
+**Step 1: Reconfigure DockFlare**
+
+Remove the external mode environment variables from your DockFlare `docker-compose.yml` file.
+
+```yaml
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    # ... other settings
+    environment:
+      # Remove the following two lines
+      # - USE_EXTERNAL_CLOUDFLARED=true
+      # - EXTERNAL_TUNNEL_ID=your-tunnel-uuid-goes-here
+```
+
+**Step 2: Deploy the Change**
+
+Run `docker compose up -d` to recreate the DockFlare container.
+
+When the updated DockFlare container starts:
+1.  It will detect that `USE_EXTERNAL_CLOUDFLARED` is `false`.
+2.  It will automatically **create, configure, and start** its own internal `cloudflared-agent` container.
+3.  It will configure this new agent to use the tunnel name defined in your DockFlare settings.
+
+**Step 3: Decommission Your External Agent**
+
+Once you have confirmed that the new internal agent is running correctly and serving traffic, you can safely stop and remove your own `cloudflared` agent.

dockflare/app/templates/docs/Understanding-Graceful-Deletion.md

@@ -0,0 +1,41 @@
+# Understanding Graceful Deletion
+
+When you stop a container managed by DockFlare, you might notice that its corresponding public hostname doesn't immediately go offline. This is due to a feature called **Graceful Deletion**.
+
+## What is Graceful Deletion?
+
+Instead of instantly deleting the Cloudflare ingress rule and DNS record the moment a container stops, DockFlare marks the rule as **"pending deletion"** and starts a timer.
+
+The associated Cloudflare resources (the ingress rule and DNS record) will only be permanently deleted after this timer, known as the **grace period**, expires.
+
+## Why is This Useful?
+
+This feature is designed to prevent service interruptions in common operational scenarios:
+
+*   **Container Updates:** When you update a container image (`docker compose up -d`), Docker typically stops the old container and starts a new one. Without a grace period, your service would be inaccessible for a short time. With graceful deletion, the DNS record and ingress rule remain active, and DockFlare simply re-associates them with the new container, resulting in zero downtime.
+*   **Temporary Restarts:** If you need to stop a container for a moment to change a setting and then restart it, the grace period ensures that your public-facing configuration remains intact.
+
+## The `GRACE_PERIOD_SECONDS` Variable
+
+The duration of this grace period is controlled by the `GRACE_PERIOD_SECONDS` environment variable, which you can set in your `docker-compose.yml` file.
+
+*   The default value is `600` seconds (10 minutes).
+*   You can adjust this value to suit your needs. A shorter period makes cleanup faster, while a longer period provides a larger window for container restarts.
+
+**Example:**
+```yaml
+services:
+  dockflare:
+    image: alplat/dockflare:stable
+    # ... other settings
+    environment:
+      - GRACE_PERIOD_SECONDS=3600 # Set a 1-hour grace period
+```
+
+## How it Works in Practice
+
+1.  **Container Stopped:** You run `docker stop my-app`.
+2.  **Pending Deletion:** DockFlare detects the stop event. In the Web UI, the rule for `my-app.example.com` will now show its status as **"pending_deletion"** and display the time at which it is scheduled to be deleted.
+3.  **The Two Scenarios:**
+    *   **Scenario A: Grace Period Expires:** If the container remains stopped and the grace period (e.g., 10 minutes) expires, DockFlare's background cleanup task will run. It will delete the ingress rule from your Cloudflare Tunnel and remove the CNAME DNS record.
+    *   **Scenario B: Container Restarts:** If you start the container again (`docker start my-app`) **before** the grace period expires, DockFlare will detect the start event. It will see that the rule is pending deletion, cancel the deletion, and change its status back to **"active"**. Your service continues to operate seamlessly.

dockflare/app/templates/docs/Using-Multiple-Domains-Indexed-Labels.md

@@ -0,0 +1,64 @@
+# Using Multiple Domains (Indexed Labels)
+
+DockFlare provides a powerful feature called **indexed labels** that allows you to define multiple, independent ingress rules for a single container. This is particularly useful when you want to expose different ports or paths of the same service on different public hostnames.
+
+## How It Works
+
+To create multiple rules, you simply prefix the standard DockFlare labels with an integer and a dot, starting from `0`. For example, `dockflare.0.hostname`, `dockflare.1.hostname`, and so on.
+
+*   Each index (e.g., `0`, `1`, `2`) represents a separate ingress rule.
+*   An indexed hostname (e.g., `dockflare.<index>.hostname`) is always required to initiate a new rule.
+*   Other labels at the same index (e.g., `dockflare.<index>.service`) will apply only to that specific rule.
+
+## The Fallback Mechanism
+
+A key feature of indexed labels is the fallback mechanism. If you do not provide a specific indexed label for a rule, it will **fall back to the value of the corresponding base (non-indexed) label**.
+
+This allows you to define common settings once at the base level and only override the specific values that need to change for each indexed rule.
+
+## Example: Exposing a Web UI and an API
+
+Let's say you have a single container that serves both a web application on port `80` and a separate API on port `3000`. You want to expose them on `app.example.com` and `api.example.com` respectively. You also want to secure the API with a specific Access Group, while the main app remains public.
+
+Here is how you would configure this using indexed labels:
+
+```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"
+```
+
+### Breakdown of the Example
+
+*   **Rule 0 (`app.example.com`)**:
+    *   It defines `dockflare.0.hostname`.
+    *   It does not define `dockflare.0.service`, so it falls back to the base `dockflare.service` and uses `http://my-app:80`.
+    *   It's a public service because no access policy is defined for this index or at the base level.
+
+*   **Rule 1 (`api.example.com`)**:
+    *   It defines `dockflare.1.hostname`.
+    *   It **overrides** the service with `dockflare.1.service`, pointing to the API port `3000`.
+    *   It applies a specific security policy using `dockflare.1.access.group`. This label only affects this rule.
+
+This approach keeps your label configuration clean and avoids repetition, making your `docker-compose.yml` files easier to read and maintain.

dockflare/app/templates/docs/Using-Wildcard-Domains.md

@@ -0,0 +1,57 @@
+# Using Wildcard Domains
+
+DockFlare supports using wildcard domains (e.g., `*.example.com`) to route traffic for multiple subdomains to a single service. This is particularly useful for applications that handle dynamic subdomains, such as multi-tenant services or personal dashboards like Heimdall.
+
+## How It Works
+
+When you use a wildcard hostname, Cloudflare Tunnel will route all traffic for any subdomain that doesn't have a more specific DNS record to the service you specify.
+
+For example, if you configure `*.apps.example.com`, traffic for `service1.apps.example.com`, `service2.apps.example.com`, and so on will all be routed to the same destination container.
+
+## Important Considerations
+
+Unlike regular hostnames, DockFlare **cannot automatically create DNS records for wildcard domains**. You must create the wildcard DNS record manually in your Cloudflare dashboard.
+
+DockFlare will still manage the **ingress rule** in your Cloudflare Tunnel, but the initial DNS setup is a manual step.
+
+## Step-by-Step Guide
+
+Here is how to correctly set up a wildcard domain with DockFlare, using `*.plex.example.com` as an example.
+
+### Step 1: Manually Create the Wildcard DNS Record
+
+1.  Log in to your **Cloudflare Dashboard**.
+2.  Navigate to the DNS settings for your domain.
+3.  Click **Add record** and create a CNAME record with the following details:
+    *   **Type:** `CNAME`
+    *   **Name:** `*.plex` (or just `*` if your main domain is `plex.example.com`)
+    *   **Target:** Your tunnel's public hostname. You can find this in your Cloudflare Zero Trust dashboard under **Access -> Tunnels**. It will look something like `your-tunnel-uuid.cfargotunnel.com`.
+    *   **Proxy status:** Make sure it is **Proxied** (orange cloud).
+
+    This manual DNS record tells Cloudflare to send all traffic for `*.plex.example.com` to your tunnel.
+
+### Step 2: Configure Your Service with a Wildcard Label
+
+Now, configure your service in your `docker-compose.yml` file with a wildcard hostname label.
+
+```yaml
+services:
+  my-proxy-manager:
+    image: nginxproxymanager/nginx-proxy-manager
+    restart: unless-stopped
+    networks:
+      - cloudflare-net
+    labels:
+      - "dockflare.enable=true"
+      # Use the wildcard hostname here
+      - "dockflare.hostname=*.plex.example.com"
+      - "dockflare.service=http://my-proxy-manager:81"
+```
+
+### Step 3: Deploy and Verify
+
+1.  Save your `docker-compose.yml` file and run `docker compose up -d`.
+2.  DockFlare will detect the container and create an ingress rule in your Cloudflare Tunnel for the hostname `*.plex.example.com`.
+3.  You can verify this in the DockFlare Web UI and in your tunnel's configuration in the Cloudflare dashboard.
+
+Now, any request to a subdomain like `sonarr.plex.example.com` or `radarr.plex.example.com` will be routed through your Cloudflare Tunnel to your `my-proxy-manager` container, which can then handle the traffic accordingly.

dockflare/app/templates/docs/Using-the-Web-UI.md

@@ -0,0 +1,45 @@
+# Using the Web UI
+
+The DockFlare Web UI is a powerful tool for managing, monitoring, and configuring your services. It provides a user-friendly interface for tasks that go beyond simple Docker label configuration.
+
+## The Dashboard (Main Page)
+
+The first page you see after logging in is the main dashboard. This is your central hub for viewing the state of all your managed services.
+
+*   **Managed Ingress Rules Table:** This table lists every ingress rule that DockFlare is managing, whether it comes from a Docker container or was created manually.
+    *   **Hostname:** The public hostname of the service.
+    *   **Service:** The internal destination URL.
+    *   **Source:** Indicates if the rule is from `Docker` or was created `Manually` in the UI.
+    *   **Status:** Shows if the rule is `active`, `pending_deletion`, or has a `UI Override`.
+    *   **Access:** Displays the Access Policy applied to the rule (e.g., `Public`, `Authenticate`, or the name of an Access Group).
+    *   **Manage Rule:** This button allows you to edit any rule.
+*   **Real-time Logs:** Below the table, you'll find a real-time log viewer that streams logs from the DockFlare backend, which is invaluable for debugging.
+
+## Managing Rules
+
+The UI gives you full control over your ingress rules.
+
+*   **Add Manual Rule:** The "Add Manual Rule" button lets you create ingress rules for services that are not running in Docker (e.g., a service on another machine in your LAN). The form allows you to specify the hostname, service URL, and optionally apply an Access Group.
+*   **Edit any Rule:** The "Manage Rule" button next to every rule opens a modal where you can change its configuration. This is how you can apply a UI override to a rule that was originally created from Docker labels.
+*   **Revert to Labels:** If a rule from Docker has a UI override, a "Revert to Labels" button will appear, allowing you to discard your manual changes and let the rule be controlled by its Docker labels again.
+
+## Access Policies Page
+
+This page is the central location for managing your reusable **Access Groups**. From here, you can:
+*   **Create** new Access Groups with complex rules (e.g., based on email, IP, or country).
+*   **Edit** existing Access Groups.
+*   **Delete** Access Groups that are no longer in use.
+
+For more details, see the [Access Policy Best Practices & Examples](Access-Policy-Best-Practices.md) guide.
+
+## Settings Page
+
+The Settings page contains various administrative and configuration options:
+
+*   **Cloudflare Tunnels:** This section lists all the Cloudflare Tunnels found on your account, their status, and their connected `cloudflared` agents. You can also view all CNAME DNS records pointing to any of your tunnels.
+*   **Backup & Restore:** Allows you to download a backup of your `state.json` file and restore it.
+*   **Security:**
+    *   **Change Password:** Change your password for the Web UI.
+    *   **Disable Password Login:** For advanced use cases where you place DockFlare behind another authentication proxy.
+*   **Cloudflare Credentials:** Allows you to update your Cloudflare Account ID and API Token after the initial setup.
+*   **Core Configuration:** Lets you change settings like the Tunnel Name and Rule Grace Period.