1. Pull the image

We are maintaining a docker image that runs an obfs4 bridge. First, download the image:

docker pull phwinter/obfs4-bridge:latest

2. Deploy a container

We provide a Makefile that helps you deploy the container. First, download the Makefile, and then write your bridge configuration to a new file, bridge.sh. Here's a template:

# Your bridge's Tor port.
export OR_PORT=X
# Your bridge's obfs4 port.
export PT_PORT=Y
# Your email address.
export EMAIL=Z

Replace X with your desired OR port, Y with your obfs4 port (make sure that both ports are forwarded in your firewall), and Z with your email address, which allows us to get in touch with you if there are problems with your bridge. With your bridge configuration in place, you can now deploy the container:

source bridge.sh && make deploy

You should now see output similar to the following:

201fbd2b4d28e6f226978f27547edd79272871c5949bf8aab3872c983156a108
Make sure that port X and Y are forwarded in your firewall.

That's it! Your container (identified by the first line of output) is now bootstrapping your new obfs4 bridge.

If you want to run multiple bridges on your machine, you need to create more bridge configuration files with different sets of ports, and run make deploy again, like so:

source bridge-1.sh && make deploy
source bridge-2.sh && make deploy
...

3. Upgrade your container

To upgrade to the latest version of our image, you need to stop your existing container, delete it, pull the latest image, and finally deploy it again:

docker stop CONTAINER_ID
docker rm CONTAINER_ID
docker pull phwinter/obfs4-bridge:latest
source bridge.sh && make deploy

Note that your bridge's data directory (which includes its key material) is stored in a docker volume, so you won't lose your bridge's identity when upgrading to the latest docker image. If you are running multiple bridges on your computer, you need to repeat this step for each bridge. We will announce new image versions on the tor-dev mailing list.

4. Monitor your logs

You can inspect your bridge's logs by running:

docker logs CONTAINER_ID

To use your new bridge in Tor Browser, you need its "bridge line". Here's how you can get your bridge line:

docker exec CONTAINER_ID get-bridge-line

This will return a string similar to the following:

obfs4 1.2.3.4:1234 B0E566C9031657EA7ED3FC9D248E8AC4F37635A4 cert=OYWq67L7MDApdJCctUAF7rX8LHvMxvIBPHOoAp0+YXzlQdsxhw6EapaMNwbbGICkpY8CPQ iat-mode=0

Make sure to check out the post-install notes. If you are having troubles setting up your bridge, have a look at our help section.