If you need to expose a service running on a balenaCloud device to a public URL, this guide is for you. While balenaCloud offers a built-in service —public device URL— that’s great for development, it may not suit advanced use cases such as HTTPS pass-through, custom domain names, arbitrary ports, or alternate protocols. In this tutorial, we’ll walk through the process of using Cloudflare Tunnel, which allows more advanced configurations (to make your service accessible on the internet).

By following these steps, you’ll ensure your service is secure and easily reachable. Whether you’re experienced with IoT projects or just starting your IoT journey, this guide will help you set up a Cloudflare Tunnel in just a few minutes. Let’s get started!

Requirements

• A balenaCloud account with a deployed device.
• BalenaCli installed on your development machine.
• A Cloudflare account, if you don’t have one, sign up for a free one.
• A domain configured within your Cloudflare account.

Let’s create our first tunnel

• On your Cloudflare account, go to Zero Trust -> Networks -> Tunnels
• Click on the “create a tunnel” button
• Select cloudflared as your connector and click next
• Give a name to your tunnel. I’ll go with balena-demo-tunnel

• Select Docker as your environment
• Copy the command to install and run a connector (keep the token somewhere, we’ll need it in a minute)

• Click on next
• For the Public hostname
  • Select your custom domain for Domain
  • Add an optional path or a subdomain to access your service
• For the Service
  • Select HTTP as the Type (you can use other protocol depending on your use case)
  • Add the internal URL for the service, in our case webserver (if the service was on another port, e.g.. 3000 we would have added now as webserver:3000)
• Click Save tunnel

If you want to connect multiple services, you can edit your tunnel, go to Public hostname and add another one pointing to your other service (or another port of the same service).

• Now exit Zero Trust and go back to Websites -> *your custom domain* -> SSL -> Edge Certificates and turn ON Always Use HTTPS. This will prevent your services from being accessible as unencrypted traffic.

Create your composition

Open your favorite code editor in a brand new folder

• Create a docker-compose.yml
• Add your services:

version: '2'

networks:
  tunnel:

services:
  webserver:
    image: nginx
    networks:
      - tunnel

  cloudflared:
    image: cloudflare/cloudflared:latest
    command:
      tunnel --no-autoupdate run
    environment:
      - TUNNEL_TOKEN=*yourTokenHere*
    networks:
      - tunnel  

• Push the composition to the device using the balena-cli: balena push *orgname/fleetname* (or the device’s local name if you are running in local mode)

What did we do in that composition?

We created a new custom bridge network named tunnel to link our services together (you can choose any name you want).

On the custom bridge network:

• Services are behind a NAT firewall (they’re not accessible, but they can access the local network and the internet)
• Services use an internal DNS that resolves the other services on the network by their name (i.e. webserver from cloudflared); that’s what we use to configure our tunnel on Cloudflare
  If you want to also expose the webserver on the local network, you can do so by exposing the ports as usual
• We create a webserver that will publish a (default) web page on port 80
• We create a cloudflared service using the official docker image from Cloudflare, passing the token as an environment variable

Setting the TUNNEL_TOKEN env variable in the composition is fine for local mode and single-device development, but you will want to set it using balenaCloud device dashboard (Device Variables) at some point. When you do so, scope it to the cloudflared service and remove it from your composition.

Test

Once your composition is built and deployed to your device; the tunnel should be connected.

Open a new tab and visit your domain (with the optional subdomain and/or path).

Troubleshooting

To check the status of your tunnel, go to the Cloudflare dashboard: Zero Trust -> Networks -> Tunnels and click on your Connector. There, you can see the status; and you can click Begin log stream to see what’s happening on your tunnel.

Extra security

If your tunneled service doesn’t require internet connectivity (i.e. it doesn’t need to fetch any external resource), we can further isolate it using an internal network configuration.

The composition becomes:

version: '2'

networks:
  tunnel:
    internal: true
  external:

services:
  webserver:
    image: nginx
    networks:
      - tunnel

  cloudflared:
    image: cloudflare/cloudflared:latest
    command:
      tunnel --no-autoupdate run 
    environment:
      - TUNEL_TOKEN=*yourTokenHere*
    networks:
      - tunnel
      - external

Here we’ve created two networks:

• tunnel is internal, meaning it connects our services but doesn’t allow connections to other networks. Essentially, all traffic in and out is blocked for both public internet and local networks.
• external is another normal bridge, which allows services to reach the local network and public internet. It’s necessary for cloudflared to connect to Cloudflare servers.

Scaling

If you have many devices to tunnel to, manually creating a tunnel and setting up the token might quickly become a chore. You can leverage both balenaCloud and Cloudflare API to automate the process as part of your provisioning flow.

Note: At the time of writing, Cloudflare tunnels are limited to 1000 tunnels per account.

Going further

In this tutorial, we examined in detail how to use Cloudflare Tunnel as an alternative to balena’s Public URL feature in circumstances when you need non-basic functionality. Keep in mind that Cloudflare Tunnel is merely one provider of these services, you can find a list of self-hosted and commercial offerings at anderspitman/awesome-tunneling Github repo.

Let us know in the comments if you’ve used an alternative such as this to access your device’s services. We’d also be interested to learn about your use case that necessitates these advanced techniques. As always, feel free to get in touch with us at hello@balena.io or in our forums!

The post How to expose your device with a custom URL using Cloudflare Tunnels appeared first on balena Blog.