Opening Custom HTTPS Ports with Pangolin for Pangolin UI

Guides & Tutorials
1

Introduction

When deploying self-hosted services, you’ll often encounter scenarios where you need to use non-standard ports. Perhaps you’re running multiple HTTPS services, working around network restrictions, or following specific security policies. While the default ports 80 and 443 work for most cases, sometimes you need custom ports like 8443, 8080, or others for your HTTPS traffic.

Pangolin primarily works with standard ports out of the box. However, with some configuration tweaks, you can extend its capabilities to handle custom HTTPS ports while still benefiting from its excellent authentication and certificate management features.

In this guide, I’ll walk you through configuring Pangolin to accept HTTPS traffic on custom ports like 8443, complete with proper TLS termination and authentication.

Understanding the Architecture

Before diving into the configuration, it helps to understand how the Pangolin stack works:

  1. Traefik serves as the front-facing reverse proxy, listening on configured ports and handling TLS termination
  2. Pangolin manages resources, users, and access controls
  3. Gerbil (optional) handles tunneling via WireGuard if you’re using that feature

For our custom port configuration, we primarily need to focus on Traefik, as it’s responsible for actually binding to network ports.

Step-by-Step Configuration

Let’s configure Pangolin to handle HTTPS traffic on port 8443 alongside the standard 80 and 443 ports.

1. Configure Traefik EntryPoints

First, we need to tell Traefik to listen on our custom port. EntryPoints in Traefik define the network ports it binds to and their basic configuration.

Open your config/traefik/traefik_config.yml file and locate the entryPoints section. Add a new entry for your custom HTTPS port:

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: "letsencrypt"
    transport:
      respondingTimeouts:
        readTimeout: "30m"
  # New custom HTTPS entrypoint
  websecure-custom:
    address: ":8443"
    http:
      tls:
        certResolver: "letsencrypt"
    transport:
      respondingTimeouts:
        readTimeout: "30m"

Notice that our new websecure-custom entrypoint mirrors the configuration of the standard websecure entrypoint, including TLS settings and timeouts. This ensures consistent behavior across both standard and custom ports.

2. Expose the Port in Docker

Next, we need to expose the port in our Docker configuration. The approach depends on whether you’re using Pangolin with tunneling (Gerbil) or without.

If using Gerbil (with tunneling):

Edit your docker-compose.yml and add the port mapping to the Gerbil service:

gerbil:
  # other configuration...
  ports:
    - 51820:51820/udp # For WireGuard
    - 443:443         # For HTTPS
    - 80:80           # For HTTP
    - 8443:8443       # Add your custom HTTPS port

If using Pangolin without tunneling:

Edit your docker-compose.yml and add the port mapping to the Traefik service:

traefik:
  # other configuration...
  ports:
    - 443:443
    - 80:80
    - 8443:8443  # Add your custom HTTPS port

3. Update Your Firewall

Don’t forget to open the port in your firewall if you’re running one:

# For UFW (Ubuntu/Debian)
sudo ufw allow 8443/tcp

# For firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload

4. Configure Routing for Your Custom Port

Now we need to tell Traefik how to route traffic coming in on our custom port. There are two approaches:

Option 1: Using Dynamic Configuration (Recommended)

This approach integrates fully with Pangolin’s authentication system. Edit your config/traefik/dynamic_config.yml file and add a router for your custom port:

http:
  routers:
    # Existing routers...
    
    # Custom HTTPS port router
    custom-port-resource:
      rule: "Host(`myresource.example.com`)"
      service: api-service  # Points to Pangolin
      entryPoints:
        - websecure-custom  # Our new entrypoint
      tls:
        certResolver: letsencrypt

This router will catch requests coming to myresource.example.com:8443 and forward them to Pangolin, complete with authentication and TLS termination.

Option 2: Using Raw TCP Mode

For simpler setups or when you don’t need Pangolin’s authentication, you can use the raw TCP/UDP feature:

  1. Follow the TCP/UDP setup procedure from Pangolin’s documentation
  2. Create a TCP resource with port 8443 in the Pangolin web interface
  3. Add targets pointing to your backend service

This approach is less integrated but can be easier to set up for certain use cases.

5. Restart Services

After making these changes, restart your services to apply the configuration:

# If using docker-compose
sudo docker compose restart traefik
sudo docker compose restart gerbil # if using tunneling

# Or restart the entire stack
sudo docker compose down
sudo docker compose up -d

Advanced Configuration Options

Multiple Custom Ports

You can repeat the process for multiple custom ports. Just add additional entrypoints and port mappings:

entryPoints:
  # Existing entrypoints...
  websecure-8443:
    address: ":8443"
    http:
      tls:
        certResolver: "letsencrypt"
  websecure-8444:
    address: ":8444"
    http:
      tls:
        certResolver: "letsencrypt"

Port-Specific TLS Options

You can apply different TLS configurations to different ports. For instance, if you wanted stricter TLS settings on your custom port:

entryPoints:
  websecure-custom:
    address: ":8443"
    http:
      tls:
        certResolver: "letsencrypt"
        options: "strict-tls@file"

Then define the TLS options in your dynamic configuration:

tls:
  options:
    strict-tls:
      minVersion: "VersionTLS13"
      cipherSuites:
        - "TLS_AES_256_GCM_SHA384"
        - "TLS_CHACHA20_POLY1305_SHA256"

Troubleshooting

Check Port Bindings

If your custom port isn’t working, first verify that Traefik is actually binding to it:

sudo netstat -tulpn | grep 8443

You should see Traefik (or the Docker container) listening on that port.

Examine Traefik Logs

Check Traefik’s logs for any errors related to your entrypoint:

sudo docker compose logs traefik | grep 8443

Test TLS Configuration

You can test the TLS configuration of your custom port with tools like openssl:

openssl s_client -connect myresource.example.com:8443 -servername myresource.example.com

Conclusion

By leveraging Traefik’s flexibility, you can extend Pangolin to handle HTTPS traffic on custom ports, giving you greater deployment flexibility while still maintaining strong security and authentication.

This capability is particularly valuable when:

  • Working around network restrictions
  • Running multiple HTTPS services on the same server
  • Complying with specific security requirements
  • Integrating with legacy systems that expect specific ports

While the default configuration of Pangolin covers most common use cases, these customizations showcase the system’s adaptability for more specialized deployments.

Remember that these changes require a solid understanding of how Traefik works, so be sure to consult the official Traefik documentation if you need to dive deeper into specific features or configurations.

With these adjustments, your Pangolin deployment can handle HTTPS traffic on any port you need, combining the security of HTTPS with the flexibility of custom port assignments.