LogoLogo
  • Welcome to Release
  • Getting started
    • Quickstart
    • Create an account
    • Prepare to use Release
    • Create an application
      • Create custom application
      • Create from template
      • Servers vs runnables
    • Create an environment
  • Guides and examples
    • Domains and DNS
      • Manage domains
      • DNS and nameservers
        • Configure GoDaddy
        • Configure Cloudflare
        • Configure Namecheap
        • Other DNS hosts
      • Routing traffic
    • Example applications
      • Full stack voting app
      • Flask and RDS counter app
      • Static site with Gatsby
      • Golang with Postgres and Nginx
      • WordPress with MySQL
      • Spring and PostgreSQL
      • Terraform and Flask
      • OpenTelemetry demo
      • Load balancer with hostname
      • Static JavaScript service
      • SSH bastion access to services
      • ngrok and OAuth for private tunnels
      • Using OAuth Proxy
      • Hybrid Docker and static site
      • App Imports: Connecting two applications
      • Example library
    • Running instances
      • Cron jobs
      • Jobs
      • Using Helm charts
      • Using terminal
      • Viewing logs
      • Troubleshooting
        • ImagePullBackoff error
        • CrashLoopBackoff error
        • Exit codes
        • OOM: out of memory
    • Advanced guides
      • Containers guide
      • Application guide
      • Kubernetes guide
      • Create a cluster
      • Upgrade a cluster
      • Managing node groups
      • Patch node groups
      • Hostnames and rules
      • Serve traffic on multiple ports
      • Configure access to your K8s cluster
      • Designing for multiple environments
      • Microservices architecture
      • Monitoring your clusters
      • Performance tuning
      • Visibility and monitoring
      • Working with data
        • Container-based data
        • Seeding and migration
        • Cloud-provided data
        • Golden images
        • Third party
      • Pausing Instant Datasets
        • Application pausing schedules
        • Pause/resume environments
      • Infrastructure as code
        • Terraform
  • Reference documentation
    • Account settings
      • Account info
      • Managing users
      • Build settings
        • Build arguments
        • Build SSH keys
      • Add integrations
      • View clusters and cloud integrations
      • Add datasets
      • Environment handles
    • Workflows in Release
      • Stages of workflows
      • Serial deployments
      • Parallel deployments
      • Rolling deployments
      • Rainbow deployments
    • Networking
      • Network architecture (AWS)
      • Network architecture (GCP)
      • Ingresses
      • IP addresses
      • Cloud-provided services
      • Third-party services
    • Release environment versioning
    • Application settings
      • Application Template
        • Schema definition
      • Default environment variables
      • GitHub
      • Pull requests
      • GitOps
      • Just-in-time file mounts
      • Primary App Link
      • Create application FAQ
      • App-level build arguments
      • Parameters
      • Workspaces
    • End-to-end testing
    • Environment settings
      • Environment configuration
      • Environment variables
        • Environment variable mappings
        • Secrets vaults
        • Using Secrets with GitOps
        • Kubernetes Secrets as environment variables
        • Managing legacy Release Secrets
    • Environment expiration
    • Environment presets
    • Instant datasets on AWS
    • Instant datasets on GCP
    • Instant dataset tasks
      • Tonic Cloud
      • Tonic On-Premise
    • Cloud resources
    • Static service deployment
    • Helm
      • Getting started
      • Version-controlled Helm charts
      • Open-source charts
      • Building Docker images
      • Ingress and networking
      • Configuration
    • GitOps
    • The .release.yaml file
    • Docker Compose conversion support
    • Reference examples
      • Adding and removing services
      • Managing service resources
      • Adding database containers to the Application Template
      • Stock Off-The-Shelf Examples
    • Release API
      • Account Authentication
      • Environments API
        • Create
        • Get
        • Setup
        • Patch
      • User Authentication
      • Environment Presets API
        • Get Environment Preset List
        • Get Environment Preset
        • Put Environment Preset
  • Background concepts
    • How Release works
  • Frequently asked questions
    • Release FAQ
    • AWS FAQ
    • Docker FAQ
    • JavaScript FAQ
  • Integrations
    • Integrations overview
      • Artifactory integration
      • Cloud integrations (AWS)
        • AWS guides
        • Grant access to AWS resources
        • AWS how to increase EIP quota
        • Control your EKS fleet with systems manager
        • Managing STS access
        • AWS Permissions Boundaries
        • Private ECR Repositories
        • Using an Existing AWS VPC
        • Using an Existing EKS Cluster
      • Docker Hub integration
      • LaunchDarkly integration
      • Private registries
      • Slack integration
      • Cloud integrations (GCP)
        • GCP Permissions Boundary
      • Datadog Agent
      • Doppler Secrets Manager
      • AWS Secrets Management
    • Source control integrations
      • GitHub
        • Pull request comments
        • Pull request labels
        • GitHub deployments
        • GitHub statuses
        • Remove GitHub integration
      • Bitbucket
      • GitLab
    • Monitoring and logging add-ons
      • Datadog
      • New Relic
      • ELK (Elasticsearch, Logstash, and Kibana)
  • Release Delivery
    • Create new customer integration
    • Delivery guide
    • Release to customer account access controls
    • Delivery FAQs
  • Release Instant Datasets
    • Introduction
    • Quickstart
    • Security
      • AWS Instant Dataset security
    • FAQ
    • API
  • CLI
    • Getting started
    • Installation
    • Configuration
    • CLI usage example
    • Remote development environments
    • Command reference
      • release accounts
        • release accounts list
        • release accounts select
      • release ai
        • release ai chat
        • release ai config-delete
        • release ai config-init
        • release ai config-select
        • release ai config-upsert
      • release apps
        • release apps list
        • release apps select
      • release auth
        • release auth login
        • release auth logout
      • release builds
        • release builds create
      • release clusters
        • release clusters exec
        • release clusters kubeconfig
        • release clusters shell
      • release datasets
        • release datasets list
        • release datasets refresh
      • release deploys
        • release deploys create
        • release deploys list
      • release development
        • release development logs
        • release development start
      • release environments
        • release environments config-get
        • release environments config-set
        • release environments create
        • release environments delete
        • release environments get
        • release environments list
        • release environments vars-get
      • release gitops
        • release gitops init
        • release gitops validate
      • release instances
        • release instances exec
        • release instances logs
        • release instances terminal
  • Release.ai
    • Release.ai Introduction
    • Getting Started
    • Release.ai Templates
    • Template Configuration Basics
    • Using GPU Resources
    • Custom Workflows
    • Fine Tuning LlamaX
    • Serving Inference
