Using Tailscale with Pangolin to Connect VPS to Home Lab

Networking
,
1

Introduction

This guide explains how to use Tailscale as an alternative connectivity solution with Pangolin. Instead of using Newt/WireGuard tunneling provided by the Gerbil component, we’ll create a secure mesh network with Tailscale that connects your VPS to your home lab. This approach allows you to use Pangolin in “Local” mode while still maintaining secure access to your home lab resources.

Benefits of Using Tailscale with Pangolin

  • Zero-config networking: Tailscale automatically handles NAT traversal and firewall issues
  • End-to-end encryption: All traffic is encrypted with WireGuard (which Tailscale uses under the hood)
  • Simple setup: No need to configure port forwarding or complex networking
  • Single sign-on: Use existing identity providers for authentication
  • MagicDNS: Automatic DNS resolution for your devices on the Tailscale network

Prerequisites

  • A VPS with a public IP address running Linux (Ubuntu/Debian recommended)
  • A domain name pointing to your VPS
  • Root access to both your VPS and home lab machines
  • Basic familiarity with the command line
  • TCP ports 80 and 443 exposed on your VPS (for Pangolin/Traefik)

1. Set Up Tailscale Network

Install Tailscale on VPS

# On Ubuntu/Debian
curl -fsSL https://tailscale.com/install.sh | sh

# On RHEL/CentOS/Fedora
dnf install tailscale
sudo systemctl enable --now tailscaled

# On other distros, see: https://tailscale.com/download

Install Tailscale on Home Lab Server

# On Ubuntu/Debian
curl -fsSL https://tailscale.com/install.sh | sh

# For other platforms, see: https://tailscale.com/download

Connect Both Systems to Tailscale

On both the VPS and home lab server:

sudo tailscale up

This will provide a URL to authenticate with Tailscale. Open the URL in a browser and log in with your Tailscale account.

Verify Connectivity

On either machine, check the status and note the Tailscale IP addresses:

tailscale status

Example output:

100.100.100.100  vps-server        user@example.com   linux   active  -
100.100.100.101  homelab-server    user@example.com   linux   active  -

VPS

image
image1799×344 16.2 KB

HOMELAB

image
image1616×267 15.4 KB

Make note of your home lab server’s Tailscale IP (e.g., 100.100.100.101). You’ll need this later when configuring Pangolin.

image
image1450×181 20.3 KB

Enable IP Forwarding on VPS

echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

2. Install Pangolin on VPS without Tunneling

Since we’re using Tailscale for connectivity, we’ll install Pangolin without the Gerbil tunneling component.

Download and Run the Installer

# 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

Configure Pangolin Without Tunneling

During the installation:

  1. Enter your base domain and dashboard domain as prompted
  2. Provide an email for Let’s Encrypt
  3. When asked if you want to install Gerbil for tunneling, select No
  4. Configure your admin user email and password
  5. Set your security preferences for signups and organization creation

The installer will generate a Docker Compose file similar to this:

name: pangolin
services:
  pangolin:
    image: fosrl/pangolin:1.1.0
    container_name: pangolin
    restart: unless-stopped
    volumes:
      - ./config:/app/config
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
      interval: "3s"
      timeout: "3s"
      retries: 5

  traefik:
    image: traefik:v3.3.3
    container_name: traefik
    restart: unless-stopped

    ports:
      - 443:443
      - 80:80

    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --configFile=/etc/traefik/traefik_config.yml
    volumes:
      - ./config/traefik:/etc/traefik:ro
      - ./config/letsencrypt:/letsencrypt
      - ./config/traefik/logs:/var/log/traefik

networks:
  default:
    driver: bridge
    name: pangolin

3. Configure Pangolin for Local Mode

After installation, let’s ensure the Pangolin configuration is properly set up for local mode:

Edit config/config.yml if needed:

app:
    dashboard_url: "https://your-pangolin-domain.com"
    base_domain: "your-domain.com"
    log_level: "info"
    save_logs: false

server:
    external_port: 3000
    internal_port: 3001
    next_port: 3002
    internal_hostname: "pangolin"
    session_cookie_name: "p_session_token"
    resource_access_token_param: "p_token"
    resource_session_request_param: "p_session_request"

traefik:
    cert_resolver: "letsencrypt"
    http_entrypoint: "web"
    https_entrypoint: "websecure"
    prefer_wildcard_cert: true

# Note: gerbil section can be deleted or left as is

rate_limits:
    global:
        window_minutes: 1
        max_requests: 100

users:
    server_admin:
        email: "admin@your-domain.com"
        password: "YourSecurePassword123!"

flags:
    require_email_verification: false
    disable_signup_without_invite: true
    disable_user_create_org: false
    allow_raw_resources: true
    allow_base_domain_resources: true

4. Start Pangolin and Access the Dashboard

sudo docker compose up -d

