A step-by-step guide for breaking free from ISP limitations and accessing your home services from anywhere.

"In a world where ISPs block your ports and routers deny your dreams, one Pi rises above the limitations..." 🎬

The Problem: ISP Lockdown 🔒

So you've got a shiny Raspberry Pi and a bunch of cool ideas for self-hosted services, but there's one big problem: your ISP won't give you a static IP, and your router doesn't let you open ports! Sound familiar?

It's like having a fabulous party venue but the door is welded shut. You're inside yelling "Come to my party!" but nobody outside can hear you. Your Raspberry Pi is throwing the most amazing digital party ever, but the ISP bouncer won't let any guests in!

This is a common roadblock for homelab enthusiasts, but don't worry - I've got a solution that's both elegant and powerful. We're going to build a secret tunnel! 🕵️‍♂️

The Solution: Cloud + VPN = Freedom 🚀

Here's our game plan in a nutshell:

1. Rent a tiny cloud server with a public IP

2. Set up WireGuard VPN on both the cloud server and Raspberry Pi

3. Forward traffic from your cloud server to your Pi

4. Access your Pi's services from anywhere in the world!

Let's get started!

Prerequisites

• A Raspberry Pi running Raspberry Pi OS (or any Linux distro)

• A small cloud server (Ubuntu/Debian recommended)

• Docker and Docker Compose installed on both machines

• Basic Linux command line knowledge

Part 1: Setting Up the Cloud Server 🌩️

First, let's prepare the cloud server to act as our WireGuard VPN server and internet-facing gateway.

Step 1: Create the Project Directory

# Log into your cloud server
ssh user@your-cloud-server

# Create a directory for our project
mkdir -p ~/wireguard_server
cd ~/wireguard_server

Step 2: Create the Docker Compose File

Create a new file called docker-compose.yml:

nano docker-compose.yml

Add the following content:

services:
  wireguard:
    image: lscr.io/linuxserver/wireguard:latest
    container_name: wireguard_server
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - SERVERURL=auto  # Auto-detects your server's public IP
      - SERVERPORT=51820
      - PEERS=raspberrypi  # Name of your Raspberry Pi client
      - PEERDNS=auto
      - INTERNAL_SUBNET=10.13.13.0
      - ALLOWEDIPS=0.0.0.0/0
      - LOG_CONFS=true
      - PERSISTENTKEEPALIVE_PEERS=all
    volumes:
      - ./wireguard-data:/config
      - /lib/modules:/lib/modules
    ports:
      - 51820:51820/udp
      # Ports you want to forward to your Raspberry Pi
      - 80:80    # HTTP
      - 443:443  # HTTPS
      # Add more ports as needed for your services
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv4.ip_forward=1
    restart: unless-stopped

Step 3: Start the WireGuard Server

docker compose up -d

This command starts the WireGuard server in detached mode. The first time you run it, it will:

• Download the WireGuard Docker image

• Create configuration files

• Generate encryption keys

• Create a client configuration for your Raspberry Pi

Step 4: Check the Logs

Let's make sure everything started correctly:

docker compose logs