Powered by GitBook
On this page
  • ngrok vs. open-source proxy servers
  • What you'll need
  • Set up
  • Add the ngrok secure tunnel
  • Find the tunnel address
  • Release's tips for protecting private services
  • 1. Use an easy subdomain
  • 2. Use a custom branded domain
  • 3. Use password protection
  • 4. Use OAuth protection

Was this helpful?

  1. Guides and examples
  2. Example applications

ngrok and OAuth for private tunnels

Protect private services in Release with ngrok

PreviousSSH bastion access to servicesNextUsing OAuth Proxy

Last updated 2 years ago

Was this helpful?

You may need a simple way to keep the applications you deploy to Release ephemeral environments private. Perhaps you're deploying a basic disposable admin tool, for example, or you would like to share a link with a potential client or vendor outside your organization. In such cases, you don't want to set up expensive access controls that need time-consuming configuration.

The solution is to create a proxy layer for your Release application environment.

ngrok vs. open-source proxy servers

We have a guide available for an .

Alternatively, take a look at this you can investigate.

We chose ngrok for this guide because it offers a simple, lightweight, and cost-effective way to securely expose an application without too much additional configuration or infrastructure maintenance.

What you'll need

Here's what you'll need to follow along:

  • An ngrok account. A free account may work for once-off environments. A business license is better for multiple accounts in a wildcard setup. Visit for more details.

  • An ngrok token. Preferably a token generated specifically for this use case so it can be revoked or changed without impacting a regularly used token somewhere else.

  • A Release application running in your Release account.

  • A service that you would like to expose via the proxy tunnel.

  • An OAuth, SAML, or OIDC service provider, such as Google Workspaces – this is optional, as it may incur vendor charges.

  • A custom domain name for your private pages, this is also optional, as it may incur vendor charges.

Set up

Say you want to expose the following service via the proxy tunnel:

services:
- name: docsbuild
  image: mycoolrepo/mycoolapp/docsbuild
  registry: local
  has_repo: true
  ports:
  - type: container_port
    port: '8080'
  build:
    context: "."
    dockerfile: docs/Dockerfile

The docsbuild service is not for public consumption, but we would like to view it along with our code deployments in pre-production settings. The main application is configured with authentication and access controls, but the documentation is a set of web pages and would be difficult to protect. If you added a regular node_port: and hostnames: section to your application, the documentation would be exposed to the internet.

Let's create a private tunnel for an additional layer of protection instead.

Add the ngrok secure tunnel

