Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Creating the quickstart guide #606

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Creating the quickstart guide #606

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe75ab0
Creating the quickstart guide
k3tan172 Nov 1, 2021
69454cc
Update doc/quickstart.md
k3tan172 Nov 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 138 additions & 0 deletions doc/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# The Quick Start Guide to Electrum Rust Server

### Prepare bitcoind

In your bitcoin.conf (usually sitting in /home/username/.bitcoin) ensure you have the following:
```
rpcallowip=127.0.0.1
rpcallowip=10.0.0.0/8
rpcallowip=172.0.0.0/8
rpcallowip=192.0.0.0/8
rpcuser=bitcoin
rpcpassword=bitcoin
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I prefer using bitcoind cookie file, instead of hard-coding the password.
WDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I use the rpcuser/rpcpassword because other projects connect to bitcoind via user/pass, not cookie file.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'd be best to persuade other projects to use cookie. Which are missing?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dojo, mempool.space

whitelist=127.0.0.1
[email protected]
```
Note: Be sure to restart your bitcoind instance for changes to take effect.
Your rpcuser and rpcpassword can be set to whatever you want, I've used bitcoin/bitcoin here.


### Prepare system to build electrs

```
sudo apt update
sudo apt install clang cmake build-essential
```

### Install latest version of Rust

`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If possible, I usually prefer to use the distribution-provided Rust (via apt install cargo).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

happy to do this, but just wanted to make sure that the version installed is 1.48+ for all distros. apt package manager may be out of date and installs an older version.


### Download electrs

In your home directory, download the electrs github repository and change directory into it.

`cd ~`
romanz marked this conversation as resolved.
Show resolved Hide resolved
`git clone https://github.com/romanz/electrs`
`cd electrs`

### Build electrs

`cargo build --locked --release`

Wait a while, can take some time.

### Configure electrs

In the ~/electrs/doc folder, there is a config_example.toml file. We need to copy that into the electrs folder and rename it to electrs.toml. This can be done by:

`cp ~/electrs/doc/config_example.toml ~/electrs/electrs.toml`

Now we need to edit the electrs.toml file in the ~electrs directory.

`nano ~/electrs/electrs.toml`

Take a look at the one below, make the necessary adjustments to username/password/db directory/electrum_rpc_address. Notice I've changed `cookie_file` it to `auth = bitcoin:bitcoin`

```
# DO NOT EDIT THIS FILE DIRECTLY - COPY IT FIRST!
# If you edit this, you will cry a lot during update and will not want to live anymore!

# This is an EXAMPLE of how configuration file should look like.
# Do NOT blindly copy this and expect it to work for you!
# If you don't know what you're doing consider using automated setup or ask an experienced friend.

# This example contains only the most important settings.
# See docs or electrs man page for advanced settings.

# File where bitcoind stores the cookie, usually file .cookie in its datadir
auth = "bitcoin:bitcoin"

# The listening RPC address of bitcoind, port is usually 8332
daemon_rpc_addr = "127.0.0.1:8332"

# The listening P2P address of bitcoind, port is usually 8333
daemon_p2p_addr = "127.0.0.1:8333"

# Directory where the index should be stored. It should have at least 70GB of free space.
db_dir = "/home/username/electrs/db"

# bitcoin means mainnet. Don't set to anything else unless you're a developer.
network = "bitcoin"

# The address on which electrs should listen. Warning: 0.0.0.0 is probably a bad idea!
# Tunneling is the recommended way to access electrs remotely.
electrum_rpc_addr = "0.0.0.0:50001"
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
electrum_rpc_addr = "0.0.0.0:50001"
electrum_rpc_addr = "127.0.0.1:50001"

Copy link
Contributor Author

@k3tan172 k3tan172 Nov 1, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is contentious because many are not running electrum on the same device they're running the electrum server in their home network. as per my understanding, setting this as 127.0.0.1 will only allow electrum to connect to electrs if they are on the same machine. if we allow 192.0.0.0, at least electrum on a different computer can connect (if on the same local network). but, if their IP addresses are 10.0.0.0, that won't connect - which leads me to putting it as 0.0.0.0 to cater for all scenarios.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SSH tunnel/VPN/Tor are more secure, why not use one of them?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because the overwhelmingly vast majority of people do not know how to set up ssh tunnel or VPN to their home network (either due to a lack of public facing IP address or network level knowledge). Tor is excruciatingly slow and unreliable.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand, same issues with public IPs or lack of knowledge apply to binding to 0.0.0.0. Documenting how to make SSH tunnel or THS shouldn't be too hard.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would love to see electrs.exe, electrs.dmg and electrs.deb files for users to double click and install their electrum server. This would mean Wallet > Electrs > Bitcoind can all run on localhost and most users can do away with binding issues.

I don't know where I'd even start on a document for a situation whereby a user is running Windows on a laptop outside the home network and can SSH back to their home electrum server to connect their Sparrow or Electrum wallet.


# How much information about internal workings should electrs print. Increase before reporting a bug.
verbose = 2
```

### Run electrs for the first time

`cd ~/electrs`
`./target/release/electrs`

Electrs should connect successfully to your bitcoind and start creating an index of all transactions in the db_dir you nominated in the electrs.toml file. It will take a while. Let it run. There will be lots of logs being created in your terminal.

You can stop at any time by pressing CTRL+C.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a stage when the DB is compacted (after the initial sync), during which electrs is unresponsive to CTRL+C :(
Not sure it worth mentioning here though...


### Autostart on boot

First create the service file
`sudo nano /etc/systemd/system/electrs.service`

Copy and paste the below. Edit the 'username' accordingly.

```
[Unit]
Description=Electrs
After=bitcoind.service
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it work if there is no bitcoind.service file?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it would work. I got this service file from config.md


[Service]
WorkingDirectory=/home/username/electrs
ExecStart=/home/username/electrs/target/release/electrs
User=username
Group=username
Type=simple
KillMode=process
TimeoutSec=60
Restart=always
RestartSec=60

[Install]
WantedBy=multi-user.target
```
CTRL+X then Y then ENTER to save and exit.

`sudo systemctl enable electrs`
`sudo systemctl start electrs`


### Upgrading

`cd ~/electrs`
`git pull origin master`
`sudo systemctl stop electrs`
`cargo build --locked --release`
`sudo systemctl start electrs`