Complete Guide: Running Two Pangolin Instances Together (VPS + Local)

Networking
1

Complete Guide: Running Two Pangolin Instances Together (VPS + Local)

image
image1502×919 70 KB

image
image1723×952 72.1 KB

image
image1717×949 63 KB

image
image1724×859 80.7 KB

This guide will help you set up two Pangolin instances that work together - one locally for internal use and one on a VPS for exposing services to the internet. I’ll cover two connectivity methods: Tailscale (easier) and Newt (more advanced).

What You’ll Achieve

  • A local Pangolin instance for managing your home services
  • A VPS-hosted Pangolin instance for secure internet access to selected services
  • The ability to choose which services to expose externally
  • No port forwarding required on your home network

Prerequisites

  • A VPS (Virtual Private Server) with a public IP address
  • A domain name pointing to your VPS
  • Docker installed on both your local machine and VPS
  • Basic familiarity with command-line operations

Option 1: Using Tailscale (Recommended for Beginners)

Tailscale creates a secure private network between your devices without opening ports.

Part 1: Setting Up Tailscale

  1. Install Tailscale on both your local machine and VPS

    • Go to tailscale.com and sign up for an account
    • Follow the installation instructions for your operating systems
    • For Ubuntu/Debian (VPS):
      curl -fsSL https://tailscale.com/install.sh | sh
    • For other systems, follow the instructions on Tailscale’s website

  2. Log in to Tailscale on both machines

    sudo tailscale up

    Follow the authentication link that appears.

  3. Verify connectivity

    • On each machine, run:
      tailscale ip -4
    • Note down both IP addresses (they will start with 100.x.x.x)
    • Test connectivity with ping:
      ping [other-machine-tailscale-ip]

Part 2: Local Pangolin Setup

  1. Install and configure Pangolin locally (skip if already installed)
    # Create a directory
mkdir -p ~/local-pangolin
cd ~/local-pangolin

# Download the installer
wget -O installer "https://github.com/fosrl/pangolin/releases/download/v1.1.0/installer_linux_amd64"
chmod +x ./installer

