Pangolin tunnel

Some projects require an external service to callback to your application, for example when handling payments. When you’re on a network that is not accessible from the internet, we can still allow access to a specific application using tunnel.

The way it works is, a client application (Newt) is setup on the machine where your application is running. This is connected to a server application (Pangolin) which can dynamically create domains and route them to the client application.

Internet -> Pangolin -> Newt -> App

To start creating tunnels you will need an account to access the pangolin dashboard. Either use the credentials from vaultwarden or ask an admin to create an account for you.

Creating a tunnel

1. From the dashboard select Sites from the side panel.
2. Select +Add Site.
3. Enter a name. Leave site addresss default.
4. Select Newt Tunnel as the tunnel type.
5. For installing newt select Unix & MacOS
6. Copy the commands.
7. Click on Create Site
8. Now execute the commands in a terminal on the target of the tunnel.
9. From the side panel select Resources
10. Select +Add Resources
11. Enter a name.
12. Select HTTPS resource as resource type.
13. Enter the desired subdomain.
14. Select +Add target
15. On the left dropdown select previously created site.
16. Select http as protocol
17. Enter the target IP/hostname. This is most likely localhost you can also try 127.0.0.1, 0.0.0.0
18. Enter the port your application is running on.
19. Select Create Resource
20. Further configuration to SSL and authentication is possible by editing the resource.
21. Visiting the URL should now connect to your application.

Installing Newt automatically

For staging environments it might be useful to automatically install newt when starting an application.

First make sure that the following environment variables are set properly.

• NEWT_ID
• NEWT_SECRET
• PANGOLIN_ENDPOINT

Install newt using curl -fsSL https://pangolin.net/get-newt.sh | bash Then start it using newt. If running in an entrypoint script you will want to run it in the background using newt &

The environment variables will be automatically picked up. Note that they will replace the command line parameters, they will not be available if the environment variable is detected.

Authentication

Pangolin features platform SSO which can limit the users that are allowed to access a resource. When allowing an external service access to an internal application authentication will need to be disabled.

1. Select Resources in the sidebar.
2. Select the resource.
3. Select the Authentication tab.
4. Disable Use platform SSO.
5. Select Save Users & Roles.
6. Confirm that authentication for the resource is set to Not Protected.