From a41453f3543b5a10991f8536e38841daadccfbdd Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Sun, 7 Dec 2025 11:32:01 -0600 Subject: [PATCH] feat: add new guides for Cloudflare Tunnels and EC2 setup - Introduced comprehensive guides for setting up Cloudflare Tunnels and deploying applications on AWS EC2. - Updated meta.json to include new guide entries, enhancing the documentation structure. - Removed outdated EC2 instructions to streamline content and improve clarity. --- .../docs/core/guides/cloudflare-tunnels.mdx | 165 ++++++++++++++++++ .../docs/core/guides/ec2-instructions.mdx | 86 +++++++++ apps/docs/content/docs/core/meta.json | 4 +- .../core/remote-servers/ec2-instructions.mdx | 47 ----- 4 files changed, 254 insertions(+), 48 deletions(-) create mode 100644 apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx create mode 100644 apps/docs/content/docs/core/guides/ec2-instructions.mdx delete mode 100644 apps/docs/content/docs/core/remote-servers/ec2-instructions.mdx diff --git a/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx b/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx new file mode 100644 index 0000000..05dcc86 --- /dev/null +++ b/apps/docs/content/docs/core/guides/cloudflare-tunnels.mdx @@ -0,0 +1,165 @@ +--- +title: Cloudflare Tunnels +description: Learn how to use Cloudflare Tunnels to securely expose your Dokploy applications without opening ports on your server. +--- + +import { Callout } from 'fumadocs-ui/components/callout'; + +Cloudflare Tunnels provide a secure way to connect your applications to the internet without exposing ports on your server. This is particularly useful for home servers or networks where you can't easily configure port forwarding or want enhanced security. + +## What are Cloudflare Tunnels? + +Cloudflare Tunnels (formerly Argo Tunnels) create an encrypted tunnel between your origin server and Cloudflare's global network. Instead of opening ports 80 and 443 on your server, the tunnel establishes an outbound-only connection to Cloudflare, which then routes traffic to your applications. + +### Benefits + +- **Enhanced Security**: No need to open inbound ports on your firewall +- **Simple Setup**: Works behind NAT and restrictive firewalls +- **DDoS Protection**: Traffic is routed through Cloudflare's network +- **Free Tier Available**: Included with free Cloudflare accounts +- **Wildcard Support**: Route multiple subdomains through a single tunnel + +## Prerequisites + +Before setting up Cloudflare Tunnels with Dokploy, ensure you have: + +- A domain managed by Cloudflare (free tier works) +- Dokploy installed and running +- Access to Cloudflare dashboard + + + When using Cloudflare Tunnels, you should **disable Let's Encrypt** in Dokploy and use HTTP instead of HTTPS for internal connections. Cloudflare handles SSL/TLS termination at their edge. + + +## Cloudflare Tunnel Setup + +### Step 1: Create a Tunnel in Cloudflare + +- Log in to your [Cloudflare Dashboard](https://dash.cloudflare.com/) +- Navigate to **Zero Trust** (or **Access** in older dashboards) +- Go to **Networks** → **Connectors** +- Click **Create a tunnel** +- Choose **Cloudflared** as the connector type +- Give your tunnel a name (e.g., `dokploy-tunnel`) +- Copy the **Tunnel Token** that's generated (you'll need this later) + + + Keep your tunnel token secure! It provides access to route traffic to your server. + + +### Step 2: Configure SSL/TLS Settings + +For Cloudflare Tunnels to work properly with Dokploy: + +- In Cloudflare Dashboard, go to **SSL/TLS** +- Set the encryption mode to **Full** or **Full (Strict)** + + + Do not use "Flexible" mode as it may cause redirect loops with Traefik. + + +### Step 3: Create Cloudflare Service in Dokploy + +1. Create a new application +2. Select Docker Provider and set the Image name as `cloudflare/cloudflared` +3. Go to the Environments tab and add the token you copied: `TUNNEL_TOKEN="TOKEN-YOU-COPIED"` +4. Go to the Advanced tab, in the Arguments field add 2 entries: first `tunnel`, second `run`, then click save +5. Deploy the application. You should see the container in healthy status in the logs section + + +### Step 4: Configuring Public Hostnames (Domains) + +After deploying cloudflared, you need to configure which domains route through the tunnel. + +#### Understanding Traefik Routing vs Direct Access + +Dokploy uses **Traefik** as its reverse proxy to route traffic to your applications. When configuring Cloudflare Tunnels, you have two options: + +**Option 1: Route through Traefik (Recommended)** +- **Traffic flow**: Cloudflare → Tunnel → Traefik → Your Apps +- **Benefits**: + - Support for multiple applications with a single tunnel (wildcard domains) + - Leverage all Dokploy domain configurations (redirects, path rewrites, etc.) + - Traefik automatically routes based on the domain you configured in Dokploy + - Configure once, works for all apps + +**Option 2: Direct Container Access** +- **Traffic flow**: Cloudflare → Tunnel → Your App (bypasses Traefik) +- **Benefits**: + - Simpler setup for single applications + - Slightly lower latency (one less hop) +- **When to use**: For single dedicated services or special cases +- **Note**: You'll need a separate public hostname in Cloudflare for each container + +#### For Applications (via Traefik) + +- In Cloudflare Dashboard, go to your tunnel +- Click **Configure** +- Go to the **Published application routes** tab +- Click **Add a published application route** +- Configure: + - **Subdomain**: Your subdomain (e.g., `app`) + - **Domain**: Your domain (e.g., `example.com`) - Select from dropdown + - **Service**: + - **Type**: HTTP + - **URL**: `dokploy-traefik:80` +- Click **Save** + + + With this setup, Traefik will route the request to the correct application based on the domain you configured in Dokploy's domain settings. + + +**Example:** + +To test this, let's create a minimal app: + +1. Create a simple application +2. Select Docker Provider and set the image name to `nginx` +3. Click on Deploy +4. Go to the Domains tab +5. Create a new domain (Important: make sure to use the same domain you created in Cloudflare dashboard under `Published application routes`) +6. Set the correct port where your application is running (nginx runs on port `80` by default) +7. Don't enable HTTPS toggle or select any certificate provider (this can cause conflicts with Cloudflare SSL) + +#### For Direct Container Access + +If you prefer to bypass Traefik and connect directly to a container: + +- Configure the public hostname with: + - **Service**: + - **Type**: HTTP + - **URL**: `appName:port` (e.g., `dokploy:3000`, `my-app:8080`) + +Note: The app name in Dokploy is shown under the service name, usually formatted as `project-serviceName-hash` + + + When using direct access, you bypass Traefik completely. Domain configurations in Dokploy won't apply, and you'll need to configure each container separately in Cloudflare. + + +### For Wildcard Subdomains (Multiple Apps) + +To support multiple applications/subdomains with a single tunnel configuration: + +**Note:** You need to create a manual CNAME wildcard record in your Cloudflare DNS configuration. + +1. Go to the **Connectors** section and copy the **Tunnel ID** value +2. Go to **DNS Records** of your domain +3. Create a new record: + - **Type**: CNAME + - **Name**: `*` + - **Content**: `your-tunnel-id.cfargotunnel.com` (replace `your-tunnel-id` with the ID you copied) +4. Click Save + +Then, go to the configuration of your tunnel under **Published application routes**: +- Add a public hostname with: + - **Subdomain**: `*` (asterisk for wildcard) + - **Domain**: Your domain (e.g., `example.com`) + - **Service**: + - **Type**: HTTP + - **URL**: `dokploy-traefik:80` + +This allows all subdomains (`app1.example.com`, `app2.example.com`, etc.) to route through Traefik, which then directs traffic to the appropriate container based on your Dokploy domain configurations. + + + With wildcard routing, you only need ONE public hostname in Cloudflare Tunnel. Traefik handles routing to different apps based on the domain configured in Dokploy. + \ No newline at end of file diff --git a/apps/docs/content/docs/core/guides/ec2-instructions.mdx b/apps/docs/content/docs/core/guides/ec2-instructions.mdx new file mode 100644 index 0000000..cee1dea --- /dev/null +++ b/apps/docs/content/docs/core/guides/ec2-instructions.mdx @@ -0,0 +1,86 @@ +--- +title: EC2 Instructions +description: "Instructions for setting up a remote server on EC2" +--- + +import { ImageZoom } from "fumadocs-ui/components/image-zoom"; +import { Callout } from "fumadocs-ui/components/callout"; + +In this guide we will show you how to setup a remote server on AWS EC2 and add an SSH Key on dokploy to connect to the server and start deploying your applications. + +## Requirements + +1. An AWS account +2. A domain that is managed by AWS Route53 + +## 1. Create an SSH Key + + + If you already have an SSH Key you can skip this step and simply go to settings -> SSH Keys and add the SSH Key you have stored on your machine + + +Navigate to Dokploy Settings -> SSH Keys and add a new key + +You will receive a public key and a private key. Copy the public key and save it. + + + +## 2. Create an EC2 Instance + +Login to your AWS account, navigate to EC2 and click on Launch Instance. + +We will then be prompted to select an AMI (Amazon Machine Image) and we will select the Ubuntu Server 22.04 LTS AMI. + +It should like this: + + + +Select the instance type you want to use. For this guide we will use the `t2.micro` instance type which is free tier eligible. + +Now we need to add the SSH Key we created in step 1 to the EC2 instance. + +Click on Security Group and then add a new key pair. + +Add the name of your SSH Key and paste the public key you copied in step 1. + + + +You will have to create a security group that allows SSH (port 22) access from your IP address. and open all HTTP and HTTPS ports for ingress and egress traffic (Port 80 and 443). + + + Opening port 22 to the internet is a security risk. It is recommended to use a bastion host or a VPN to access your EC2 instance securely. + + +Now click on Launch Instance and wait for the instance to be created. + +## 3. Add the Server to Dokploy + +Now that we have the EC2 instance running, we can add it to Dokploy. + +Navigate to Dokploy -> Settings -> Servers and click on Add Server and copy the server IP Address. + +## 4. Setup the Server + +Navigate to Dokploy -> Settings -> Servers -> Setup Server and follow the instructions. + +## 5. Deploy your application + +Now that the server is setup, you can deploy your application to the server. diff --git a/apps/docs/content/docs/core/meta.json b/apps/docs/content/docs/core/meta.json index 0836a75..066d0f3 100644 --- a/apps/docs/content/docs/core/meta.json +++ b/apps/docs/content/docs/core/meta.json @@ -43,9 +43,11 @@ "remote-servers/index", "remote-servers/instructions", "remote-servers/deployments", - "remote-servers/ec2-instructions", "remote-servers/security", "remote-servers/validate", + "---Guides---", + "guides/cloudflare-tunnels", + "guides/ec2-instructions", "---Advanced---", "cluster" ] diff --git a/apps/docs/content/docs/core/remote-servers/ec2-instructions.mdx b/apps/docs/content/docs/core/remote-servers/ec2-instructions.mdx deleted file mode 100644 index 8b5278e..0000000 --- a/apps/docs/content/docs/core/remote-servers/ec2-instructions.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: EC2 Instructions -description: "Instructions for setting up a remote server on EC2" ---- - -When using EC2 instances, by default you don't have root access, and Dokploy needs root access to install the necessary packages without restrictions. - -To do this, you need to make manual modifications to the instance: - -1. **Click on launch instance** - -2. **Select the distribution of your choice** (we recommend Ubuntu, Debian or Amazon Linux) - -3. **Choose your instance type** and all the other settings you want - -4. **In the Network settings**, click on: - - `Allow SSH traffic from the internet` - - `Allow HTTPS traffic from the internet` - - `Allow HTTP traffic from the internet` - -5. **Click on `Launch instance`** (If you see a warning about adding a new key pair, just skip it) - -6. **Now go to your instance and click on `Connect`** - -7. **Type this command** `sudo nano /etc/ssh/sshd_config` and find the line `#PermitRootLogin prohibit-password` and change it to `PermitRootLogin yes`. Save and exit. - -8. **Restart the SSH service** by typing this command: - ```bash - sudo systemctl restart sshd - ``` - -9. **Go back to the EC2 instance and click on `Connect`** but instead of using the default username `ec2-user`, type `root` - -10. **Connect using the `root` user** - -11. **Create a server in the Dokploy dashboard** in the remote server section - -12. **Specify the server details**: - - **IP field**: IPv4 public address of the instance - - **Username field**: `root` - - **SSH key**: Select the SSH key you created earlier - - Click on `Create Server` - -13. **Click on action `Setup Server`** in the `SSH Keys` tab, follow the manual process (Copy the Command and paste in the server manually) - -14. **Connect to the server** - you should now be able to setup the server properly and deploy your applications -