Skip to main content

Public tunnel

A remote development environment runs the PHP webserver on the localhost of a remote machine, which your own browser can't reach. Codespaces, DevPod, a remote Docker host and an SSH dev box all work this way. The tooling can expose the webserver through a Cloudflare quick tunnel, a public *.trycloudflare.com HTTPS URL that needs no account, DNS or configuration. This page covers turning the tunnel on, what it changes and opening the site on a phone.

Anyone with the URL can reach the site

While the tunnel is up, the site is on the public internet. A local Drupal site usually has a known admin account and no firewall. Use disposable test data only, and stop the tunnel with stop when you're done.

Turn on the tunnel​

To turn on the tunnel:

  1. Install cloudflared so it's on your PATH.
  2. Set CLOUDFLARE_TUNNEL=1 in .env or in your shell.
  3. Build the site. On a site you've already built, run start and then provision in place of build.

The following commands set the variable in your shell, then build:

export CLOUDFLARE_TUNNEL=1
make build

Confirm that the tunnel is up: provision prints a *.trycloudflare.com address as the site URL, and info prints the same address.

The tunnel stays off for an empty value and for 0, false, no and off, in any letter case. Any other value, such as 1, turns it on. A value in your shell wins over .env. An empty shell value counts as unset, so .env decides. To override a .env that turns the tunnel on, set 0, false, no or off in your shell. For a single command, prefix it, such as CLOUDFLARE_TUNNEL=0 make start.

What happens​

The tunnel changes what these commands do:

  • start starts a tunnel and writes its URL to .env as TUNNEL_URL. It reuses a running tunnel that forwards to the same port and whose URL still answers. Without cloudflared, or when no URL appears within 30 seconds, start carries on without the tunnel and says so.
  • provision adds the reverse-proxy and trusted-host settings that Drupal needs behind the tunnel to settings.php.
  • start, provision, info, drush and login use the tunnel URL as the site URL.
  • stop closes the tunnel and removes its URL from .env, even while CLOUDFLARE_TUNNEL is off. It leaves CLOUDFLARE_TUNNEL as it is. reset closes it too, and so does assemble when it stops a running webserver.

After you turn CLOUDFLARE_TUNNEL off, a running tunnel stays up, and the site public, until the next stop. To close the tunnel, run the following command:

make stop

When a tunnel doesn't come up, read .logs/cloudflared.log in the project root, where cloudflared writes its output.

Bring your own tunnel​

The commands treat any TUNNEL_URL in .env as the site URL, whichever tool wrote it. To use a different tunnel, such as ngrok, start it from a lifecycle script like scripts/start-ngrok.sh and write its URL to .env. Keep CLOUDFLARE_TUNNEL off. With it on, provision adds trusted-host settings that accept only the Cloudflare and local hosts. 2 things work only with the Cloudflare tunnel:

  • provision adds its settings.php entries for a Cloudflare tunnel only. Behind another tunnel, add the settings that tunnel needs to settings.php yourself, such as reverse_proxy, so Drupal detects HTTPS.
  • stop removes only a *.trycloudflare.com URL from .env, so remove your tunnel's URL from a stop-*.sh script.

Open the site on a phone​

vendor/bin/eddy-qrcode <url> draws any URL as a QR code in the terminal, so you can open the URL by scanning the code with a phone. It needs qrencode on PATH. To draw the site URL, run the following command:

vendor/bin/eddy-qrcode "$(vendor/bin/eddy-info site-url)"

To have login draw the one-time login link as a QR code too, set LOGIN_QRCODE=1 in .env or your shell (see Log in).