DOCKER_setup.md
1 # Installation of Dojo with Docker and Docker Compose 2 3 MyDojo is a set of Docker containers providing a full Samourai backend composed of: 4 * a bitcoin full node accessible as an ephemeral Tor hidden service, 5 * a backend database, 6 * backend modules with an API accessible as a static Tor hidden service, 7 * a maintenance tool accessible through a Tor web browser, 8 * a block explorer ([BTC RPC Explorer](https://github.com/janoside/btc-rpc-explorer)) accessible as a static Tor hidden service. 9 * an optional indexer of Bitcoin addresses ([addrindexrs](https://code.samourai.io/dojo/addrindexrs)) providing fast and private rescans of HD accounts and loose addresses. 10 11 12 ## Table of Content ## 13 - [Architecture](#architecture) 14 - [Requirements](#requirements) 15 - [Configuration files](#config_files) 16 - [First-time install procedure](#install) 17 - [Upgrade procedure](#upgrade) 18 - [Dojo shell script](#shell_script) 19 - [Dojo maintenance tool](#maintenance_tool) 20 - [Block explorer](#explorer) 21 - [Pairing your wallet to your Dojo](#pairing) 22 - [Network connections](#network) 23 24 25 <a name="architecture"/> 26 27 ## Architecture ## 28 29 ``` 30 ------------------ -------------------- 31 | Mobile Wallets | | Bitcoin full nodes | 32 ------------------ -------------------- 33 |_______________________|__________ 34 | 35 ------------- 36 | | 37 | Tor network | 38 | | 39 ------------ 40 | 41 | (Tor hidden services) 42 ____________________________________ | _________________________________________ 43 | | | | 44 | | --------- dmznet | 45 | | -----------| Tor |------------------------ | 46 | | | --------- | | 47 | --------- | | 48 | | nginx | - - - - - - - - - - - - - - - - - - - - - -|- - - - - - | 49 | --------- | | 50 | | | | | 51 | | ---------------------------- | | 52 | | | | | | 53 | | ---------- ---------- ---------- | 54 | | | Nodejs |----------| Explorer |------| Bitcoind | | 55 | | ---------- ---------- ---------- | 56 | | | | | | | 57 | | | ------- | | | 58 | | | | | | | 59 | | ---------- | ---------- | | 60 | | | MySQL | ----| Indexer |----------- | 61 | | ---------- ---------- | 62 | | dojonet | 63 |_________________|______________________________________________________________| 64 Host machine 65 66 ``` 67 68 69 <a name="requirements"/> 70 71 ## Requirements ## 72 73 * A dedicated computer (host machine) connected 24/7 to internet 74 * OS: Linux is recommended 75 * Disk: 600GB (minimal) / 1TB (recommended) - SSD is recommended 76 * RAM: 4GB (minimal) 77 * Docker and Docker Compose installed on the host machine (be sure to run a recent version supporting v3.2 of docker-compose files, i.e. Docker Engine v17.04.0+) 78 * Check that the clock of your computer is properly set (required for Tor) 79 * Tor Browser installed on the host machine (or on another machine if your host is a headless server) 80 81 82 <a name="config_files"/> 83 84 ## Configuration files ## 85 86 Each new release of Dojo is packaged with 7 template files stored in the `<dojo_dir>/docker/my-dojo/conf` directory: 87 - docker-common.conf.tpl 88 - docker-bitcoin.conf.tpl 89 - docker-explorer.conf.tpl 90 - docker-indexer.conf.tpl 91 - docker-mysql.conf.tpl 92 - docker-node.conf.tpl 93 - docker-tor.conf.tpl 94 95 These template files define default values for configuration options of your Dojo. 96 97 During the first-time installation (dojo.sh install) these templates are used to initialize the configuration files (files with .conf extension) that will be used by your Dojo. 98 99 During an upgrade (dojo.sh upgrade), the content of the template files is merged with the content of the configuration files, preserving the values that you may have modified in the configuration files. A backup of the configuration files is saved in the same directory (files with .save extension). 100 101 Most options provided in the configuration files can be later modified. New values will become active after a call to 102 103 ```sh 104 ./dojo.sh restart 105 ``` 106 107 108 <a name="install"/> 109 110 ## First-time Setup ## 111 112 For Ubuntu 16, see this detailed [installation and upgrade guide](./DOCKER_ubuntu_setup.MD). 113 114 For MacOS, see this detailed [installation guide](./DOCKER_mac_setup.MD). 115 116 For Synology, see this detailed [installation guide](./DOCKER_synology_setup.md). 117 118 For Raspberry Pi4 and Odroid N2, see the [Ronin Dojo Project](https://code.samourai.io/ronindojo/RoninDojo) 119 120 121 This procedure allows to install a new Dojo from scratch. 122 123 * Install [Docker and Docker Compose](https://docs.docker.com/compose/install/) on the host machine and check that your installation is working. 124 125 * Install [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en) on the host machine. 126 127 * Download the most recent release of Dojo from [Gitlab](https://code.samourai.io/dojo/samourai-dojo/-/archive/master/samourai-dojo-master.zip) 128 129 * Uncompress the archive on the host machine in a temporary directory of your choice (named `<tmp_dir>` in this doc) 130 131 * Create a directory for Dojo (named `<dojo_dir>` in this doc) 132 133 * Copy the content of the `<tmp_dir>/samourai-dojo-master` directory into the `<dojo_dir>` directory 134 135 * Customize the configuration of your Dojo 136 137 * Go to the `<dojo_dir>/docker/my-dojo/conf` directory 138 139 * Edit docker-bitcoind.conf.tpl and provide a new value for the following parameters: 140 * `BITCOIND_RPC_USER` = login protecting the access to the RPC API of your full node, 141 * `BITCOIND_RPC_PASSWORD` = password protecting the access to the RPC API of your full node. 142 * If your machine has a lot of RAM, it's recommended that you increase the value of `BITCOIND_DB_CACHE` for a faster Initial Block Download. 143 144 * Edit docker-mysql.conf.tpl and provide a new value for the following parameters: 145 * `MYSQL_ROOT_PASSWORD` = password protecting the root account of MySQL, 146 * `MYSQL_USER` = login of the account used to access the database of your Dojo, 147 * `MYSQL_PASSWORD` = password of the account used to access the database of your Dojo. 148 Note: These values can't be changed after the first installation. 149 150 * Edit docker-node.conf.tpl and provide a new value for the following parameters: 151 * `NODE_API_KEY` = API key which will be required from your Samourai Wallet / Sentinel for its interactions with the API of your Dojo, 152 * `NODE_ADMIN_KEY` = API key which will be required from the maintenance tool for accessing a set of advanced features provided by the API of your Dojo, 153 * `NODE_JWT_SECRET` = secret used by your Dojo for the initialization of a cryptographic key signing Json Web Tokens. 154 These parameters will protect the access to your Dojo. Be sure to provide alphanumeric values with enough entropy. 155 156 * Edit docker-explorer.conf.tpl and provide a new value for the following parameter: 157 * If you want to deactivate the block explorer, set the value of `EXPLORER_INSTALL` to `off`. 158 See this [section](#explorer) for more details about the block explorer. 159 160 * Dojo provides a few additional settings for advanced setups: 161 * installation of an address indexer used for fast imports and rescans, 162 * support of an external electrum server (ElectrumX or electrs) used for fast imports and rescans, 163 * static onion address for your full node, 164 * bitcoind RPC API exposed to external apps, 165 * use of an external full node, 166 * use of Tor Bridges, 167 * support of testnet. 168 See this [doc](./DOCKER_advanced_setups.md) for more details. 169 170 * Open the docker quickstart terminal or a terminal console and go to the `<dojo_dir>/docker/my-dojo` directory. This directory contains a script named dojo.sh which will be your entrypoint for all operations related to the management of your Dojo. 171 172 173 * Launch the installation of your Dojo with 174 175 ```sh 176 ./dojo.sh install 177 ``` 178 179 Docker and Docker Compose are going to build the images and containers of your Dojo. This operation will take several minutes (download and setup of all required software components). After completion, your Dojo will be launched and will begin the initialization of the full node (Bitcoin Initial Block Download and syncing of the database). This step will take several hours/days according to the specs of your machine. Be patient. Use CTRL+C to stop the display of the full logs. 180 181 182 * Monitor the progress made for the initialization of the database with this command displaying the logs of the tracker 183 184 ```sh 185 ./dojo.sh logs nodejs 186 ``` 187 188 Exit the logs with CTRL+C when the syncing of the database has completed. 189 190 191 * Retrieve the Tor onion addresses (v3) of the API and block explorer of your Dojo 192 193 ```sh 194 ./dojo.sh onion 195 ``` 196 197 * Restrict the access to your host machine as much as possible by configuring its firewall. 198 199 200 <a name="upgrade"/> 201 202 ## Upgrade ## 203 204 This procedure allows to upgrade your Dojo with a new version. 205 206 * Stop your Dojo with 207 208 ```sh 209 ./dojo.sh stop 210 ``` 211 212 * Download the most recent release of Dojo from [Gitlab](https://code.samourai.io/dojo/samourai-dojo/-/releases) 213 214 * Uncompress the archive on the host machine in a temporary directory of your choice (named `<tmp_dir>` in this doc) 215 216 * Copy the content of the `<tmp_dir>/samourai-dojo-1.x.y` directory into the `<dojo_dir>` directory (overwrite). 217 218 * Launch the upgrade of your Dojo with 219 220 ```sh 221 ./dojo.sh upgrade 222 ``` 223 224 Docker and Docker Compose are going to build new images and containers for your Dojo. After completion, the updated version of your Dojo will be launched automatically. 225 226 Note: The upgrade process will override all manual modifications of the files stored under the `<dojo_dir>` directory with an exception for the configuration files stored in the `<dojo_dir>/docker/my-dojo/conf` directory. 227 228 229 <a name="shell_script"/> 230 231 ## Dojo shell script ## 232 233 dojo.sh is a multifeature tool allowing to interact with your Dojo. 234 235 ```sh 236 Usage: ./dojo.sh command [module] [options] 237 238 Available commands: 239 240 help Display the help message. 241 242 bitcoin-cli Launch a bitcoin-cli console for interacting with bitcoind RPC API. 243 244 clean Free disk space by deleting docker dangling images and images of previous versions. 245 246 install Install your Dojo. 247 248 logs [module] [options] Display the logs of your dojo. 249 By default, the command displays the live logs. Use CTRL+C to stop the logs. 250 Use the -n option to display past logs. 251 252 Available modules: 253 dojo.sh logs : display the logs of all the Docker containers 254 dojo.sh logs bitcoind : display the logs of bitcoind 255 dojo.sh logs db : display the logs of the MySQL database 256 dojo.sh logs tor : display the logs of tor 257 dojo.sh logs nginx : display the logs of nginx 258 dojo.sh logs indexer : display the logs of the internal indexer 259 dojo.sh logs nodejs : display the logs of NodeJS modules (API, Tracker, PushTx API, Orchestrator) 260 dojo.sh logs explorer : display the logs of the Explorer 261 262 Available options: 263 -n [VALUE] : display the last VALUE lines 264 265 onion Display the Tor onion addresses allowing to access the API, maintenance tool and block explorer of your Dojo. 266 267 restart Restart your Dojo. 268 269 start Start your Dojo. 270 271 stop Stop your Dojo. 272 273 uninstall Delete your Dojo. Be careful! This command will also remove all data. 274 275 upgrade Upgrade your Dojo. 276 277 version Display the version of dojo. 278 279 ``` 280 281 282 <a name="maintenance_tool"/> 283 284 ## Dojo maintenance tool ## 285 286 A maintenance tool is accessible through your Tor browser at the url: <v3_onion_address>/admin 287 288 The maintenance tool requires that you allow javascript for the site. 289 290 Sign in with the value entered for `NODE_ADMIN_KEY`. 291 292 293 <a name="explorer"/> 294 295 ## Block explorer ## 296 297 A block explorer ([BTC RPC Explorer](https://github.com/janoside/btc-rpc-explorer)) is accessible through your Tor browser. 298 299 You can retrieve the onion address of the block explorer with the command 300 301 ```sh 302 ./dojo.sh onion 303 ``` 304 305 Notes: 306 307 * Current version doesn't support the display of detailed information for a Bitcoin address, 308 309 * Calls to the RPC API of your bitcoind are deactivated. 310 311 312 <a name="pairing"/> 313 314 ## Pairing your wallet to your Dojo ## 315 316 Once the database has finished syncing, you can pair your Samourai Wallet with your Dojo in 2 steps: 317 318 1. Open the maintenance tool in a Tor browser (Tor v3 onion address) and sign in with your admin key. 319 320 2. Get your smartphone and launch the Samourai Wallet app. Scan the first QRCode displayed in the "Pairing" tab of the maintenance tool. 321 322 If you experience any problems when pairing, try re-installing the app and select "Connect to existing Dojo" from the [⋮] menu. 323 324 325 ## Pairing your wallet to your local block explorer (coming "soon") ## 326 327 You can pair your Samourai Wallet with your local block explorer in 2 steps: 328 329 1. Open the maintenance tool in a Tor browser (Tor v3 onion address) and sign in with your admin key. 330 331 2. Get your smartphone and launch the Samourai Wallet app. Scan the second QRCode displayed in the "Pairing" tab of the maintenance tool. 332 333 334 <a name="network"/> 335 336 ## Network connections ## 337 338 The API of your Dojo is accessed as a Tor hidden service (static onion address). 339 340 If OXT is selected as the default source for imports, OXT clearnet API is accessed through the Tor local proxy. 341 342 The maintenance tool is accessed as a Tor hidden service (static onion address). 343 344 The block explorer is accessed as a Tor hidden service (static onion address). 345 346 The Bitcoin node only allows incoming connections from Tor (ephemeral onion address). 347 348 The Bitcoin node attempts outgoing connections to both Tor and clearnet nodes (through the Tor local proxy).