ngrok is the programmable network edge that makes it easy to publish unreachable ports on the public internet. DoltLab is the self-hosted, self-managed version of DoltHub, where you can push your Dolt databases, collaborate on changes, manage pull requests, and view data diffs through a sleek, user-friendly UI.
Recently, users asked us how they could use port-forwarding to expose their DoltLab instance running on a closed host (or local host). Their goal was to easily grant their friends and colleagues access so they could experience DoltLab and start collaborating with them.
In response to this, we shipped DoltLab v0.5.5, available for download here, that supports port-forwarding with tools like
ngrok. In this post I'll cover how to configure
ngrok and DoltLab so you too can start sharing and collaborating on your own DoltLab instance.
Be warned: exposing DoltLab in this way is a bit complicated and is not for the feint of heart. There are four DoltLab services which need ports exposed via
ngrok, which requires some YAML customizations. Following the instructions in this post will make DoltLab work with
ngrok, but it's not going to be pretty. That said, if you want something easy, we recommend using DoltHub instead. DoltLab is for your inner System Administrator—get ready to
bash this beast onto the public internet 🤠.
Please note that exposing DoltLab in this way requires running one of its services without authentication and is not recommended for production use. To run a production DoltLab instance, please refer to our previous blog post where we demonstrate how to spin up a production ready DoltLab instance.
To get started, install DoltLab
v0.5.5 on a linux host. The quickest way to do this is to copy the ubuntu-bootstrap.sh script onto your host and run:
chmod +x ubuntu-bootstrap.sh
sudo ./ubuntu-bootstrap.sh with-sudo "$DOLTLAB_VERSION"
Running this script installs all of DoltLab's dependencies and puts its assets in a directory called
Before doing anything else with DoltLab we need to install, configure, and run
ngrok. In a separate shell, download the latest
ngrok agent here and confirm your installation succeeded by running:
ngrok version 3.0.6
Next, you'll need to create a free account using
ngrok's dashboard. After you login, copy your personal auth token and run the following to authenticate your agent:
ngrok config add-authtoken <your auth token>
After adding the auth token to the config, edit the config using
ngrok config edit so that it contains the following
authtoken: <your auth token>
The above tunnel definitions will produce different urls we'll supply as values to DoltLab's
docker-compose.yaml file. We'll also use one hostname for the
HOST_IP environment variable when we're ready to start DoltLab.
This will start the
ngrok agent and use the tunnel definition in the configuration file.
ngrok will output something like the following:
Account firstname.lastname@example.org (Plan: Free)
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding tcp://2.tcp.ngrok.io:14290 -> localhost:50051
Forwarding http://b862-54-200-56-40.ngrok.io -> http://localhost:100
Forwarding http://c9bd-54-200-56-40.ngrok.io -> http://localhost:80
Forwarding http://e65d-54-200-56-40.ngrok.io -> http://localhost:4321
Using the output above, return to the original shell you used to run the
cd into the
We will edit portions of the
docker-compose.yaml file by inputting the generated urls or hostnames output by
First, copy the hostname used for serving data files that
ngrok forwards to
http://localhost:100. In our example, this value is
Next, edit the
command section of
docker-compose.yaml. Replace the values supplied to the
-http-host argument and the
-backingStoreHostNameOverrideKey argument with the
ngrok value of
We're also going to supply this value to the
-remoteApiHostNameOverrideKey argument in the
Now, copy the url from the
ngrok output that forwards to
http://localhost:4321. In our example above this is
Still editing the
command section arguments, replace the value of
Then, copy the hostname used for pushing, pulling, and cloning that forwards to
http://localhost:50051, which for us is
2.tcp.ngrok.io:14290, and set this value as the environment variable
CLONE_REMOTE_HOST in the
Finally, edit the
command section. Add the argument
-no-auth, disabling authentication for user uploaded files:
ngrok removes cross-origin credentials required to run
doltlabfileserviceapi with authentication. This change is necessary for enabling user file uploads on DoltLab exposed with
Save these changes and you can now start up your DoltLab instance. Use the
start-doltlab.sh script and supply
EMAIL_PORT=<smtp port> \
EMAIL_HOST=<smtp host> \
EMAIL_USERNAME=<smtp username> \
EMAIL_PASSWORD=<smtp password> \
Your DoltLab instance should now be accessible at
Don't be alarmed if you see the screen above, you can simply bypass it by clicking "Details", and continuing on to the DoltLab site. You might need to refresh the page a couple times, but afterward, you should see your fully operational DoltLab instance being served.
Make sure you only visit
ngrok urls from sources you trust! We take no responsibility for any stolen Bored Apes.
If you see the following screen, you know it's working correctly.
We love getting feedback, questions, and feature requests from our community, so if there's anything you'd like to see added in DoltLab or in one of our other products, please don't hesitate to reach out. You can checkout each of our different product offerings below, to find which ones are right for you:
Also, don't hesitate to contact us here or on Discord.