# Run the installer
sudo ./installer

  1. Follow the installation prompts

    • Base Domain Name: Use whatever you prefer locally (e.g., homelab.10.24.7.119.traefik.me)
    • Dashboard Domain Name: Set to match your local network (e.g., pangolin.homelab.10.24.7.119.traefik.me)
    • For local use only, you can skip email configuration
    • Set your admin credentials securely

  2. Configure resources on your local Pangolin

    • Access your local Pangolin dashboard (e.g., https://pangolin.homelab.10.24.7.119.traefik.me)
    • Create a local organization
    • Add sites and resources as needed for your local services

Part 3: VPS Pangolin Setup

  1. Install and configure Pangolin on your VPS

    # Create a directory
mkdir -p ~/vps-pangolin
cd ~/vps-pangolin

# Download the installer
wget -O installer "https://github.com/fosrl/pangolin/releases/download/v1.1.0/installer_linux_amd64"
chmod +x ./installer

# Run the installer
sudo ./installer

  2. Follow the installation prompts

    • Base Domain Name: Use your actual domain (e.g., example.com)
    • Dashboard Domain Name: Your public dashboard domain (e.g., pangolin.example.com)
    • Let’s Encrypt Email: Your email for SSL certificates
    • Configure admin credentials securely

Part 4: Setting Up Cross-Instance Access

  1. Create a “Local” site on your VPS Pangolin

    • Log in to your VPS Pangolin dashboard
    • Go to “Sites” tab
    • Click “Add Site”
    • Name: “Local Pangolin” or similar
    • Connection Method: Choose “Local” (not Newt)
    • Click “Create Site”

  2. Create resources on VPS Pangolin that point to your local services

    • Go to “Resources” tab
    • Click “Add Resource”
    • Fill in the details:
      • Name: “Wallos” (or your service name)
      • Subdomain: “wallos” (or preferred subdomain)
      • Site: Select the “Local Pangolin” site you created
      • Click “Create Resource”

  3. Configure the resource target

  4. Access your local service

    • You can now access your local service via your VPS domain
    • For example: https://wallos.example.com

Option 2: Using Newt (Pangolin’s Native Tunneling)

Newt is Pangolin’s native tunneling client that creates secure WireGuard tunnels.

Part 1: VPS Pangolin Setup

  1. Install and configure Pangolin on your VPS with Gerbil

    # Create a directory
mkdir -p ~/vps-pangolin
cd ~/vps-pangolin

# Download the installer
wget -O installer "https://github.com/fosrl/pangolin/releases/download/v1.1.0/installer_linux_amd64"
chmod +x ./installer

# Run the installer
sudo ./installer

  2. Follow the installation prompts

    • Base Domain Name: Your actual domain (e.g., example.com)
    • Dashboard Domain Name: Your public dashboard domain (e.g., pangolin.example.com)
    • Let’s Encrypt Email: Your email for SSL certificates
    • Important: When asked about tunneling, select “Yes” to install Gerbil
    • Configure admin credentials securely

  3. Create an organization and site on VPS Pangolin

    • Access your VPS Pangolin dashboard (e.g., https://pangolin.example.com)
    • Create a new organization when prompted
    • Go to “Sites” tab
    • Click “Add Site”
    • Name: “Home Network” or similar
    • Connection Method: Choose “Newt”
    • Important: Copy the Newt command or configuration shown - you’ll need this later
    • Click “Create Site”

Part 2: Local Machine Setup with Newt

  1. Install Newt on your local machine

    # Download Newt (use appropriate version for your system)
wget -O newt "https://github.com/fosrl/newt/releases/download/v1.0.0-beta.5/newt_linux_amd64"
chmod +x ./newt

# Move to a permanent location (optional)
sudo mv ./newt /usr/local/bin

  2. Run Newt with your site configuration

    • Use the command copied from the VPS Pangolin site creation:
    ./newt \
--id YOUR_ID_HERE \
--secret YOUR_SECRET_HERE \
--endpoint https://your-domain.com
    • Keep this terminal window open or set up Newt as a service to run in the background

  3. Verify connection

    • Check the Newt output for connection confirmation
    • In your VPS Pangolin dashboard, the site status should change to “Online”

Part 3: Setting Up Local Services for Exposure

  1. Install and configure services on your local machine

    • Set up your services (e.g., Wallos, Home Assistant, Plex)
    • Note down their local IP addresses and ports

  2. Create resources on VPS Pangolin for each service

    • Go to “Resources” tab
    • Click “Add Resource”
    • Fill in the details:
      • Name: “Wallos” (or your service name)
      • Subdomain: “wallos” (or preferred subdomain)
      • Site: Select the “Home Network” site you created earlier
      • Click “Create Resource”

  3. Configure the resource target

    • On the resource’s “Connectivity” page:
    • Enable SSL if you want HTTPS
    • Add a target:
    • Click “Add Target”
    • Click “Save Changes”

  4. Access your local service

    • You can now access your local service via your VPS domain
    • For example: https://wallos.example.com

Comparison of Approaches

Tailscale Approach

  • Pros:
    • Easier to set up for beginners
    • Works across any network
    • No need for Gerbil on VPS side
    • Can be used for many other things beyond Pangolin
  • Cons:
    • Requires installing Tailscale on both machines
    • Limited free tier (if you need many devices)

Newt Approach

  • Pros:
    • Native to Pangolin
    • Doesn’t require third-party service
    • Purpose-built for this exact use case
  • Cons:
    • Slightly more complex setup
    • Requires Gerbil component on VPS

Troubleshooting

Can’t connect to local Pangolin from VPS

  1. Check Tailscale/Newt connectivity
    • For Tailscale: ping [tailscale-ip]
    • For Newt: Check logs with sudo docker logs newt
  2. Verify correct IP addresses are used in the resource target
  3. Check that the port is correct

Resources not loading

  1. Check if the local service is running
  2. Verify the target IP and port are correct
  3. For SSL issues, wait a few minutes for certificates to be issued
  4. Check Pangolin logs: sudo docker logs pangolin

“Could not connect to host” errors

  1. Verify Tailscale/Newt connection is active
  2. Check if local service is accessible locally
  3. Try using HTTP instead of HTTPS for the target connection
  4. Verify firewall settings allow traffic

Extra Tips

  1. Make Newt run automatically (for the Newt approach)

    # Create a systemd service file
sudo nano /etc/systemd/system/newt.service

    Add this content:

    [Unit]
Description=Newt VPN Client
After=network.target

[Service]
ExecStart=/usr/local/bin/newt --id YOUR_ID_HERE --secret YOUR_SECRET_HERE --endpoint https://your-domain.com
Restart=always
User=root

[Install]
WantedBy=multi-user.target

    Enable and start the service:

    sudo systemctl enable newt.service
sudo systemctl start newt.service

  2. Set up wildcard certificates on your VPS Pangolin for instant SSL on new services

  3. Secure your exposed services with Pangolin’s authentication features

By following this guide, you now have two Pangolin instances working together - one for local network management and one for securely exposing selected services to the internet. You can easily add more services to expose as needed without reconfiguring your home router or opening ports.

1 Like
2

Are there any options with Pangolin to route traffic locally, without going through the VPS? For instance, if I want to secure apps in my local network and use the same DNS name. With internally hosted NPM (or other reverse proxy), I just had to add internal DNS records that pointed to the NPM server. With Pangolin, it seems that can’t be done? My apologies if I’ve missed something.

3 Likes
3

yes, you can.
https://forum.hhf.technology/t/deploying-pangolin-locally-without-domain-names-with-traefik-me-a-step-by-step-guide/
In the above setup you won’t require a vps or domain names.

4

Apologies, I meant so you can still host it on a VPS for external routing and not open any ports. Sorry for the confusion.

1 Like
5

you can host it at home without opening ports, it can be hosted on a vps without opening ports. both conditions can be used. depends how and what services you want to route.

6

All my services are within their own containers on different subnets. So for instances all my management svcs like technitium, portainer, etc… on the Management vlan 10.6.200.100, and all my security svc like Pocket ID, Vaultwarden etc.. are on the security vlan 10.6.100.100 etc… So does that mean I will have to place a local instance of Pangolin is each subnet in order for this to work or can I just have one instance of Pangolin running locally and it can handle multiple subnets?

Hope this makes sense.

1 Like
7

if you can access them from the same subnet where pangolin is hosted then yes, you can get it work.

8

Would this also work with a Wireguard Tunnel on an Opnsense Router instead of Tailscale/Newt?

My thinking is this would allow the whole subnet to be exposed and would allow for better bandwidth/traffic monitoring on the Opnsense Wireguard Interface.

1 Like
9

Why not. Connection is up to you.

10

The main reason I came across this guide was to get Split DNS working as If my Reverse Proxy was locally hosted again and not on a VPS.

The goal would be to use app,example,org on my LAN and have it resolve to the Local Pangolin through a DNS rewrite while if it’s a WAN connection, the same app,example,org would go through the VPS.

I just want to confirm, since I notice the local instance is not the the external domain, that in the best case I could do something like app,lan.,example,org but there is no way to do actual Split DNS for the same URL unless I go for only a 1 instance Local approach and lose the ability for my IP to be masked as it would be if there was a 2nd instance on a VPS?

1 Like
11

Ping me on hhf discord. We can discuss in detail. HHF Technology

I might not be available right now but will respond to you in after hours. You have lot of options to achieve what you said.

12

I tried this, everything installed fine I had an issue with newt had to rename the folder but I was never able to connect the site in pangolin on the local box. I was using devai for vps and rustyram domains I mean it seems like it should have connected but I am still learning…at the moment i have traefik installed locally and pangolin vps.

1 Like
13

you can post what error or where you are stuck or ping me or mattercoder here HHF Technology

14

I have pangolin running on a vps but I was trying to install it on my server at the house and create a local site in the pangolin dashboard then just add my containers to the pangolin and use it that way…but since I have the vps and newt already installed I got an error so I renamed the second newt folder and it installed but would not connect never showed online not sure if this works my ports are blocked so I need traefik and maybe I need to add wild cards dns after installing pangolin.

15

Your mention “This guide will help you set up two Pangolin instances that work together.”

For me it is not clear in which your steps for option 2 (Newt) you install your local pangolin instance.

1 Like
16

Hi, I agree , I am trying to follow the second option and I have the feeling to miss something …