|
| 1 | +## Running `teosd` in a docker container |
| 2 | +A `teos` image can be built from the Dockerfile located in `docker`. You can create the image by running: |
| 3 | + |
| 4 | + cd rust-teos |
| 5 | + docker build -f docker/Dockerfile -t teos . |
| 6 | + |
| 7 | +Then we can create a container by running: |
| 8 | + |
| 9 | + docker run -it teos |
| 10 | + |
| 11 | +One way to feed `teos` custom config options is to set environment variables: |
| 12 | + |
| 13 | + docker run -it -e <ENV_VARIABLES> teos |
| 14 | + |
| 15 | +Notice that the ENV variables are optional, if unset the corresponding default setting is used. The following ENVs are available: |
| 16 | + |
| 17 | +``` |
| 18 | +- API_BIND=<teos_api_hostname> |
| 19 | +- API_PORT=<teos_api_port> |
| 20 | +- RPC_BIND=<teos_rpc_hostname> |
| 21 | +- RPC_PORT=<teos_rpc_port> |
| 22 | +- BTC_NETWORK=<btc_network> |
| 23 | +- BTC_RPC_CONNECT=<btc_node_hostname> |
| 24 | +- BTC_RPC_PORT=<btc_node_port> |
| 25 | +- BTC_RPC_USER=<btc_rpc_username> |
| 26 | +- BTC_RPC_PASSWORD=<btc_rpc_password> |
| 27 | +# The following options can be set turned on by setting them to "true" |
| 28 | +- DEBUG=<debug_bool> |
| 29 | +- DEPS_DEBUG=<deps_debug_bool> |
| 30 | +- OVERWRITE_KEY=<overwrite_key_bool> |
| 31 | +- FORCE_UPDATE=<force_update_bool> |
| 32 | +``` |
| 33 | + |
| 34 | +### Volume persistence |
| 35 | + |
| 36 | +You may also want to run docker with a volume, so you can have data persistence in `teosd` databases and keys. |
| 37 | +If so, run: |
| 38 | + |
| 39 | + docker volume create teos-data |
| 40 | + |
| 41 | +And add the the mount parameter to `docker run`: |
| 42 | + |
| 43 | + -v teos-data:/home/teos/.teos |
| 44 | + |
| 45 | +If you are running `teosd` and `bitcoind` in the same machine, continue reading for how to create the container based on your OS. |
| 46 | + |
| 47 | +### `bitcoind` running on the same machine (UNIX) |
| 48 | +The easiest way to run both together in the same machine using UNIX is to set the container to use the host network. |
| 49 | + |
| 50 | +For example, if both `teosd` and `bitcoind` are running on default settings, run: |
| 51 | + |
| 52 | +``` |
| 53 | +docker run \ |
| 54 | + --network=host \ |
| 55 | + --name teos \ |
| 56 | + -v teos-data:/home/teos/.teos \ |
| 57 | + -e BTC_RPC_USER=<btc_rpc_username> \ |
| 58 | + -e BTC_RPC_PASSWORD=<btc_rpc_password> \ |
| 59 | + -it teos |
| 60 | +``` |
| 61 | + |
| 62 | +Notice that you may still need to set your RPC authentication details, since, hopefully, your credentials won't match the `teosd` defaults. |
| 63 | + |
| 64 | +### `bitcoind` running on the same machine (OSX or Windows) |
| 65 | + |
| 66 | +Docker for OSX and Windows does not allow to use the host network (nor to use the `docker0` bridge interface). To work around this |
| 67 | +you can use the special `host.docker.internal` domain: |
| 68 | + |
| 69 | +``` |
| 70 | +docker run \ |
| 71 | + -p 9814:9814 \ |
| 72 | + -p 8814:8814 \ |
| 73 | + --name teos \ |
| 74 | + -v teos-data:/home/teos/.teos \ |
| 75 | + -e BTC_RPC_CONNECT=host.docker.internal \ |
| 76 | + -e BTC_RPC_USER=<btc_rpc_username> \ |
| 77 | + -e BTC_RPC_PASSWORD=<btc_rpc_password> \ |
| 78 | + -e API_BIND=0.0.0.0 \ |
| 79 | + -e RPC_BIND=0.0.0.0 \ |
| 80 | + -it teos |
| 81 | +``` |
| 82 | + |
| 83 | +Notice that we also needed to add `API_BIND=0.0.0.0` and `RPC_BIND=0.0.0.0` to bind the API to all interfaces of the container. |
| 84 | +Otherwise it will bind to `localhost` and we won't be able to send requests to the tower from the host. |
| 85 | + |
| 86 | +### Interacting with a TEOS instance |
| 87 | + |
| 88 | +Once our `teos` instance is running in the container, we can interact with it using `teos-cli`. We have two main ways of doing so: |
| 89 | + |
| 90 | +1) You can open a shell to the Docker instance by calling: |
| 91 | + |
| 92 | +`docker exec -it <CONTAINER_NAME> sh` |
| 93 | + |
| 94 | +Then you can use the `teos-cli` binary from inside the container as you would use it from your host machine. |
| 95 | + |
| 96 | +2) Using `teos-cli` remotely (assuming you have it installed in the source machine) and pointing to the container. To do so, you will need to copy over the necessary credentials to the host machine. To do so, you can follow the instructions in [the main README](https://github.com/talaia-labs/rust-teos/blob/master/README.md#running-teos-cli-remotely). |
| 97 | + |
| 98 | +### Plugging in Tor |
| 99 | + |
| 100 | +You may have noticed, in the above section where the environment variables are covered, that the Tor options are nowhere to be found. That's because these instructions assume that users will likely be setting up Tor in another container. |
| 101 | + |
| 102 | +On the machine where you have Tor running, you can follow [these instructions](https://community.torproject.org/onion-services/setup/) for setting up a hidden service manually. |
| 103 | + |
| 104 | +For instance, if you're running `teosd` in a Docker container on the same machine as where Tor is running, you can create a hidden service from the host machine to hide the IP of the `teosd` API (listening on port 9814 for example). If you're using Linux, you can do so by editing your `torrc` file on the host machine with the below option: |
| 105 | + |
| 106 | +``` |
| 107 | +HiddenServiceDir /var/lib/tor/teosd # Path for Linux. This may differ depending on your OS. |
| 108 | +HiddenServicePort 9814 127.0.0.1:9814 |
| 109 | +``` |
| 110 | + |
| 111 | +Then restart Tor. |
| 112 | + |
| 113 | +If all works correctly, the hidden service public key will be located in the `HiddenServiceDir` you set above, in the file called `hostname`. |
0 commit comments