mirror of
https://github.com/therealaleph/MasterHttpRelayVPN-RUST.git
synced 2026-05-18 06:34:41 +03:00
docs: add GitHub Actions Full tunnel documentation and workflows (#783)
* docs: add GitHub Actions tunnel general documentation README.md * docs: add cloudflared quick tunnel guide * Add: add cloudflared quick tunnel workflow * docs: add ngrok tunnel guide * Add: add ngrok tunnel workflow * fix: Update cloudflared-quick.md to add link to related yml file * fix: Update ngrok.md to add related file link * docs: add cloudflared named tunnel guide * Add: add cloudflared named workflow
This commit is contained in:
Euvel
@@ -0,0 +1,187 @@
|
||||
# cloudflared Named Tunnel
|
||||
|
||||
Run a Full tunnel with a **permanent, unchanging URL** using a Cloudflare
|
||||
account and a custom domain. The tunnel URL never changes between restarts —
|
||||
configure `CodeFull.gs` once and only re-trigger the workflow when needed.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A GitHub account (free)
|
||||
- A Cloudflare account with a domain
|
||||
- `cloudflared` installed on your local machine for one-time setup
|
||||
- `CodeFull.gs` deployed as a Google Apps Script Web App
|
||||
|
||||
## One-Time Local Setup
|
||||
|
||||
These steps are performed **once** on your local machine. They create a named
|
||||
tunnel on Cloudflare and route your domain to it.
|
||||
|
||||
### Step 1: Install cloudflared
|
||||
|
||||
**Linux (Debian/Ubuntu):**
|
||||
```bash
|
||||
curl -L --output cloudflared.deb \
|
||||
https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
|
||||
sudo dpkg -i cloudflared.deb
|
||||
```
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
brew install cloudflared
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
Download the installer from the [cloudflared releases page](https://github.com/cloudflare/cloudflared/releases).
|
||||
|
||||
### Step 2: Authenticate with Cloudflare
|
||||
|
||||
```bash
|
||||
cloudflared tunnel login
|
||||
```
|
||||
|
||||
This opens a browser window. Select your domain and authorize.
|
||||
|
||||
### Step 3: Create a Named Tunnel
|
||||
|
||||
```bash
|
||||
cloudflared tunnel create my-tunnel
|
||||
```
|
||||
|
||||
This outputs a tunnel ID (a UUID) and creates a credentials file at:
|
||||
```
|
||||
~/.cloudflared/<TUNNEL_ID>.json
|
||||
```
|
||||
|
||||
Copy the tunnel ID — you will need it later.
|
||||
|
||||
### Step 4: Route Your Domain
|
||||
|
||||
```bash
|
||||
cloudflared tunnel route dns my-tunnel tunnel.yourdomain.com
|
||||
```
|
||||
|
||||
Replace `tunnel.yourdomain.com` with the actual subdomain you want to use.
|
||||
This creates a DNS record on Cloudflare pointing to your tunnel.
|
||||
|
||||
### Step 5: Get the Credentials File
|
||||
|
||||
```bash
|
||||
cat ~/.cloudflared/<TUNNEL_ID>.json
|
||||
```
|
||||
|
||||
Copy the entire JSON output. You will use this as the
|
||||
`CLOUDFLARE_TUNNEL_CREDENTIALS` secret in GitHub Actions.
|
||||
|
||||
## GitHub Setup
|
||||
|
||||
### Step 6: Create the Repository
|
||||
|
||||
If you already have a repository from another method, you can reuse it.
|
||||
Otherwise:
|
||||
|
||||
1. Go to [github.com](https://github.com) and sign in
|
||||
2. Click the **+** icon in the top-right corner, then **New repository**
|
||||
3. Enter a repository name (e.g., `my-tunnel`)
|
||||
4. Select **Private** (recommended — keeps your secrets secure)
|
||||
5. Click **Create repository**
|
||||
|
||||
### Step 7: Add the Secrets
|
||||
|
||||
1. In your repository, go to **Settings > Secrets and variables > Actions**
|
||||
2. Click **New repository secret** and add each of the following:
|
||||
|
||||
| Name | Value |
|
||||
|---|---|
|
||||
| `TUNNEL_AUTH_KEY` | A strong password. You will also set this in `CodeFull.gs`. |
|
||||
| `CLOUDFLARE_TUNNEL_ID` | The tunnel ID from Step 3. |
|
||||
| `CLOUDFLARE_TUNNEL_HOSTNAME` | The subdomain you configured in Step 4 (e.g., `tunnel.yourdomain.com`). |
|
||||
| `CLOUDFLARE_TUNNEL_CREDENTIALS` | The entire JSON contents of the credentials file from Step 5. |
|
||||
|
||||
3. Click **Add secret** for each
|
||||
|
||||
### Step 8: Add the Workflow
|
||||
|
||||
1. In your repository, go to the **Actions** tab
|
||||
2. Click **New workflow**
|
||||
3. Click the **set up a workflow yourself** link
|
||||
4. Delete the default content and paste the contents of `cloudflared-named.yml` [[here]]
|
||||
5. Click **Commit changes...**, add a commit message, then click **Commit changes**
|
||||
|
||||
The workflow file will be saved to `.github/workflows/cloudflared-named.yml`.
|
||||
|
||||
### Step 9: Run the Workflow
|
||||
|
||||
1. Go to the **Actions** tab
|
||||
2. Select **Full Tunnel (cloudflared Named)** from the left sidebar
|
||||
3. Click **Run workflow > Run workflow**
|
||||
|
||||
The workflow will start immediately.
|
||||
|
||||
### Step 10: Configure CodeFull.gs
|
||||
|
||||
Open `CodeFull.gs` in the Google Apps Script editor and update these constants:
|
||||
|
||||
```javascript
|
||||
const TUNNEL_SERVER_URL = "https://tunnel.yourdomain.com";
|
||||
const TUNNEL_AUTH_KEY = "the-secret-you-set-in-step-7";
|
||||
```
|
||||
|
||||
Deploy: **Deploy > New Deployment > Web App**.
|
||||
Copy the new Deployment ID and update your `mhrv-rs` config.
|
||||
|
||||
**This step is performed only once.** The tunnel URL never changes between
|
||||
restarts.
|
||||
|
||||
### Step 11: Verify
|
||||
|
||||
Use `mhrv-rs test` or visit `https://ipleak.net` through your proxy.
|
||||
You should see a Cloudflare IP address.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. GitHub Actions starts a Docker container running `mhrv-tunnel-node` on port
|
||||
`8080`
|
||||
2. `cloudflared` connects to Cloudflare using the named tunnel credentials
|
||||
3. Cloudflare routes traffic from your custom domain to the runner through a
|
||||
secure, persistent tunnel
|
||||
4. `CodeFull.gs` forwards tunnel operations to your custom domain over HTTPS
|
||||
5. The runner stays alive for 6 hours, then shuts down automatically
|
||||
6. On restart, the same domain routes to the new runner — no configuration
|
||||
changes needed
|
||||
|
||||
## Restarting the Tunnel
|
||||
|
||||
The tunnel shuts down after 6 hours. To start a new session:
|
||||
|
||||
1. Go to the **Actions** tab
|
||||
2. Select **Full Tunnel (cloudflared Named)**
|
||||
3. Click **Run workflow > Run workflow**
|
||||
|
||||
That is all — the URL is permanent so `CodeFull.gs` does not need to be updated.
|
||||
|
||||
For automatic restarts every 6 hours, add a `schedule` trigger to the workflow:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
workflow_dispatch:
|
||||
schedule:
|
||||
- cron: '0 */6 * * *'
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- Requires a one-time local setup with `cloudflared` CLI
|
||||
- Requires a Cloudflare account with a domain
|
||||
- 6-hour maximum per session (GitHub Actions limit)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| `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. |
|
||||
| `cloudflared tunnel create` fails | Verify you are authenticated. Run `cloudflared tunnel login` again. |
|
||||
| Workflow fails at Docker step | GitHub Actions may be pulling the image for the first time. Wait 2-3 minutes and retry. |
|
||||
| `cloudflared` fails to connect | Verify all four secrets are set correctly. Check that `CLOUDFLARE_TUNNEL_CREDENTIALS` contains valid JSON. |
|
||||
| `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. |
|
||||
|
||||
[here]: cloudflared-named.yml
|
||||
Reference in New Issue
Block a user