Add Cloudflared configuration with Internet & Internet+LAN examples #1945
Conversation
… for better flexibility
📝 WalkthroughWalkthroughAdds two new example directories demonstrating Pelican Panel deployment with Cloudflare Tunnel integration. The first provides a basic HTTP-only setup, while the second adds LAN HTTPS support with internal CA and local binding. Each includes docker-compose configuration, environment templates, Caddyfile, and documentation. Changes
Pre-merge checks✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
All contributors have signed the CLA ✍️ ✅ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
examples/cloudflare-tunnel/.env.example (1)
13-13: Verify variable substitution support in .env files.Docker Compose's
.envfile handling may not expand${PANEL_DOMAIN}when reading this file—substitution typically works indocker-compose.yml, not in the.envsource itself. Users may need to setAPP_URLto the literal valuehttps://panel.yourdomain.cominstead.
🧹 Nitpick comments (3)
examples/cloudflare-tunnel/docker-compose.yml (1)
16-21: Consider if PANEL_DOMAIN should be passed to the panel service.The
.env.exampledefinesPANEL_DOMAIN, but it's not explicitly passed to the panel service's environment variables. If the panel application or scripts need this value, add it to the environment section. If it's only used for constructingAPP_URL, this can remain as-is.If needed, apply this diff:
environment: XDG_DATA_HOME: /pelican-data APP_URL: ${APP_URL} ADMIN_EMAIL: ${ADMIN_EMAIL} + PANEL_DOMAIN: ${PANEL_DOMAIN} DOCKER_SUBNET: ${DOCKER_SUBNET:-172.21.0.0/16} PHP_UPLOAD_LIMIT: ${PHP_UPLOAD_LIMIT:-256M}examples/cloudflare-tunnel-lan/Caddyfile (1)
8-38: Consider reducing duplication between HTTP and HTTPS blocks.The
:80and:443server blocks contain identicalroot,encode,php_fastcgi, andfile_serverdirectives. While this configuration works correctly, you could reduce duplication using Caddy's snippet feature or by consolidating common directives.Example refactor using snippets:
{ admin off servers { trusted_proxies static {$DOCKER_SUBNET} } } +(common) { + root * /var/www/html/public + encode gzip + php_fastcgi 127.0.0.1:9000 { + env PHP_VALUE "upload_max_filesize = {$PHP_UPLOAD_LIMIT} +post_max_size = {$PHP_UPLOAD_LIMIT}" + } + file_server +} + :80 { - root * /var/www/html/public - encode gzip - - php_fastcgi 127.0.0.1:9000 { - env PHP_VALUE "upload_max_filesize = {$PHP_UPLOAD_LIMIT} -post_max_size = {$PHP_UPLOAD_LIMIT}" - } - - file_server + import common } :443 { - root * /var/www/html/public - encode gzip - tls internal { on_demand } header { Strict-Transport-Security "max-age=31536000" } - php_fastcgi 127.0.0.1:9000 { - env PHP_VALUE "upload_max_filesize = {$PHP_UPLOAD_LIMIT} -post_max_size = {$PHP_UPLOAD_LIMIT}" - } - - file_server + import common }examples/cloudflare-tunnel-lan/docker-compose.yml (1)
20-20: Consider if PANEL_DOMAIN is needed in the environment.
PANEL_DOMAINis passed to the panel service but may not be used by the application directly ifAPP_URLis the canonical configuration variable. Verify whether the panel application or any scripts actually reference this variable.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
examples/cloudflare-tunnel-lan/.env.example(1 hunks)examples/cloudflare-tunnel-lan/Caddyfile(1 hunks)examples/cloudflare-tunnel-lan/README.md(1 hunks)examples/cloudflare-tunnel-lan/docker-compose.yml(1 hunks)examples/cloudflare-tunnel/.env.example(1 hunks)examples/cloudflare-tunnel/Caddyfile(1 hunks)examples/cloudflare-tunnel/README.md(1 hunks)examples/cloudflare-tunnel/docker-compose.yml(1 hunks)
🧰 Additional context used
🪛 LanguageTool
examples/cloudflare-tunnel/README.md
[style] ~13-~13: This phrase is redundant. Consider using “outside”.
Context: ...Usage 1. Copy this directory somewhere outside of the repository, then rename `.env.examp...
(OUTSIDE_OF)
examples/cloudflare-tunnel-lan/README.md
[style] ~17-~17: This phrase is redundant. Consider using “outside”.
Context: ...Usage 1. Copy this directory somewhere outside of the repository, rename .env.example t...
(OUTSIDE_OF)
🔇 Additional comments (6)
examples/cloudflare-tunnel/Caddyfile (1)
1-18: LGTM!The Caddyfile configuration is well-structured for a Cloudflare Tunnel setup:
- Admin interface appropriately disabled for production
- Trusted proxies correctly configured for Docker subnet
- PHP upload limits properly templated
- HTTP-only setup is correct since HTTPS termination happens at Cloudflare
examples/cloudflare-tunnel/docker-compose.yml (1)
8-9: LGTM! Correct configuration for tunnel-only access.Ports are appropriately commented out since all traffic flows through the Cloudflare Tunnel. This prevents direct external access to the panel, which is the intended security posture.
examples/cloudflare-tunnel-lan/README.md (2)
11-13: LGTM! Excellent clarification about APP_URL behavior.The explanation about why
APP_URLmust remain consistent and how to achieve local access through split-horizon DNS is clear and addresses a common point of confusion. This guidance will prevent authentication and signed URL issues.
21-21: Based on my verification through web searches, I can now provide the rewritten review comment:
The internal CA certificate path is correct.
The path
/data/caddy/pki/authorities/local/root.crtis the standard location where Caddy stores its internal Certificate Authority certificate in Docker containers, as confirmed by Caddy documentation. The Pelican panel Docker image uses/dataas the Caddy data directory, making this path accurate. The docker compose cp command is correct as written.examples/cloudflare-tunnel-lan/Caddyfile (1)
24-26: Based on my verification, I have gathered sufficient information to rewrite the review comment.
The
on_demanddirective is valid and documented for use withtls internal.The combination of
tls internalwithon_demandis supported by Caddy and matches the official documentation. Theon_demandsubdirective allows Caddy to provision certificates for arbitrary hostnames on demand using the internal CA, rather than pre-provisioning them. This is a legitimate configuration pattern.examples/cloudflare-tunnel-lan/.env.example (1)
13-13: Based on my verification through multiple web searches, I now have sufficient evidence to determine the accuracy of the original review comment.The original review comment's primary claim is incorrect. Docker Compose documentation and specification clearly confirm that variable interpolation is supported in .env files, including the ability to reference other variables using the
${VAR}syntax.The
APP_URL=https://${PANEL_DOMAIN}syntax in the.env.examplefile at line 13 will work as expected, provided thatPANEL_DOMAINis defined in the same.envfile.Variable substitution works in both:
.envfiles (for unquoted and double-quoted values)docker-compose.ymlfilesThe review comment's suggestion to use a literal value like
https://panel.yourdomain.comis unnecessary and would actually be less flexible than the current parametrized approach.
No issue with variable substitution in .env files.
Docker Compose supports variable interpolation in
.envfiles using the${PANEL_DOMAIN}syntax. The current lineAPP_URL=https://${PANEL_DOMAIN}will correctly expand whenPANEL_DOMAINis defined in the same.envfile. This is documented behavior in Docker Compose and works across versions.
| networks: | ||
| - pelican | ||
| ports: | ||
| - "${LAN_BIND_ADDRESS:-0.0.0.0}:443:443" |
There was a problem hiding this comment.
Security: Default binding to 0.0.0.0 exposes HTTPS to all interfaces.
The LAN_BIND_ADDRESS defaults to 0.0.0.0, which binds the HTTPS port to all network interfaces, potentially exposing the panel to the internet if the host is directly connected. Consider requiring users to explicitly set this variable without a default, or default to 127.0.0.1 with clear documentation to change it.
Apply this diff to require explicit configuration:
ports:
- - "${LAN_BIND_ADDRESS:-0.0.0.0}:443:443"
+ - "${LAN_BIND_ADDRESS:?LAN_BIND_ADDRESS must be set in .env}:443:443"This will cause Docker Compose to fail with a clear error message if LAN_BIND_ADDRESS is not set, forcing users to make a conscious choice.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - "${LAN_BIND_ADDRESS:-0.0.0.0}:443:443" | |
| - "${LAN_BIND_ADDRESS:?LAN_BIND_ADDRESS must be set in .env}:443:443" |
🤖 Prompt for AI Agents
In examples/cloudflare-tunnel-lan/docker-compose.yml at line 9, the
LAN_BIND_ADDRESS currently defaults to 0.0.0.0 which exposes HTTPS on all
interfaces; change this to require explicit configuration or default to
127.0.0.1: remove the 0.0.0.0 fallback and use a required env var expansion (so
compose fails if unset) or set the default to 127.0.0.1, and update the
README/usage docs to explain how to override LAN_BIND_ADDRESS when binding to
other interfaces.
There was a problem hiding this comment.
Valid point. Maintainers, do you have a preference?
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find other docker-compose.yml files in the examples directory to check for patterns
fd -e yml -e yaml docker-compose examples/
# Check how other examples handle port bindings
fd -e yml -e yaml docker-compose examples/ --exec grep -A 2 -B 2 "ports:"
Length of output: 361
@k3vmcd Thanks for checking with the maintainers! I looked through the examples and didn't find an established pattern for port bindings with environment variables—this would be the first.
Here are the trade-offs for each approach to help inform the decision:
Option 1: Require explicit config (no default)
- "${LAN_BIND_ADDRESS:?LAN_BIND_ADDRESS must be set in .env}:443:443"- ✅ Most secure: forces conscious decision
- ✅ Clear error message if forgotten
- ❌ Slightly less convenient for quick testing
Option 2: Default to 127.0.0.1
- "${LAN_BIND_ADDRESS:-127.0.0.1}:443:443"- ✅ Secure by default (localhost only)
- ✅ Still works out-of-box for tunnel-only usage
- ✅ Users can override for LAN access
- ❌ Defeats the purpose of the "LAN" variant if localhost-only
Option 3: Keep 0.0.0.0 with strong documentation
- ✅ Most convenient, works immediately for LAN use case
- ❌ Security risk if used carelessly
- Requires prominent warnings in README
Given this is the LAN variant specifically designed for local network access, Option 2 (defaulting to 127.0.0.1) might not make sense. Perhaps Option 1 with a well-documented .env.example entry would balance security and usability?
Happy to adjust based on what the maintainers prefer! 🙂
|
I have read the CLA Document and I hereby sign the CLA |
|
@k3vmcd A note here. I have a PR to run the panel in http if you run it "behind a proxy" with a single variable https://github.com/pelican-dev/panel/pull/1917/files#diff-4f5cabe26761257a4d685a6edc7a43e0fe0f78762f50eeb48530f2bd3b3ee7caR45 |
|
Thank you very much for writing these up, I think these would be better in their own section on the docs repo and would love to have them there: https://github.com/pelican-dev/docs |
3 participants
This pull request adds two new example configurations for running Pelican Panel behind a Cloudflare Tunnel, with one variant also supporting secure LAN access via HTTPS. Each example includes a complete Docker Compose stack, Caddy server configuration, environment variable templates, and documentation to help users deploy Pelican Panel securely in different network scenarios.
Cloudflare Tunnel + LAN HTTPS Example:
Configuration and documentation:
cloudflare-tunnel-lanexample with a fulldocker-compose.ymlstack that binds HTTPS on a specified LAN IP for local clients, while keeping Cloudflare Tunnel for remote access.Caddyfilethat serves the app over HTTP for the tunnel and HTTPS (with internal CA) for LAN traffic, including support for higher PHP upload limits..env.examplefile with new variables such asLAN_BIND_ADDRESSto help users configure LAN HTTPS access.README.mdexplaining setup steps, LAN certificate trust, and DNS configuration for split-horizon access.Cloudflare Tunnel Example (Internet-only):
Configuration and documentation:
cloudflare-tunnelexample with a minimal Docker Compose stack for serving Pelican Panel exclusively through Cloudflare Tunnel, keeping host ports closed.Caddyfiletuned for reverse proxy and upload limits, and a.env.exampletemplate for required environment variables. [1] [2]README.mdguiding users through tunnel setup and deployment.