After the containers start, access your Pangolin dashboard at your configured URL (e.g., https://your-pangolin-domain.com).

5. Setting Up Site and Resources in Pangolin

1. Create Your Organization

After logging in with your admin credentials:

  1. You’ll be prompted to create an organization
  2. Enter a name (e.g., “Home Lab”)
  3. Enter an ID (e.g., “homelab”) - Note: This cannot be changed later

2. Create a Local Site

  1. Go to the Sites tab
  2. Click the Add Site button
  3. Give your site a name (e.g., “Home Server”)
  4. Select the connection method: Local
  5. Click Create Site

This creates a site that uses the local network (which now includes our Tailscale network).

3. Create a Resource

  1. Go to the Resources tab
  2. Click the Add Resource button
  3. Enter resource details:
    • Name (e.g., “Home Assistant”)
    • Subdomain (e.g., “homeassistant”)
    • Select the site you created
  4. Click Create Resource

4. Configure Resource Target with Tailscale IP

  1. Navigate to the resource you just created
  2. Go to the Connectivity tab
  3. Add a target with the following details:
    • Method: Choose HTTP or HTTPS depending on your service
    • IP Address: Enter your home lab’s Tailscale IP (e.g., 100.100.100.101)
    • Port: Enter the port your service runs on (e.g., 8123 for Home Assistant)
  4. Click Add Target
  5. Click Save Changes

Example configuration for Home Assistant:

  • Method: HTTP
  • IP Address: 100.100.100.101
  • Port: 8123

5. Configure Authentication

  1. Navigate to the Authentication tab for your resource
  2. By default, the resource is protected with your Pangolin credentials (Platform SSO)
  3. Adjust authentication settings as needed (SSO, password, email whitelist, etc.)

6. Test Access

Once Let’s Encrypt provisions the SSL certificate (which may take a few minutes), you can access your resource at:

https://subdomain.your-domain.com

6. Additional Configuration for Multiple Services

Adding More Home Services

Repeat the “Create a Resource” and “Configure Resource Target” steps for each service you want to expose. Use the same site but different subdomains and target ports.

Example services:

  • Plex Media Server (port 32400)
  • Nextcloud (port 443)
  • Jellyfin (port 8096)
  • Bitwarden (port 8080)

Tailscale Subnet Routing (Optional)

If you have other devices on your home network that aren’t running Tailscale directly, you can enable subnet routing:

  1. On your home lab server, find your local subnet (e.g., 192.168.1.0/24)
  2. Enable subnet routing:
sudo tailscale up --advertise-routes=192.168.1.0/24
  1. In the Tailscale admin console, approve the subnet routes
  2. For Pangolin resource targets, you can now use local IPs (e.g., 192.168.1.10)

7. Troubleshooting

Connectivity Issues

If you’re having connectivity issues between your VPS and home lab:

  1. Check Tailscale status:
tailscale status
  1. Verify ping works between your devices:
ping 100.100.100.101  # Replace with your home lab's Tailscale IP
  1. Check that Tailscale is running on both devices:
sudo systemctl status tailscaled

Certificate Issues

If you’re having issues with SSL certificates:

  1. Check Traefik logs:
docker logs traefik

  1. Verify that ports 80 and 443 are open on your VPS

  2. Ensure your domain is correctly pointing to your VPS IP

Resource Access Issues

If you’re having trouble accessing your resources:

  1. Verify the Tailscale connection is active on both ends
  2. Check that you’re using the correct Tailscale IP in the resource target
  3. Ensure the service is running and accessible on the specified port
  4. Check Pangolin logs:
docker logs pangolin

8. Security Considerations

Tailscale ACLs

For added security, consider configuring Tailscale ACLs to restrict which devices can communicate:

  1. Visit the Tailscale admin console (Tailscale)
  2. Configure ACLs to restrict traffic as needed

Pangolin Authentication

Even though your resources are only accessible through Tailscale, it’s good practice to maintain authentication:

  1. Keep Platform SSO enabled for resources
  2. Consider using resource-specific passwords for sensitive services
  3. Enable email whitelisting for resources that need additional security

Conclusion

You’ve now set up a secure connection between your VPS running Pangolin and your home lab using Tailscale. This configuration allows you to expose your home services through Pangolin without using Newt or opening ports on your home network.

The main advantages of this approach:

  • Simplified networking with Tailscale’s mesh VPN
  • No port forwarding required on your home router
  • Secure, encrypted connections between all devices
  • DNS name resolution with Let’s Encrypt certificates
  • Authentication and access control through Pangolin

Remember to keep both Tailscale and Pangolin updated for the latest security features and bug fixes.

2 Likes
2

I am just confused, why do I need Pangolin when just tailscale does the job. I am a little confused

1 Like
3

You don’t. It’s acting as a replacement of their wireguard implementation called newt.
You can use pangolin without tailscale, this is just an optional change some users might want.

2 Likes
4

for tailscale you need client at each end unless you use funnels. pangolin is an RP integrated with tunnels to protect your home infra. Mini CF tunnels self hosted.