lukechilds
/
umbrel-samourai-dojo
mirror of https://github.com/lukechilds/umbrel-samourai-dojo.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

add a detailed installation and upgrade guide for ubuntu

use-env-var-docker
kenshin-samourai 4 years ago
parent
3e2d6aad14
commit
0c81a1b37d
2 changed files with 515 additions and 4 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 10
      doc/DOCKER_setup.md
  2. 509
      doc/DOCKER_ubuntu_setup.md

10
doc/DOCKER_setup.md
View File

@ -61,7 +61,7 @@ MyDojo is a set of Docker containers providing a full Samourai backend composed
| | ---------- ---------- |
| whirlnet | dojonet |
|_________________|______________________________________________________________|
Host machine
Host machine
@ -109,6 +109,8 @@ Most options provided in the configuration files can be later modified. New valu
## First-time Setup ##
For Ubuntu 16, see this detailed [installation and upgrade guide](./DOCKER_ubuntu_setup.MD).
For MacOS, see this detailed [installation guide](./DOCKER_mac_setup.MD).
For Synology, see this detailed [installation guide](./DOCKER_synology_setup.md).
@ -325,7 +327,7 @@ Once the database has finished syncing, you can pair your Samourai Wallet with y
1. Open the maintenance tool in a Tor browser (Tor v3 onion address) and sign in with your admin key.
2. Get your smartphone and launch the Samourai Wallet app. Scan the first QRCode displayed in the "Pairing" tab of the maintenance tool.
2. Get your smartphone and launch the Samourai Wallet app. Scan the first QRCode displayed in the "Pairing" tab of the maintenance tool.
If you experience any problems when pairing, try re-installing the app and select "Connect to existing Dojo" from the [⋮] menu.
@ -336,7 +338,7 @@ You can pair your Samourai Wallet with your local block explorer in 2 steps:
1. Open the maintenance tool in a Tor browser (Tor v3 onion address) and sign in with your admin key.
2. Get your smartphone and launch the Samourai Wallet app. Scan the second QRCode displayed in the "Pairing" tab of the maintenance tool.
2. Get your smartphone and launch the Samourai Wallet app. Scan the second QRCode displayed in the "Pairing" tab of the maintenance tool.
<a name="network"/>
@ -353,7 +355,7 @@ The block explorer is accessed as a Tor hidden service (static onion address).
The Whirlpool API is accessed as a Tor hidden service (static onion address).
The Whirlpool client connects to the Whirlpool Coordinator hidden service.
The Whirlpool client connects to the Whirlpool Coordinator hidden service.
The Bitcoin node only allows incoming connections from Tor (ephemeral onion address).

509
doc/DOCKER_ubuntu_setup.md
View File