services:
- name: docsbuild-tunnel
  image: wernight/ngrok

Next, add the following to your application's environment variables template:

services:
  docbuild-tunnel:
  - key: NGROK_AUTH
    value: mysecretauthtoken
    secret: true
  - key: NGROK_LOOK_DOMAIN
    value: docsbuild
  - key: NGROK_PORT
    value: '8080'
  - key: NGROK_BINDTLS
    value: "true"

Add both services to your setup workflow, but don't add the tunnel service to your patch flow, since it doesn't need to be restarted during deploys:

workflows:
- name: setup
  paralellize:
  - step: docs
    tasks:
    - services.docsbuild
    - services.docsbuild-tunnel
    wait_for_finish: false
- name: patch
  paralellize:
  - step: docs
    tasks:
    - services.docsbuild
    wait_for_finish: false

Find the tunnel address

Exposing the tunnel service logs will reveal the one-time URL in ngrok.io similar to the following:

ngrok by @inconshreveable

Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://localhost:4040
Forwarding                    https://abc.ngrok.io -> docsbuild:80

Connnections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Point your browser to the Forwarding URL to view your documentation pages.

You can also expose the ngrok dashboard that runs on port 4040 by using hostnames:, or by using another tunnel pointed at the ngrok tunnel server. The ngrok tunnel dashboard could be used for various development or debugging services, but the dashboard itself will be exposed on the internet and may need to be protected too.

Release's tips for protecting private services

Here are our tips for securing private tunnels.

1. Use an easy subdomain

You may want to use a well-known custom domain name for your application tunnel endpoint, but this could incur additional costs and require an upgrade to your ngrok account.

You could instead add a subdomain directive to your environment variable template:

services:
  docsbuild-tunnel:
  - key: NGROK_SUBDOMAIN
    value: mydocs

Which yields something like this output:

ngrok by @inconshreveable

...
Forwarding                    https://mydocs.ngrok.io -> docsbuild:80

You can also use Environment variable mappingsto create a link to the tunnel port like this

mapping:
  NGROK_SUBDOMAIN: RELEASE_ENV_ID

You will also need to add Hostnames and rules section like the following to your application template so that you can easily click the link in the UI or pull request comments.

hostnames:
- ${env_id}.ngrok.io

2. Use a custom branded domain

For an even better domain name option, use a fully customised hostname. Please note this probably requires an upgrade to a paid ngrok account and features.

Prerequisites

A quick diversion here is required since the custom domain names will not be managed by Release (we have no way of knowing what the ngrok tunnel addresses will be). You will need to setup CNAME record(s) in your cloud DNS provider, and a custom domain and a TLS certificate in the ngrok dashboard.

Setup example

services:
  docsbuild-tunnel:
  - key: NGROK_HOSTNAME
    value: mydocs.private.example.com

Which yields something like this output:

ngrok by @inconshreveable

...
Forwarding                    https://mydocs.private.example.com -> docsbuild:80

You can also follow the same instructions as above for a mapping and hostnames section. This will avoid having to hardcode the values in your configuration file. These two sections should help guide you.

mapping:
  NGROK_HOSTNAME: DOCSBUILD_INGRESS_HOST
domain: example.com
hostnames:
- ${env_id}.private.${domain}

3. Use password protection

Add a basic authentication password:

services:
  docsbuild-tunnel:
  - key: NGROK_USERNAME
    value: "myuser"
  - key: NGROK_PASSWORD
    value: "mypassword"
    secret: true

4. Use OAuth protection

We can expose the application via ngrok using a . Instantiate this service alongside your other services in the application template as follows:

Here, the NGROK_AUTH key has the value of your ngrok token. We use NGROK_LOOK_DOMAIN to identify the service to expose via the ngrok tunnel, in this case it is docsbuild. The port is specified as 8080. By default ngrok will use http (you could specify TLS or TCP as well). Therefore the full url to your internal service in this example would be http://docsbuild:8080. You could consider adding a and pointing to http://localhost for even more privacy. The NGROK_BINDTLS option tells ngrok to redirect from HTTP to HTTPS and only support https: traffic externally.

Make sure you follow .

Please note that these features are an upgrade in the ngrok product feature and may require additional costs. Follow the ngrok documentation to , then associate the NGROK_AUTH token with an ACL to attach to the custom Edge. You can add various Edge modules, including Mutual TLS, IP restrictions, OIDC, SAML, OAuth, and more.

open source OAuth2 server
list of open source tunneling solutions
ngrok's pricing page
simple container
sidecar
ngrok's set up instructions
configure an Edge