diff --git a/README.md b/README.md
index ea3d529..d5fd07c 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,10 @@ Authentication is enforced by an API key and Json Web Tokens.
* Edit /keys/index.js and set "explorers.bitcoind" to "inactive".
* Main drawbacks of using your local bitcoind for these imports:
- * It doesn't return the full transactional history associated to the HD account but only transactions having an unspent output controlled by the HD account.
- * It's slightly slower than using the option relying on the OXT API.
- * In some specific cases, the importer might miss the most recent unspent outputs. Higher values of gap.external and gap.internal in /keys/index.js should help to mitigate this issue. Another workaround is to request the endpoint /support/xpub/.../rescan provided by the REST API with the optional gap parameter.
* This option is considered as experimental.
+ * It doesn't return the full transactional history associated to an HD account or to an address but only transactions having an unspent output controlled by the HD account or the address.
+ * It's slightly slower than using the option relying on the OXT API.
+ * It may fail to correctly import an existing wallet if this wallet had a large activity.
+ * If you use bitcoind and if the import seems to return an invalid balance, you can use the "XPUB rescan" function provided by the maintenance tool. This function allows you to force the minimum number of addresses to be derived and the start index for the derivation.
+ * As a rule of thumb, we recommend to use bitcoind as the source of imports and to setup your Dojo with a new clean wallet. It increases your privacy and it removes all potential issues with the import of a large wallet.
+
diff --git a/doc/DOCKER_setup.md b/doc/DOCKER_setup.md
index bec2a8b..e85cb13 100644
--- a/doc/DOCKER_setup.md
+++ b/doc/DOCKER_setup.md
@@ -2,11 +2,25 @@
MyDojo is a set of Docker containers providing a full Samourai backend composed of:
* a bitcoin full node accessible as an ephemeral Tor hidden service,
-* the backend database,
-* the backend modules with an API accessible as a static Tor hidden service,
+* a backend database,
+* a backend modules with an API accessible as a static Tor hidden service,
* a maintenance tool accessible through a Tor web browser.
+# Table of Content
+- [Architecture](#architecture)
+- [Requirements](#requirements)
+- [First-time install procedure](#install)
+- [Upgrade procedure](#upgrade)
+- [Configuration files](#config_files)
+- [Dojo shell script](#shell_script)
+- [Dojo maintenance tool](#maintenance_tool)
+- [Pairing your wallet to your Dojo](#pairing)
+- [Network connections](#network)
+
+
+
+
## Architecture ##
@@ -42,6 +56,7 @@ MyDojo is a set of Docker containers providing a full Samourai backend composed
|______________________________________________________________|
+
## Requirements ##
@@ -54,6 +69,8 @@ MyDojo is a set of Docker containers providing a full Samourai backend composed
* Tor Browser installed on the host machine (or on another machine if your host is a headless server)
+
+
## First-time Setup ##
This procedure allows to install a new Dojo from scratch.
@@ -125,6 +142,8 @@ Exit the logs with CTRL+C when the syncing of the database has completed.
* Restrict the access to your host machine as much as possible by configuring its firewall.
+
+
## Upgrade ##
This procedure allows to upgrade your Dojo with a new version.
@@ -149,6 +168,32 @@ This procedure allows to upgrade your Dojo with a new version.
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.
+Note: The upgrade process will override all manual modifications of the files stored under the directory with an exception for the three configuration files stored in the "/docker/my_dojo/conf" directory.
+
+
+
+
+## Configuration files ##
+
+Each new release of Dojo is packaged with 3 template files stored in the "/docker/my_dojo/conf" directory:
+- docker-bitcoin.conf.tpl
+- docker-mysql.conf.tpl
+- docker-node.conf.tpl
+
+These templates files define default values for configuration options of your Dojo.
+
+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.
+
+During an upgrade (dojo.sh upgrade), the content of the templates 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).
+
+Most options provided in the configuration files can be later modified. New values will become active after a call to
+
+```
+./dojo.sh restart
+```
+
+
+
## Dojo shell script ##
@@ -200,25 +245,29 @@ Available commands:
```
+
+
## Dojo maintenance tool ##
-A maintenance tool is accessible through your Tor browser at the url: /admin
+A maintenance tool is accessible through your Tor browser at the url: /admin
The maintenance tool requires that you allow javascript for the site.
Sign in with the value entered for NODE_ADMIN_KEY.
+
-## Pairing ##
+## Pairing your wallet to your Dojo ##
Once the database has finished syncing, you can pair your Samourai Wallet with your Dojo in 2 steps:
-* Open the maintenance tool in a Tor browser and sign in with your admin key.
+* Open the maintenance tool in a Tor browser (Tor v3 onion address) and sign in with your admin key.
* Get your smartphone and launch the Samourai Wallet app. Scan the QRCode displayed in the "Pairing" tab of the maintenance tool.
+
## Network connections ##
@@ -230,4 +279,4 @@ The maintenance tool is accessed as a Tor hidden service (static onion address).
The Bitcoin node only allows incoming connections from Tor (ephemeral onion address).
-The Bitcoin node attempts outgoing connections to both Tor and clearrnet nodes (through the Tor local proxy).
+The Bitcoin node attempts outgoing connections to both Tor and clearnet nodes (through the Tor local proxy).