mirror of
https://github.com/ChrispyBacon-dev/DockFlare.git
synced 2026-04-26 10:50:43 +00:00
✨v1.8.0
This commit is contained in:
ChrispyBacon-dev
parent
4bbbbca577
commit
562fec5879
9 changed files with 22 additions and 400 deletions
1
.github/workflows/docker-image.yml
vendored
1
.github/workflows/docker-image.yml
vendored
|
|
@ -13,6 +13,7 @@
|
|||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
# .github/docker-image.yml
|
||||
name: Docker Image Build and Push (Conditional Arch)
|
||||
|
||||
on:
|
||||
|
|
|
|||
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -1,3 +1,4 @@
|
|||
#.gitignore
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
|
|
|
|||
|
|
@ -1,9 +1,7 @@
|
|||
```markdown
|
||||
# GNU General Public License v3.0
|
||||
|
||||
This project, DockFlare, is licensed under the GNU General Public License version 3.0.
|
||||
|
||||
```
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ DockFlare simplifies Cloudflare Tunnel and Zero Trust Access policy management b
|
|||
## ⚙️ Getting Started
|
||||
|
||||
<details>
|
||||
<summary>📋 Important Prerequisites - Cloudflare API</summary>
|
||||
<summary>📋 Important Prerequisites for Cloudflare API</summary>
|
||||
|
||||
- Docker: [Install Docker](https://docs.docker.com/engine/install/)
|
||||
- Docker Compose: [Install Docker Compose](https://docs.docker.com/compose/install/)
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
version: '3.8'
|
||||
services:
|
||||
dockflare:
|
||||
image: alplat/dockflare:stable # Use the stable pre-built image
|
||||
image: alplat/dockflare:stable # alplat/dockflare:unstable docker tag for beta versions
|
||||
# build: . # Uncomment to build from source instead
|
||||
container_name: dockflare
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "5000:5000" # Web UI port
|
||||
- "5000:5000"
|
||||
env_file:
|
||||
- .env # Load environment variables from .env file
|
||||
volumes:
|
||||
|
|
@ -22,24 +22,20 @@ services:
|
|||
#- cloudflare.tunnel.hostname=dockflare.yourdomain.tld
|
||||
#- cloudflare.tunnel.service=http://dockflare:5000
|
||||
# cloudflare.tunnel.access.policy: "authenticate"
|
||||
#cloudflare.tunnel.access.app_launcher_visible: "false"
|
||||
#cloudflare.tunnel.access.name: "Custom Rules" # Example for Custom Rule Access authentication via Email and Allow a specifiy IP - You can change everything in UI as well.
|
||||
#cloudflare.tunnel.access.custom_rules: '[{"name": "Allow Specific Email", "decision": "allow", "include": [{"email": {"email": "your@email.com"}}]},{"name": "Allow Your IP", "decision": "allow", "include": [{"ip": {"ip": "YOURIP/32"}}]},{"name": "Deny Everyone Else", "decision": "deny", "include": [{"everyone": {}}]}]'
|
||||
|
||||
# Container Scanning:
|
||||
# - SCAN_ALL_NETWORKS=true # Scan containers across all Docker networks
|
||||
|
||||
# For reverse proxy usage:
|
||||
# - TRUSTED_PROXIES=172.16.0.0/12 # IP range of your proxy servers
|
||||
|
||||
# For external cloudflared:
|
||||
# - USE_EXTERNAL_CLOUDFLARED=true
|
||||
# - EXTERNAL_TUNNEL_ID=your-external-tunnel-id
|
||||
|
||||
# SSL verification for origin services:
|
||||
# - DEFAULT_NO_TLS_VERIFY=false # Set to true to skip SSL verification for all services
|
||||
#cloudflare.tunnel.access.app_launcher_visible: "false"
|
||||
#cloudflare.tunnel.access.name: "Custom Rules" # Example for Custom Rule Access authentication via Email and Allow a specifiy IP - You can change everything in UI as well.
|
||||
#cloudflare.tunnel.access.custom_rules: '[{"name": "Allow Specific Email", "decision": "allow", "include": [{"email": {"email": "your@email.com"}}]},{"name": "Allow Your IP", "decision": "allow", "include": [{"ip": {"ip": "YOURIP/32"}}]},{"name": "Deny Everyone Else", "decision": "deny", "include": [{"everyone": {}}]}]'
|
||||
# Container Scanning:
|
||||
# - SCAN_ALL_NETWORKS=true # Scan containers across all Docker networks
|
||||
# For reverse proxy usage:
|
||||
# - TRUSTED_PROXIES=172.16.0.0/12 # IP range of your proxy servers
|
||||
# For external cloudflared:
|
||||
# - USE_EXTERNAL_CLOUDFLARED=true
|
||||
# - EXTERNAL_TUNNEL_ID=your-external-tunnel-id
|
||||
# SSL verification for origin services:
|
||||
# - DEFAULT_NO_TLS_VERIFY=false # Set to true to skip SSL verification for all services
|
||||
volumes:
|
||||
dockflare_data: # Persistent volume for state data
|
||||
dockflare_data:
|
||||
networks:
|
||||
cloudflare-net:
|
||||
name: cloudflare-net
|
||||
1
dockflare/.gitignore
vendored
1
dockflare/.gitignore
vendored
|
|
@ -1,3 +1,4 @@
|
|||
#.gitignore
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
|
|
|
|||
|
|
@ -55,6 +55,7 @@ TUNNEL_NAME=dockflared-tunnel
|
|||
# USE_EXTERNAL_CLOUDFLARED=false
|
||||
|
||||
# External Tunnel ID (Required ONLY if USE_EXTERNAL_CLOUDFLARED=true)
|
||||
# Please note currently under review not recommended.
|
||||
# The ID of your existing, externally managed Cloudflare Tunnel.
|
||||
# Find in Cloudflare Dashboard: Zero Trust -> Access -> Tunnels -> (select your tunnel)
|
||||
# EXTERNAL_TUNNEL_ID=your_existing_external_tunnel_id
|
||||
|
|
@ -67,8 +68,8 @@ LABEL_PREFIX=cloudflare.tunnel
|
|||
|
||||
# Grace Period for Rule Deletion (seconds)
|
||||
# How long DockFlare keeps ingress rules for a stopped Docker container before deletion.
|
||||
# Default: 28800 (8 hours)
|
||||
GRACE_PERIOD_SECONDS=28800
|
||||
# Default: 28800 (8h)
|
||||
GRACE_PERIOD_SECONDS=600
|
||||
|
||||
# Cleanup Interval (seconds)
|
||||
# How often DockFlare checks for expired rules to delete.
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 725 KiB After Width: | Height: | Size: 725 KiB |
376
readme_draft.md
376
readme_draft.md
|
|
@ -1,376 +0,0 @@
|
|||
|
||||
[](https://github.com/ChrispyBacon-dev/baconflip)
|
||||
[]()
|
||||
[](https://en.wikipedia.org/wiki/Central_processing_unit)
|
||||
[](https://github.com/ChrispyBacon-dev/DockFlare/releases/tag/v1.8.0)
|
||||
[](https://hub.docker.com/r/alplat/dockflare)
|
||||
[](https://www.python.org/)
|
||||
[](https://github.com/ChrispyBacon-dev/dockflare/issues)
|
||||
[](https://github.com/ChrispyBacon-dev/dockflare/commits/stable)
|
||||
[](https://github.com/ChrispyBacon-dev/dockflare/commits/stable)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 What is DockFlare?
|
||||
|
||||
DockFlare simplifies Cloudflare Tunnel and Zero Trust Access policy management by using Docker labels for automated configuration, while also providing a powerful web UI for manual service definitions and policy overrides. It enables secure, hassle-free public access to both Dockerized and non-Dockerized applications with minimal direct interaction with Cloudflare. Acting as a dynamic, self-hosted ingress controller, DockFlare offers persistent, UI-driven control over access policies centralizing and streamlining your access management.
|
||||
|
||||
<details>
|
||||
<summary>✨ Key Features</summary>
|
||||
|
||||
- **Unified Cloudflare Tunnel Management**:
|
||||
- Automates Tunnel creation/use & `cloudflared` agent lifecycle (optional internal deployment or external).
|
||||
- **Dynamic Ingress via Docker Labels**:
|
||||
- Auto-configures Tunnel ingress & DNS from Docker labels (e.g., `cloudflare.tunnel.hostname`, `service`) by monitoring container events.
|
||||
- **Manual Ingress Rule Management**:
|
||||
- Add & manage public hostnames for non-Docker services (e.g., router, NAS) via Web UI; DockFlare handles Tunnel rules & DNS.
|
||||
- **Versatile Access Policy Control (Docker & Manual)**:
|
||||
- Define Cloudflare Access Policies (e.g., `bypass`, `authenticate`, custom JSON) via Docker labels; auto-manages Access Applications.
|
||||
- Web UI to manage/override policies for *any* rule; UI changes persist, override labels, with revert option & clear indicators.
|
||||
- **Multi-Hostname & Multi-Zone**:
|
||||
- Supports multiple hostnames (unique targets, zones, policies) per Docker container (indexed labels) or manual rule.
|
||||
- **State Persistence & Graceful Deletion**:
|
||||
- Configurable grace period for Docker rule cleanup; persists all managed rules, Access App IDs, & UI overrides in `state.json`.
|
||||
- **Intelligent Reconciliation**:
|
||||
* Continuously syncs Docker, manual entries, & saved state (respecting UI overrides) with Cloudflare (Tunnel, DNS, Access Apps); shows UI progress.
|
||||
- **Comprehensive Web UI (DaisyUI)**:
|
||||
- **Dashboard**: Tunnel/agent status & controls.
|
||||
- **Unified Rule List**: View/manage all rules (Docker & manual) with status, target, Access Policy (Cloudflare links, UI override badges), & delete options.
|
||||
- **Easy Manual Entry**: Add non-Docker services via UI.
|
||||
- **Account Tools**: View account tunnels/DNS.
|
||||
- **Real-time Logs & Themes**: SSE activity logs & multiple UI themes.
|
||||
- **Secure & Robust**:
|
||||
- Content Security Policy (CSP), API retries, and error reporting.
|
||||
|
||||
[Learn more on the GitHub Wiki](https://github.com/ChrispyBacon-dev/DockFlare/wiki)
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🖼️ Web UI Preview
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Getting Started
|
||||
|
||||
<details>
|
||||
<summary>📋 Prerequisites</summary>
|
||||
|
||||
- Docker: [Install Docker](https://docs.docker.com/engine/install/)
|
||||
- Docker Compose: [Install Docker Compose](https://docs.docker.com/compose/install/)
|
||||
- Cloudflare Account with:
|
||||
- API Token with Account:Cloudflare Tunnel:Edit, Account:Account Settings:Read, Account:Access: Apps and Policies:Edit, Zone:Zone:Read, Zone:DNS:Edit
|
||||
|
||||
*(Note: Account Settings Read is planned for future features, not strictly required for current core functionality.)*
|
||||
- Account ID (found in Cloudflare Dashboard → Overview)
|
||||
- Zone ID (found in Cloudflare Dashboard → Overview for your primary domain)
|
||||
|
||||
</details>
|
||||
|
||||
### 🚀 Quick Start (Docker Compose)
|
||||
|
||||
1. **Create `docker-compose.yml`**:
|
||||
```yaml
|
||||
# Your docker-compose.yml content
|
||||
version: '3.8'
|
||||
services:
|
||||
dockflare:
|
||||
image: alplat/dockflare:stable # Or :unstable for the latest features
|
||||
container_name: dockflare
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "5000:5000"
|
||||
env_file:
|
||||
- .env
|
||||
environment:
|
||||
- STATE_FILE_PATH=/app/data/state.json
|
||||
- TZ=Europe/Zurich # Set your timezone
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- dockflare_data:/app/data
|
||||
networks:
|
||||
- cloudflare-net
|
||||
# Optional labels to expose DockFlare itself via DockFlare
|
||||
# labels:
|
||||
# - cloudflare.tunnel.enable=true
|
||||
# - cloudflare.tunnel.hostname=dockflare.yourdomain.tld
|
||||
# - cloudflare.tunnel.service=http://dockflare:5000
|
||||
# - cloudflare.tunnel.access.policy=authenticate # Example: require login
|
||||
volumes:
|
||||
dockflare_data:
|
||||
networks:
|
||||
cloudflare-net:
|
||||
name: cloudflare-net
|
||||
```
|
||||
|
||||
2. **Create `.env` File**:
|
||||
Copy `env.example` to `.env` and fill in your details.
|
||||
<details>
|
||||
<summary>📄 Example `.env` content (Click to expand)</summary>
|
||||
|
||||
```dotenv
|
||||
# === REQUIRED CLOUDFLARE CREDENTIALS ===
|
||||
CF_API_TOKEN=your_cloudflare_api_token_here
|
||||
CF_ACCOUNT_ID=your_cloudflare_account_id_here
|
||||
|
||||
# Default Cloudflare Zone ID (Recommended)
|
||||
# If not set, cloudflare.tunnel.zonename label is REQUIRED for all services.
|
||||
CF_ZONE_ID=your_default_cloudflare_zone_id_here
|
||||
|
||||
# === TUNNEL CONFIGURATION ===
|
||||
# Name for the Cloudflare Tunnel managed by DockFlare
|
||||
# (Required if NOT using an external cloudflared instance)
|
||||
TUNNEL_NAME=DockFlare-Tunnel
|
||||
|
||||
# --- External Cloudflared Mode (Advanced) ---
|
||||
# USE_EXTERNAL_CLOUDFLARED=false
|
||||
# EXTERNAL_TUNNEL_ID=your_existing_external_tunnel_id
|
||||
|
||||
# === DOCKFLARE BEHAVIOR & CUSTOMIZATION ===
|
||||
LABEL_PREFIX=cloudflare.tunnel
|
||||
GRACE_PERIOD_SECONDS=28800
|
||||
CLEANUP_INTERVAL_SECONDS=300
|
||||
AGENT_STATUS_UPDATE_INTERVAL_SECONDS=10
|
||||
# STATE_FILE_PATH=/app/data/state.json # Usually set in docker-compose
|
||||
SCAN_ALL_NETWORKS=false
|
||||
CLOUDFLARED_NETWORK_NAME=cloudflare-net
|
||||
# TUNNEL_DNS_SCAN_ZONE_NAMES=extradomain.com,another-zone.net
|
||||
|
||||
# === PERFORMANCE & RESOURCE MANAGEMENT ===
|
||||
MAX_CONCURRENT_DNS_OPS=3
|
||||
# RECONCILIATION_BATCH_SIZE=3 # Placeholder
|
||||
```
|
||||
*Refer to `env.example` for a full list of options and detailed comments.*
|
||||
</details>
|
||||
|
||||
3. **Run DockFlare**:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
4. **Access the Web UI**: Open `http://your-server-ip:5000` in your browser.
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ How It Works & Labeling Containers
|
||||
|
||||
DockFlare listens for Docker container events.
|
||||
- **Label-First for Initial Setup**: By labeling your containers, DockFlare initially configures Cloudflare Tunnel ingress rules, DNS records, and associated Cloudflare Zero Trust Access Applications.
|
||||
- **UI for Dynamic Overrides**: The Web UI allows you to dynamically change Access Policies for individual services. These UI changes take precedence over container labels and are persistent.
|
||||
- **Revert Option**: You can always revert a UI-managed Access Policy back to be controlled by the container's labels via the Web UI.
|
||||
|
||||
<details>
|
||||
<summary>📝 Labeling Your Containers (Examples & Details)</summary>
|
||||
|
||||
DockFlare supports two approaches for labeling containers:
|
||||
|
||||
#### 1. Standard Labels (Single Domain per Service)
|
||||
|
||||
To expose a service through DockFlare, add the following labels to your container:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
my-service:
|
||||
image: nginx:latest
|
||||
labels:
|
||||
# Enable DockFlare management for this container
|
||||
- "cloudflare.tunnel.enable=true" # Use quotes for boolean-like strings
|
||||
|
||||
# The public hostname to expose
|
||||
- "cloudflare.tunnel.hostname=my-service.example.com"
|
||||
|
||||
# The internal service address (protocol://container_name_or_ip:port)
|
||||
- "cloudflare.tunnel.service=http://my-service:80" # Or http://<container_name>:<port>
|
||||
|
||||
# Optional: Specify a different Cloudflare Zone for this hostname
|
||||
# - "cloudflare.tunnel.zonename=another.example.com"
|
||||
|
||||
# Optional: Disable TLS verification if your internal service uses HTTP or a self-signed cert
|
||||
# - "cloudflare.tunnel.no_tls_verify=true"
|
||||
networks:
|
||||
- cloudflare-net # Ensure it's on a network DockFlare can reach or its own agent can reach
|
||||
```
|
||||
|
||||
#### 2. Indexed Labels (Multiple Hostnames/Services from One Container)
|
||||
|
||||
To expose multiple hostnames or services from a single container, use indexed labels:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
multi-host-app:
|
||||
image: my-custom-app:latest
|
||||
labels:
|
||||
- "cloudflare.tunnel.enable=true"
|
||||
|
||||
# First hostname configuration
|
||||
- "cloudflare.tunnel.0.hostname=app1.example.com"
|
||||
- "cloudflare.tunnel.0.service=http://multi-host-app:8080" # Points to port 8080
|
||||
# - "cloudflare.tunnel.0.access.policy=authenticate" # Specific policy for this hostname
|
||||
|
||||
# Second hostname configuration
|
||||
- "cloudflare.tunnel.1.hostname=api.example.com"
|
||||
- "cloudflare.tunnel.1.service=http://multi-host-app:3000" # Points to port 3000
|
||||
# - "cloudflare.tunnel.1.zonename=otherexample.com" # Can be in a different zone
|
||||
|
||||
# Default service if an indexed service is not specified (less common with indexed setups)
|
||||
# - "cloudflare.tunnel.service=http://multi-host-app:80"
|
||||
networks:
|
||||
- cloudflare-net
|
||||
```
|
||||
> **Note**: Index numbers must be sequential starting from `0` (e.g., `0`, `1`, `2`). Any gap will stop further processing of indexed labels for that container. Each indexed entry is treated as a separate rule.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>🛡️ Access Policy Labels (Zero Trust)</summary>
|
||||
|
||||
These labels define the *initial* Cloudflare Access Policy for an exposed `hostname`. UI changes persist and override these labels unless "Reverted to Labels".
|
||||
|
||||
| Label | Description | Default | Example |
|
||||
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------- | :---------------------------------------------------------------------------------------- |
|
||||
| `{prefix}.access.policy` | Type: `bypass` (public app), `authenticate` (IdP login), `default_tld` (inherits from `*.domain.com` policy, no specific app created). If unset, service is public (no Access App). | (None/Public) | `cloudflare.tunnel.access.policy="authenticate"` |
|
||||
| `{prefix}.access.name` | Custom name for the Cloudflare Access Application. | `DockFlare-{hostname}` | `cloudflare.tunnel.access.name="My Web App Access"` |
|
||||
| `{prefix}.access.session_duration` | Session duration (e.g., `24h`, `30m`). | `24h` | `cloudflare.tunnel.access.session_duration="1h"` |
|
||||
| `{prefix}.access.app_launcher_visible` | If `"true"`, app is visible in Cloudflare App Launcher. | `false` | `cloudflare.tunnel.access.app_launcher_visible="true"` |
|
||||
| `{prefix}.access.allowed_idps` | Comma-separated IdP UUIDs. If `authenticate` & unset, allows any account IdP. | (Account Default) | `cloudflare.tunnel.access.allowed_idps="<IdP_UUID_1>,<IdP_UUID_2>"` |
|
||||
| `{prefix}.access.auto_redirect_to_identity` | If `"true"`, auto-redirects to IdP login. | `false` | `cloudflare.tunnel.access.auto_redirect_to_identity="true"` |
|
||||
| `{prefix}.access.custom_rules` | JSON string array of [Cloudflare Access Policy rules](https://developers.cloudflare.com/api/operations/access-policies-create-an-access-policy). Overrides basic `access.policy` decisions. | (None) | `'...=[{"email":{"email":"user@example.com"},"action":"allow"},{"action":"block"}]'` |
|
||||
|
||||
**Example of Access Policy Labels:**
|
||||
```yaml
|
||||
labels:
|
||||
- "cloudflare.tunnel.enable=true"
|
||||
- "cloudflare.tunnel.hostname=secure-app.example.com"
|
||||
- "cloudflare.tunnel.service=http://my-secure-app:8080"
|
||||
- "cloudflare.tunnel.access.policy=authenticate"
|
||||
- "cloudflare.tunnel.access.session_duration=8h"
|
||||
# - "cloudflare.tunnel.access.allowed_idps=YOUR_GITHUB_IDP_UUID_HERE"
|
||||
```
|
||||
This creates an Access Application named "DockFlare-secure-app.example.com" requiring authentication with an 8-hour session.
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Advanced Configuration & Usage
|
||||
|
||||
<details>
|
||||
<summary>⚙️ All Environment Variables</summary>
|
||||
|
||||
| Variable | Description | Default |
|
||||
| :-------------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------- |
|
||||
| `CF_API_TOKEN` | Cloudflare API token | **(Required)** |
|
||||
| `CF_ACCOUNT_ID` | Cloudflare account ID | **(Required)** |
|
||||
| `CF_ZONE_ID` | Default/fallback Cloudflare zone ID. | (None - `zonename` label needed) |
|
||||
| `TUNNEL_NAME` | Name for the Cloudflare tunnel (if DockFlare manages it). | `dockflared-tunnel` |
|
||||
| `GRACE_PERIOD_SECONDS` | Time (sec) before removing rules after container stops. | `28800` (8 hours) |
|
||||
| `CLEANUP_INTERVAL_SECONDS` | Interval (sec) for checking expired rules. | `300` (5 minutes) |
|
||||
| `AGENT_STATUS_UPDATE_INTERVAL_SECONDS` | Interval (sec) to update managed agent status. | `10` |
|
||||
| `LABEL_PREFIX` | Prefix for Docker labels. | `cloudflare.tunnel` |
|
||||
| `USE_EXTERNAL_CLOUDFLARED` | Set to `true` to use an existing `cloudflared` agent. | `false` |
|
||||
| `EXTERNAL_TUNNEL_ID` | Tunnel ID for external `cloudflared` mode. | (Required if external is true) |
|
||||
| `SCAN_ALL_NETWORKS` | Scan containers across all Docker networks. | `false` |
|
||||
| `CLOUDFLARED_NETWORK_NAME` | Docker network for DockFlare's managed `cloudflared` agent. | `cloudflare-net` |
|
||||
| `STATE_FILE_PATH` | Path inside container for state persistence (`state.json`). | `/app/data/state.json` |
|
||||
| `TUNNEL_DNS_SCAN_ZONE_NAMES` | Comma-separated additional Zone NAMES for UI DNS scan (e.g., `another.com,mydomain.org`). | (None) |
|
||||
| `MAX_CONCURRENT_DNS_OPS` | Limits simultaneous DNS API calls during reconciliation. | `3` |
|
||||
| `RECONCILIATION_BATCH_SIZE` | (Placeholder for future) DNS records to process per batch. | `3` |
|
||||
| `ACCOUNT_EMAIL_CACHE_TTL` | (Internal) How long to cache the account email (seconds). | `3600` (1 hour) |
|
||||
| `TZ` | Set timezone for the container, e.g. `America/New_York`. Affects log timestamps. | (System Default) |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>🔄 External `cloudflared` Mode & Switching</summary>
|
||||
|
||||
IMPORTANT: Currently this Mode is under heavy development and not recommended.
|
||||
DockFlare can manage DNS and Access Applications for an existing `cloudflared` tunnel that you manage separately.
|
||||
|
||||
**To use External Mode:**
|
||||
1. Set `USE_EXTERNAL_CLOUDFLARED=true` in your `.env`.
|
||||
2. Set `EXTERNAL_TUNNEL_ID` to your existing tunnel's ID.
|
||||
<details>
|
||||
<summary>Find Your Tunnel ID</summary>
|
||||
|
||||
1. Log in to [Cloudflare Dashboard](https://dash.cloudflare.com).
|
||||
2. Navigate to **Zero Trust** -> **Access** -> **Tunnels**.
|
||||
3. Select your tunnel. The ID is in the URL and on the overview page.
|
||||
</details>
|
||||
|
||||
**DockFlare's Behavior in External Mode:**
|
||||
- DockFlare will **not** start or manage a `cloudflared` agent container.
|
||||
- It **will** create/delete CNAME DNS records pointing to your `EXTERNAL_TUNNEL_ID`.
|
||||
- It **will** create/update/delete Cloudflare Access Applications based on labels or UI interactions for services it manages.
|
||||
- It will **not** modify the tunnel's ingress rules directly (as this is typically managed by the external `cloudflared` agent's configuration file).
|
||||
|
||||
> [!WARNING]
|
||||
> **Authoritative DNS Management in External Mode:**
|
||||
> When `USE_EXTERNAL_CLOUDFLARED=true`, DockFlare assumes it has authoritative control over CNAME records in the specified zones that point to the `EXTERNAL_TUNNEL_ID`. It may remove CNAMEs it doesn't recognize as actively managed by its rules if they point to the same tunnel ID. Ensure no other systems are creating CNAMEs for this specific external tunnel in the zones DockFlare monitors.
|
||||
|
||||
**Switching Modes (e.g., Internal to External):**
|
||||
This requires careful steps to avoid conflicts.
|
||||
1. **Stop DockFlare:** `docker compose stop dockflare`
|
||||
2. **If moving from Internal to External:**
|
||||
* Remove the DockFlare-managed agent: `docker rm -f cloudflared-agent-YOUR_TUNNEL_NAME` (replace `YOUR_TUNNEL_NAME` with the value from your old `.env`).
|
||||
* Consider deleting the old tunnel object and its DNS CNAMEs from the Cloudflare dashboard if you are setting up a brand new external tunnel.
|
||||
3. **Set up your external `cloudflared` agent** and get its Tunnel ID.
|
||||
4. **Update `.env`**: Set `USE_EXTERNAL_CLOUDFLARED=true` and `EXTERNAL_TUNNEL_ID`. Clear or comment out `TUNNEL_NAME`.
|
||||
5. **Optional: Clear Old State:** For a clean switch, you might consider removing the old `state.json` (e.g., `docker volume rm dockflare_data` then `docker volume create dockflare_data`, or delete the file if mapped to host). DockFlare will then rebuild state from active containers.
|
||||
6. **Start DockFlare:** `docker compose up -d dockflare`
|
||||
7. **Verify:** Check UI, logs, and Cloudflare dashboard.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>🗺️ Multi-Zone DNS Management</summary>
|
||||
|
||||
DockFlare handles services across multiple Cloudflare zones (domains).
|
||||
|
||||
1. **Container-Specific Zone (Label):**
|
||||
Use `cloudflare.tunnel.zonename="yourdomain.com"` on a container (or indexed entry) to specify its zone. DockFlare resolves the Zone ID automatically.
|
||||
```yaml
|
||||
labels:
|
||||
- "cloudflare.tunnel.0.hostname=app.customdomain.com"
|
||||
- "cloudflare.tunnel.0.service=http://my-service:80"
|
||||
- "cloudflare.tunnel.0.zonename=customdomain.com"
|
||||
```
|
||||
2. **Default Zone (Environment Variable):**
|
||||
Set `CF_ZONE_ID` in your `.env` file. This is used if a `zonename` label isn't provided for a rule.
|
||||
3. **UI DNS Scan (Multiple Zones):**
|
||||
To see DNS records for a tunnel across multiple zones you own (in the "All Cloudflare Tunnels" UI section), set `TUNNEL_DNS_SCAN_ZONE_NAMES` in your `.env` with a comma-separated list of zone *names* (e.g., `TUNNEL_DNS_SCAN_ZONE_NAMES=domain1.com,another.org`). `CF_ZONE_ID`'s domain is included automatically if set.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>🔍 Troubleshooting & Health Checks</summary>
|
||||
|
||||
**Common Issues:**
|
||||
- **Log Stream Not Working**: Ensure browser supports SSE. Check for network filtering or reverse proxy issues (ensure SSE/long-polling is allowed).
|
||||
- **Container Not Detected**:
|
||||
- Verify correct labels (prefix, enable, hostname, service).
|
||||
- Container network accessible by DockFlare/agent (or `SCAN_ALL_NETWORKS=true`).
|
||||
- Valid hostname and service format (e.g., `http://host:port`).
|
||||
- **Cloudflare API Errors**: Check `CF_API_TOKEN` permissions, `CF_ACCOUNT_ID`, and `CF_ZONE_ID`.
|
||||
|
||||
**Debugging:**
|
||||
- View logs in DockFlare Web UI or via `docker logs dockflare`.
|
||||
|
||||
**Health Checks:**
|
||||
- **DockFlare App Ping**: `http://<dockflare_host>:5000/ping`
|
||||
- **Cloudflare Connectivity (via Tunnel)**: Access `http://<your_dockflare_public_hostname>/cloudflare-ping` (if you've exposed DockFlare itself) to check headers from Cloudflare.
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) or open an issue/PR.
|
||||
|
||||
## 📜 License
|
||||
|
||||
DockFlare is licensed under the GNU General Public License v3.0. See [LICENSE.MD](LICENSE.MD) for details.
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue