1. Deploy a container

We provide a docker-compose file that helps you deploy the container. First, download docker-compose.yml, and then write your bridge configuration to a new file, .env, which is in the same directory as docker-compose.yml. Here's a template:

# Your bridge's Tor port.
OR_PORT=X
# Your bridge's obfs4 port.
PT_PORT=Y
# Your email address.
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 by running:

docker-compose up -d obfs4-bridge

This command will automatically load your docker-compose.yml file while considering the environment variables in .env.

You should now see output similar to the following:

Starting docker-obfs4-bridge_obfs4-bridge_1 ... done

That's it! Your container is now bootstrapping your new obfs4 bridge.

2. Upgrade your container

Upgrading to the latest version of our image is as simple as pulling the latest version of the image running:

docker-compose pull obfs4-bridge

And then restarting the container:

docker-compose up -d obfs4-bridge

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.

3. 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

If you are having trouble setting up your bridge, have a look at our help section. If your bridge is now running, check out the post-install notes.

4. Advanced usage

You may set additional torrc variables in your .env file by setting OBFS4_ENABLE_ADDITIONAL_VARIABLES to 1 and prefixing the desired torrc options with OBFS4V_. For example, to set the AddressDisableIPv6 option, include the following lines in your .env:

OBFS4_ENABLE_ADDITIONAL_VARIABLES=1
OBFS4V_AddressDisableIPv6=1

You may download our template .env to get started.