If all went well, you should see something like "WireGuard started" in the logs. You should also see QR codes for your Raspberry Pi client configuration (we won't need these).

Step 5: Add Port Forwarding (Optional but Recommended)

The WireGuard container already added some basic routing rules, but let's double-check the configuration file:

cat wireguard-data/wg_confs/wg0.conf

You should see something like this in the [Interface] section:

PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth+ -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth+ -j MASQUERADE

These rules allow general traffic forwarding. We need to forward specific ports (like 80 and 443), add these additional lines to the [Interface] section:

# Open the config file for editing
nano wireguard-data/wg_confs/wg0.conf

Add these lines after the existing PostUp/PostDown rules:

PostUp = iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80; iptables -t nat -A PREROUTING -p tcp --dport 443 -j DNAT --to-destination 10.13.13.2:443
PostDown = iptables -t nat -D PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80; iptables -t nat -D PREROUTING -p tcp --dport 443 -j DNAT --to-destination 10.13.13.2:443

Your wg0.conf should look like this now.

[Interface]
Address = 10.13.13.1
ListenPort = 51820
PrivateKey = <some private key>
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth+ -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth+ -j MASQUERADE
PostUp = iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80; iptables -t nat -A PREROUTING -p tcp --dport 443 -j DNAT --to-destination 10.13.13.2:443
PostDown = iptables -t nat -D PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80; iptables -t nat -D PREROUTING -p tcp --dport 443 -j DNAT --to-destination 10.13.13.2:443

[Peer]
# peer_raspberrypi
PublicKey = au4RPHqjiyok5jf76hCS+eK5tzLlOn84PbaIiTU69XE=
PresharedKey = <some private key>
AllowedIPs = 10.13.13.2/32
PersistentKeepalive = 25

Save the file and restart the container:

docker compose restart

Step 6: Find the Raspberry Pi Client Configuration

The WireGuard container generated a configuration file for your Raspberry Pi. This file contains everything needed to connect to the VPN:

cat wireguard-data/peer_raspberrypi/peer_raspberrypi.conf

You'll need to copy this file to your Raspberry Pi in the next part. Just create a new file and copy-paste the contents.

Part 2: Setting Up the Raspberry Pi 🥧

Now let's set up your Raspberry Pi as a WireGuard client.

Step 1: Create the Project Directory

# Create a directory for our project
mkdir -p ~/wireguard_client
cd ~/wireguard_client

Step 2: Create the Docker Compose File

Create a new file called docker-compose.yml:

nano docker-compose.yml

Add the following content:

services:
  wireguard:
    image: lscr.io/linuxserver/wireguard:latest
    container_name: wireguard_client
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
    volumes:
      - ./wireguard-client-data:/config
      - /lib/modules:/lib/modules
    restart: unless-stopped
    network_mode: "host"  # Makes VPN connection available to other containers

Step 3: Create the Client Configuration Directory

mkdir -p wireguard-client-data/wg_confs

Step 4: Copy the Client Configuration File

Create the WireGuard client configuration file:

nano wireguard-client-data/wg_confs/wg0.conf

Copy and paste the contents from the peer_raspberrypi.conf file we found on the cloud server.

Make sure to add PersistentKeepalive = 25 to the conf in the interface for connection to be persistent.

the w0.conf on pi should look like the following:

[Interface]
Address = 10.13.13.2
PrivateKey = <some key>
ListenPort = 51820
DNS = 10.13.13.1

[Peer]
PublicKey = <some key>
PresharedKey = <some key>
Endpoint = <public ip of you cloud server>:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Step 5: Set Up System Requirements

Before starting the WireGuard client, we need to set a special system parameter as we are using the host docker networking:

# Set the parameter immediately
sudo sysctl -w net.ipv4.conf.all.src_valid_mark=1

# Make it persistent across reboots
echo "net.ipv4.conf.all.src_valid_mark = 1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Wait, what does this parameter do? 🤔

This parameter (net.ipv4.conf.all.src_valid_mark=1) is needed for WireGuard's magic to work properly. It enables packet marking and routing based on those marks, which is how WireGuard knows which packets should go through the VPN tunnel and which shouldn't.

Think of it as putting special invisible stickers on your internet packets so your computer knows which door they should use to exit - the regular internet door or the secret VPN tunnel door. Without this setting, those stickers won't stick, and your packets will get confused about where to go!

Step 6: Start the WireGuard Client

docker compose up -d

Time for the test

On your pi, try pinging the server

ping -c 4 10.13.13.1

It seems to work. You can try doing the same from the server.

docker exec -it wireguard_server ping -c 10.13.13.2

Houston, We Have a Problem! 🚨

Now you try to pull a Docker image on your pi, and...

docker run hello-world

Error:

Unable to find image 'hello-world:latest' locally
docker: Error response from daemon: Get "https://registry-1.docker.io/v2/": 
dial tcp 44.208.254.194:443: connect: connection refused

# Or some similar timeout issue.

What's happening? When you stop WireGuard, it works fine. What's going on?

The Mystery Explained: 🕵️‍♂️

Remember how we set up WireGuard with ALLOWEDIPS=0.0.0.0/0 on the server and the client configuration has AllowedIPs = 0.0.0.0/0? That innocent-looking setting is actually saying "send ALL internet traffic through the VPN tunnel."

So when your Raspberry Pi tries to talk to Docker Hub, instead of going straight to the internet, the conversation goes like this:

1. Pi: "Hey Docker Hub, send me that hello-world image!"

2. WireGuard: "YOINK! I'll take that request!" sends it through the tunnel

3. Cloud Server: "What's this? A request to Docker Hub? Hmm, I don't know how to handle this properly...(this requires additional setup, which is beyond the scope of this blog)"

4. request fails

It's like asking your friend to deliver a message to someone across the street, but your friend can only talk to people in their own house! When you turn off WireGuard, your Pi talks directly to Docker Hub - no middleman needed.

The Split Tunneling Solution 🔀

The problem is that our WireGuard configuration is routing ALL traffic through the VPN tunnel. That's why Docker can't connect to the Docker Hub - it's trying to go through our cloud server instead of directly to the internet.

Let's fix this with "split tunneling" - a technique that lets us selectively choose what traffic goes through the VPN. It's like having two roads from your house: a private tunnel for secret messages and the regular highway for everyday errands. We don't need to send our grocery shopping through the secret tunnel!

Step 1: Stop the WireGuard Client

cd ~/wireguard_client
docker compose down

Step 2: Update the Client Configuration

Edit the WireGuard client configuration:

nano wireguard-client-data/wg_confs/wg0.conf

Find the AllowedIPs line in the [Peer] section and change it from:

AllowedIPs = 0.0.0.0/0

To:

AllowedIPs = 10.13.13.0/24

This line change tells WireGuard: "Hey buddy, only send traffic to the 10.13.13.0/24 network through the tunnel. Let everything else go the normal way!"

It's like telling your mail carrier: "Only deliver the secret love letters through the hidden tunnel, but send my Amazon packages and bills the regular way." This way, your Raspberry Pi can talk directly to Docker Hub and the rest of the internet, while still maintaining its special connection to your cloud server.

Step 3: Restart the WireGuard Client

docker compose up -d

Step 4: Test the Connection

Try pulling a Docker image again:

docker run hello-world

Success! You should see the "Hello World" message. Now let's make sure we can still reach our cloud server:

ping 10.13.13.1

If this works, congratulations! You've set up split tunneling correctly.

Part 3: Running Your Services 🚢

Now that our VPN tunnel is established, let's set up some services on the Raspberry Pi. We will run a simple webserver image to test.

docker run -p 80:80 -d nginxdemos/hello

Part 4: Testing Access from the Internet 🌐

Now for the exciting part - accessing your Raspberry Pi services from anywhere!

1. Open a web browser on any device

2. Enter your cloud server's public IP address

3. You should see the website.

If this works, congratulations! Your traffic is flowing: Internet → Cloud Server → VPN → Raspberry Pi → Service → back through the same path to your browser.

Bonus: The Magic Behind the Curtain: Understanding iptables in Our WireGuard VPN Setup 🧙‍♂️

When setting up our WireGuard VPN to bypass ISP limitations, we employed some powerful iptables magic to enable our cloud server to forward traffic to our Raspberry Pi. Let's dive into what makes this work!

What Are PostUp and PostDown? 🚀

In our WireGuard configuration, we added these special commands:

PostUp = iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80; iptables -t nat -A PREROUTING -p tcp --dport 443 -j DNAT --to-destination 10.13.13.2:443
PostDown = iptables -t nat -D PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80; iptables -t nat -D PREROUTING -p tcp --dport 443 -j DNAT --to-destination 10.13.13.2:443

Think of these as "setup" and "cleanup" instructions:

• PostUp: "Hey system, once the VPN tunnel is UP and running, please set up these traffic routing rules!"

• PostDown: "When the VPN tunnel is shutting DOWN, please clean up those routing rules so we don't leave a mess."

The Traffic Director Analogy 🚦

Imagine your cloud server is a traffic director standing at a busy intersection. When someone comes looking for web content (port 80) or secure web content (port 443), our iptables rules act like special instructions to this traffic director.

PREROUTING: The Initial Greeting

When traffic arrives, the PREROUTING chain is like the traffic director's first action:

-A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80

Traffic director: "Oh, you're looking for website content on port 80? Don't stop here! Go straight down this secret tunnel to address 10.13.13.2, that's where the real website lives!"

The -j DNAT part is like the traffic director pulling out a special map and saying "Here's the actual destination you want!"

Breaking Down the iptables Spell 🧪

iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 10.13.13.2:80

• iptables: The Linux firewall/packet manipulation tool

• -t nat: We're working with the Network Address Translation table

• -A PREROUTING: Add a rule to the PREROUTING chain (processes packets as soon as they arrive)

• -p tcp: This rule applies to TCP protocol traffic

• --dport 80: Match packets destined for port 80 (HTTP)

• -j DNAT: Jump to the Destination NAT action

• --to-destination 10.13.13.2:80: Change the destination to our Raspberry Pi's VPN IP and port

What About the Alternatives?

We could have used other options, but each has drawbacks:

• socat or netcat: These tools can redirect ports, but they run as user processes rather than kernel-level operations, making them less efficient for constant traffic.

• nginx/haproxy: Great for HTTP/HTTPS traffic forwarding, but overkill for our needs and would require additional setup and maintenance.

Conclusion: You're Now a WireGuard Hero! 🦸‍♂️

"With great power comes great responsibility..." And you now have the POWER!

You've successfully:

• Set up a WireGuard VPN between a cloud server and your Raspberry Pi

• Configured split tunneling for optimal routing (you traffic wizard, you!)

• Made your Raspberry Pi services accessible from anywhere (take THAT, restrictive ISP!)

• Added HTTPS for secure access (because safety first, even for rebels)

The best part? This solution costs just a few dollars per month for the cloud server, and you're now free from the limitations of consumer ISPs and routers. Your Raspberry Pi has broken free from its digital prison and can now share its awesomeness with the entire internet!

Remember the days when you couldn't access your Pi from outside your home? Those dark days are over! You've seen the light, and it's shaped like a tunnel... a WireGuard tunnel!

Happy self-hosting, you magnificent network ninja! 🥷

Troubleshooting 🔧

Can't connect to the VPN?

• Check your cloud server's firewall (allow UDP port 51820)

• Ensure your WireGuard configurations have the correct public keys

• Check logs with docker compose logs

Services accessible but slow?

• Your cloud server might be far from you geographically

• Try a cloud provider with servers closer to your location

Want to add more services?

• Update port forwarding rules in your cloud server's wg0.conf

• Restart both WireGuard containers

---

Was this guide helpful? Let me know in the comments!