@ -0,0 +1,509 @@
# Installation and Upgrade of Dojo on Ubuntu 16
This procedure is written for the installation of MyDojo on a host machine running Ubuntu 16 but it should be easy to adapt it for Linux distributions running on a x86-64 architecture.
## Table of Content ##
- [Requirements](#requirements)
- [Storage locations](#storage)
- [Installation procedure](#install)
- [Upgrade procedure](#upgrade)
<a name="requirements"/>
## 1/ Requirements ##
The main requirements for the host machine running MyDojo are:
* Processor: x86-64
* OS: Linux 64 bits
* Disk Type: SSD (recommended)
* Disk Size: 600GB (min)/ 1TB (recommended)
* RAM: 2GB (min) / 4GB (recommended)
__Additional Considerations__
* While MyDojo will work fine on a multipurpose computer, a dedicated host machine connected 24/7 to the network is recommended. MyDojo was primarily designed as a server always ready for use
* The clock of the host machine MUST be set properly (required for Tor)
<a name="storage"/>
## 2/ Storage Locations ##
By default, MyDojo stores its code and data in 2 different locations:
* __MyDojo application code__: source code of MyDojo + Dojo Shell Script + Configuration files
* __MyDojo and Docker data__: persistent data required for a functional MyDojo (blockchain data, Dojo database, logs, Docker images)
By default, MyDojo and Docker data will be stored under `/var/lib/docker` directory but the directory can be modified (e.g.: all data stored on an dedicated disk).
<a name="install"/>
## 3/ First Installation
The procedure described in this section will configure and install MyDojo with its own Indexer for fast rescans. See the [Advanced Setups](./DOCKER_advanced_setups.md) for more information about this module or for the additional installation of a Whirlpool client on your Dojo.
### 3.1/ Prepare Host System
First, we must prepare our host system for MyDojo by installing required operating system dependencies and configuring our linux system with privacy and security in mind.
#### 3.1.1/ Install OS dependencies
```
> cd ~
> sudo apt-get update
> sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common unzip
```
#### 3.1.2/ Install Docker & Docker-Compose
For an installation of Docker and Docker Compose with a different Linux distribution, please refer to the official [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/) documentations.
If Docker is already installed on the host machine remove old Docker versions installed on the computer
```
> sudo apt-get remove docker docker-engine docker.io containerd runc
```
__Download Docker's official PGP key__
```
> curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
> sudo apt-key fingerprint 0EBFCD88
```
Verify that you now have the key with the fingerprint `9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88`
__Install Docker__
```
> sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
> sudo apt-get update
> sudo apt-get install docker-ce docker-ce-cli containerd.io
```
__Test the installation of Docker__
```
> sudo docker --version
```
This command should return the version of Docker if installation was successful.
__Install Docker Compose__
```
> sudo curl -L "https://github.com/docker/compose/releases/download/1.25.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
> sudo chmod +x /usr/local/bin/docker-compose
```
__Test the installation of Docker Compose__
```
> sudo docker-compose --version
```
This command should return the version of Docker Compose if installation was successful.
__Create a user account for MyDojo__
Creating a segregated user account for MyDojo is a good idea for security reasons.
#### 3.1.3/ Create a dojo user
```
> sudo useradd -s /bin/bash -d /home/dojo -m -G sudo dojo
> sudo passwd dojo
```
Enter and confirm the password for the `dojo` user.
__Add the user to the docker group__
```
> sudo usermod -aG docker dojo
```
__Restart Host System__
```
> sudo shutdown -r now
```
Log back into the Host System with the `dojo` user and test the Docker installation
```
> docker run hello-world
```
This command should display a hello message if Docker can be run with the `dojo` user.
#### 3.1.4/ Configure Docker data storage directory (optional)
This step should be applied if you don't want to store MyDojo and Docker data under the default `/var/lib/docker` directory (e.g.: all data will be stored on an external SSD).
__Stop the Docker Service__
```
> sudo systemctl stop docker
```
Create the directory that will store Docker data (replace `/path/to/target/directory/` by the correct path).
```
> sudo mkdir /path/to/target/directory/
```
Temporarily switch to root and create the daemon.json file storing the path to your Docker direct (replace `/path/to/target/directory/` by the correct path).
```
> sudo su - root
> sudo echo '{ "data-root": "/path/to/target/directory/" }' > /etc/docker/daemon.json
> exit
```
### 3.2/ Downloading MyDojo
Now that the Host System has been prepared, we will download the latest version of MyDojo source code and configure it before proceeding with install.
#### 3.2.1/ Initialize the dojo app directory
We first create a directory for housing our MyDojo files. In this guide we are naming this directory `dojo-app` and it will be located in the home directory of the `dojo` user.
```
> mkdir ~/dojo-app
```
#### 3.2.2/ Download latest MyDojo files
Download and unpack the source archive for the latest version of MyDojo and copy these files to the newly created `dojo-app` directory with the following commands.
```
> cd ~
> wget https://code.samourai.io/dojo/samourai-dojo/-/archive/master/samourai-dojo-master.zip
> unzip samourai-dojo-master.zip -d .
> cp -a samourai-dojo-master/. dojo-app/
```
Delete the source archive now that we have copied the files to our directory.
```
> rm -rf samourai-dojo-master
> rm samourai-dojo-master.zip
```
### 3.3/ Configuring MyDojo
Change the working directory to the MyDojo configuration directory.
```
> cd ~/dojo-app/docker/my-dojo/conf
```
__Note:__
You will be required to generate various random alphanumeric passwords to secure various aspects of your Dojo installation. You can generate these in any way you wish, but you may wish to use the following command in a terminal session to generate these passwords with sufficient entropy:
```
> cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1
```
#### 3.3.1/ Bitcoin configuration
Edit the `docker-bitcoind.conf.tpl` file.
```
> nano docker-bitcoind.conf.tpl
```
Customize the content of the file
```
BITCOIND_RPC_USER=<provide_this_value>
BITCOIND_RPC_PASSWORD=<provide_this_value>
```
__Note:__
If your machine has a lot of RAM, it's recommended that you increase the value of `BITCOIND_DB_CACHE` (e.g 2048) for a faster Initial Block Download.
Save and exit the file with `CTRL+X`, `Y` and `ENTER`.
#### 3.3.2/ Database configuration
Edit the ``docker-mysql.conf.tpl`` file.
```
> nano docker-mysql.conf.tpl
```
Customize the content of the file
```
MYSQL_ROOT_PASSWORD=<provide_this_value>
MYSQL_USER=<provide_this_value>
MYSQL_PASSWORD=<provide_this_value>
```
Save and exit the file with `CTRL+X`, `Y` and `ENTER`.
#### 3.3.3/ NodeJS configuration
Edit the `docker-node.conf.tpl` file.
```
> nano docker-node.conf.tpl
```
Customize the content of the file
```
NODE_API_KEY=<provide_this_value>
NODE_ADMIN_KEY=<provide_this_value>
NODE_JWT_SECRET=<provide_this_value>
NODE_ACTIVE_INDEXER=local_indexer
```
Save and exit the file with `CTRL+X`, `Y` and `ENTER`.
#### 3.3.4/ Indexer configuration
Edit the `docker-indexer.conf.tpl` file.
```
> nano docker-indexer.conf.tpl
```
Customize the content of the file
```
INDEXER_INSTALL=on
```
Save and exit the file with `CTRL+X`, `Y` and `ENTER`.
#### 3.3.5/ Explorer configuration
Edit the `docker-explorer.conf.tpl` file.
```
> nano docker-explorer.conf.tpl
```
Customize the content of the file
```
EXPLORER_KEY=<provide_this_value>
```
Save and exit the file with `CTRL+X`, `Y` and `ENTER`.
### 3.6/ Execute the first installation of MyDojo
From this point on the install process is automatic. Launch the installation of MyDojo
```
> cd ~/dojo-app/docker/my-dojo
> ./dojo.sh install
```
Confirm the installation with `Y` and `ENTER`.
#### 3.6.1/ Understanding the Automatic Install
At this point, your job is done. The Dojo Shell script and Docker are going to take over and a lot of things are going to happen automatically.
__Building of MyDojo containers__
First, the shell script is going to initialize a set of configuration files. Then Docker is going to
initialize the dedicated networks and data volumes that will be used by MyDojo. At last, Docker is going
to build the Docker containers composing MyDojo.
This latest operation may last from a dozen to a few tens of minutes, depending on the specs of the hardware. A lot of logs are displayed and you may be concerned that some of these logs (displayed in red) are the sign of a problem. Don't worry about this. Some of these logs are just informational or warnings. Just be aware that if a blocking error occurs, Docker will stop building the containers and you won't reach the next phase.
__First launch of MyDojo__
If all Docker containers have been successfully built, the Shell Script is going to launch MyDojo (equivalent of the `dojo.sh start` command) and display its logs.
Here you may be able to observe a few things in the logs:
* The schema of the local database is initialized (done once during first installation)
* The Tor container is connecting to the Tor network
* Dojo application modules are started in the NodeJS container
* The Bitcoin daemon is launched, establishes connections to remote full nodes and starts to download block headers.
* The indexer is launched and waits for the completion of the Initial Blocks Download by the Bitcoin daemon.
__Initial Blocks Download__
When all blocks headers have been successfully downloaded and processed, the Bitcoin daemon is going to process its Initial Blocks Download (IBD). In parallel, the `Tracker` module of Dojo is going to process its own IBD thanks to data provided by the Bitcoin daemon.
This phase is going to last from 1 to several days, depending on the specs of the hardware. At this point, all you have to do is wait. The Bitcoin daemon is processing the IBD while the Tracker is importing block headers in parallel.
Note: You can exit the logs with `CTRL+C`. Don't worry, MyDojo is still running in background.
__Address Indexing__
When the Bitcoin daemon has completed its IBD, the Indexer will automatically start the indexation of all Bitcoin addresses. When the indexation is complete, it will compact the database.
These operations should last a few more hours, depending on the specs of the hardware.
Note: You may notice errors returned by the Block Explorer during all these operations. Don't worry. The Block Explorer should be available as soon as the Indexer has completed its tasks.
### 3.7/ Monitor Install Progress with the Maintenance Tool (DMT)
Retrieve the onion address of the DMT with the commands
```
> cd ~/dojo-app/docker/my-dojo
> ./dojo.sh onion
```
Open the DMT with the Tor browser and check the `Status` page.
If a green check is displayed for all modules and if the chaintip displayed for all modules match with the chaintip displayed by a third-party Block Explorer, then your Dojo is ready.
<a name="upgrade"/>
## 4/ Upgrade
The procedures described in this section will upgrade your Dojo to the most recent version or to a specific version of Dojo.
### 4.1/ Upgrade to latest version
This procedure allows to upgrade MyDojo to the latest version.
#### 4.1.1/ Stop MyDojo
```
> cd ~/dojo-app/docker/my-dojo
> ./dojo.sh stop
```
#### 4.1.2/ Update the code of MyDojo
Download the archive of latest version
```
> cd ~
> wget https://code.samourai.io/dojo/samourai-dojo/-/archive/master/samourai-dojo-master.zip
```
Uncompress the archive
```
> unzip samourai-dojo-master.zip -d .
```
Overwrite the dojo-app directory with the content of the archive
```
> cp -a samourai-dojo-master/. dojo-app/
```
#### 4.1.3/ Update Configuration (optional)
Check the [release notes](https://code.samourai.io/dojo/samourai-dojo/-/blob/master/RELEASES.md) of the new vesion for a list of new features that may require to tune the value of new configuration options.
If applicable, edit the templates files stored in `~/dojo-app/docker/my-dojo/conf/` and modify the values set for new configuration options.
#### 4.1.4/ Start Upgrade
```
> cd ~/dojo-app/docker/my-dojo
> ./dojo.sh upgrade
```
Confirm that you want to upgrade MyDojo with `Y` and `ENTER`.
The shell script is going to rebuild the Docker containers. MyDojo will be automatically restarted after the containers have been rebuilt.
#### 4.1.5/ Cleanup
```
> cd ~
> rm -rf samourai-dojo-master
> rm samourai-dojo-master.zip
```
### 4.2/ Upgrade to a specific version
This procedure allows to upgrade MyDojo to a specific version `X.Y.Z`
#### 4.2.1/ Stop MyDojo
```
> cd ~/dojo-app/docker/my-dojo
> ./dojo.sh stop
```
#### 4.2.2/ Update the code of MyDojo
Download the archive of version `X.Y.Z`
```
> cd ~
> wget https://code.samourai.io/dojo/samourai-dojo/-/archive/vX.Y.Z/samourai-dojo-vX.Y.Z.zip
```
Uncompress the archive
```
> unzip samourai-dojo-vX.Y.Z.zip -d .
```
Overwrite the dojo-app directory with the content of the archive
```
> cp -a samourai-dojo-vX.Y.Z/. dojo-app/
```
#### 4.2.3/ Update Configuration (optional)
Check the [release notes](https://code.samourai.io/dojo/samourai-dojo/-/blob/master/RELEASES.md) for a list of new features that may require to tune the value of new configuration options.
If applicable, edit the templates files stored in `~/dojo-app/docker/my-dojo/conf/` and modify the values set for new configuration options.
#### 4.2.4/ Start Upgrade
```
> cd ~/dojo-app/docker/my-dojo
> ./dojo.sh upgrade
```
Confirm that you want to upgrade MyDojo with `Y` and `ENTER`.
The shell script is going to rebuild the Docker containers. MyDojo will be automatically restarted after the containers have been rebuilt.
#### 4.2.5/ Cleanup
```
> cd ~
> rm -rf samourai-dojo-vX.Y.Z
> rm samourai-dojo-vX.Y.Z.zip
```
Write Preview
Loading…
Cancel
Save