Skip to content

Commit bb285f8

Browse files
euveleuvel
authored
docs: add cloudflared named tunnel guide
1 parent 84534a2 commit bb285f8

1 file changed

Lines changed: 187 additions & 0 deletions

File tree

‎assets/github-actions-tunnel/cloudflared-named.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# cloudflared Named Tunnel
2+
3+
Run a Full tunnel with a **permanent, unchanging URL** using a Cloudflare
4+
account and a custom domain. The tunnel URL never changes between restarts —
5+
configure `CodeFull.gs` once and only re-trigger the workflow when needed.
6+
7+
## Prerequisites
8+
9+
- A GitHub account (free)
10+
- A Cloudflare account with a domain
11+
- `cloudflared` installed on your local machine for one-time setup
12+
- `CodeFull.gs` deployed as a Google Apps Script Web App
13+
14+
## One-Time Local Setup
15+
16+
These steps are performed **once** on your local machine. They create a named
17+
tunnel on Cloudflare and route your domain to it.
18+
19+
### Step 1: Install cloudflared
20+
21+
**Linux (Debian/Ubuntu):**
22+
```bash
23+
curl -L --output cloudflared.deb \
24+
https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
25+
sudo dpkg -i cloudflared.deb
26+
```
27+
28+
**macOS:**
29+
```bash
30+
brew install cloudflared
31+
```
32+
33+
**Windows:**
34+
Download the installer from the [cloudflared releases page](https://github.com/cloudflare/cloudflared/releases).
35+
36+
### Step 2: Authenticate with Cloudflare
37+
38+
```bash
39+
cloudflared tunnel login
40+
```
41+
42+
This opens a browser window. Select your domain and authorize.
43+
44+
### Step 3: Create a Named Tunnel
45+
46+
```bash
47+
cloudflared tunnel create my-tunnel
48+
```
49+
50+
This outputs a tunnel ID (a UUID) and creates a credentials file at:
51+
```
52+
~/.cloudflared/<TUNNEL_ID>.json
53+
```
54+
55+
Copy the tunnel ID — you will need it later.
56+
57+
### Step 4: Route Your Domain
58+
59+
```bash
60+
cloudflared tunnel route dns my-tunnel tunnel.yourdomain.com
61+
```
62+
63+
Replace `tunnel.yourdomain.com` with the actual subdomain you want to use.
64+
This creates a DNS record on Cloudflare pointing to your tunnel.
65+
66+
### Step 5: Get the Credentials File
67+
68+
```bash
69+
cat ~/.cloudflared/<TUNNEL_ID>.json
70+
```
71+
72+
Copy the entire JSON output. You will use this as the
73+
`CLOUDFLARE_TUNNEL_CREDENTIALS` secret in GitHub Actions.
74+
75+
## GitHub Setup
76+
77+
### Step 6: Create the Repository
78+
79+
If you already have a repository from another method, you can reuse it.
80+
Otherwise:
81+
82+
1. Go to [github.com](https://github.com) and sign in
83+
2. Click the **+** icon in the top-right corner, then **New repository**
84+
3. Enter a repository name (e.g., `my-tunnel`)
85+
4. Select **Private** (recommended — keeps your secrets secure)
86+
5. Click **Create repository**
87+
88+
### Step 7: Add the Secrets
89+
90+
1. In your repository, go to **Settings > Secrets and variables > Actions**
91+
2. Click **New repository secret** and add each of the following:
92+
93+
| Name | Value |
94+
|---|---|
95+
| `TUNNEL_AUTH_KEY` | A strong password. You will also set this in `CodeFull.gs`. |
96+
| `CLOUDFLARE_TUNNEL_ID` | The tunnel ID from Step 3. |
97+
| `CLOUDFLARE_TUNNEL_HOSTNAME` | The subdomain you configured in Step 4 (e.g., `tunnel.yourdomain.com`). |
98+
| `CLOUDFLARE_TUNNEL_CREDENTIALS` | The entire JSON contents of the credentials file from Step 5. |
99+
100+
3. Click **Add secret** for each
101+
102+
### Step 8: Add the Workflow
103+
104+
1. In your repository, go to the **Actions** tab
105+
2. Click **New workflow**
106+
3. Click the **set up a workflow yourself** link
107+
4. Delete the default content and paste the contents of `cloudflared-named.yml` [[here]]
108+
5. Click **Commit changes...**, add a commit message, then click **Commit changes**
109+
110+
The workflow file will be saved to `.github/workflows/cloudflared-named.yml`.
111+
112+
### Step 9: Run the Workflow
113+
114+
1. Go to the **Actions** tab
115+
2. Select **Full Tunnel (cloudflared Named)** from the left sidebar
116+
3. Click **Run workflow > Run workflow**
117+
118+
The workflow will start immediately.
119+
120+
### Step 10: Configure CodeFull.gs
121+
122+
Open `CodeFull.gs` in the Google Apps Script editor and update these constants:
123+
124+
```javascript
125+
const TUNNEL_SERVER_URL = "https://tunnel.yourdomain.com";
126+
const TUNNEL_AUTH_KEY = "the-secret-you-set-in-step-7";
127+
```
128+
129+
Deploy: **Deploy > New Deployment > Web App**.
130+
Copy the new Deployment ID and update your `mhrv-rs` config.
131+
132+
**This step is performed only once.** The tunnel URL never changes between
133+
restarts.
134+
135+
### Step 11: Verify
136+
137+
Use `mhrv-rs test` or visit `https://ipleak.net` through your proxy.
138+
You should see a Cloudflare IP address.
139+
140+
## How It Works
141+
142+
1. GitHub Actions starts a Docker container running `mhrv-tunnel-node` on port
143+
`8080`
144+
2. `cloudflared` connects to Cloudflare using the named tunnel credentials
145+
3. Cloudflare routes traffic from your custom domain to the runner through a
146+
secure, persistent tunnel
147+
4. `CodeFull.gs` forwards tunnel operations to your custom domain over HTTPS
148+
5. The runner stays alive for 6 hours, then shuts down automatically
149+
6. On restart, the same domain routes to the new runner — no configuration
150+
changes needed
151+
152+
## Restarting the Tunnel
153+
154+
The tunnel shuts down after 6 hours. To start a new session:
155+
156+
1. Go to the **Actions** tab
157+
2. Select **Full Tunnel (cloudflared Named)**
158+
3. Click **Run workflow > Run workflow**
159+
160+
That is all — the URL is permanent so `CodeFull.gs` does not need to be updated.
161+
162+
For automatic restarts every 6 hours, add a `schedule` trigger to the workflow:
163+
164+
```yaml
165+
on:
166+
workflow_dispatch:
167+
schedule:
168+
- cron: '0 */6 * * *'
169+
```
170+
171+
## Limitations
172+
173+
- Requires a one-time local setup with `cloudflared` CLI
174+
- Requires a Cloudflare account with a domain
175+
- 6-hour maximum per session (GitHub Actions limit)
176+
177+
## Troubleshooting
178+
179+
| Problem | Solution |
180+
|---|---|
181+
| `cloudflared tunnel login` fails | Ensure your browser can reach `dash.cloudflare.com`. You may need to use a proxy or alternative network for this step. |
182+
| `cloudflared tunnel create` fails | Verify you are authenticated. Run `cloudflared tunnel login` again. |
183+
| Workflow fails at Docker step | GitHub Actions may be pulling the image for the first time. Wait 2-3 minutes and retry. |
184+
| `cloudflared` fails to connect | Verify all four secrets are set correctly. Check that `CLOUDFLARE_TUNNEL_CREDENTIALS` contains valid JSON. |
185+
| `CodeFull.gs` returns 502 or timeout | Verify the workflow is still running. Check that `TUNNEL_AUTH_KEY` matches in both the secret and `CodeFull.gs`. Ensure the DNS record was created in Step 4. |
186+
187+
[here]: cloudflared-named.yml

0 commit comments

Comments
 (0)