Creating the quickstart guide #606

k3tan172 · 2021-11-01T08:21:13Z

Electrs is an incredibly critical piece of software and requires a quick and easy way to get up and running. I have written this guide for beginners hoping others can use it. Feedback welcome.

romanz · 2021-11-01T11:30:11Z

Many thanks for the kind words and your contribution!
Maybe we can use https://asciinema.org/ to prepare a short screencast that shows how to install and run electrs on a Linux machine? This way, beginner users will also have the commands' output available (which can help with troubleshooting).
@Kixunil WDYT?

doc/quickstart.md

romanz · 2021-11-01T11:32:25Z

doc/quickstart.md

+rpcallowip=172.0.0.0/8
+rpcallowip=192.0.0.0/8
+rpcuser=bitcoin
+rpcpassword=bitcoin


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

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

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

dojo, mempool.space

romanz · 2021-11-01T11:33:04Z

doc/quickstart.md

+
+### Install latest version of Rust
+
+`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`


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

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.

romanz · 2021-11-01T11:33:42Z

doc/quickstart.md

+
+# 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"


Suggested change

electrum_rpc_addr = "0.0.0.0:50001"

electrum_rpc_addr = "127.0.0.1:50001"

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.

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

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.

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.

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.

romanz · 2021-11-01T11:35:32Z

doc/quickstart.md

+
+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.


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...

romanz · 2021-11-01T11:36:10Z

doc/quickstart.md

+
+[Unit]
+Description=Electrs
+After=bitcoind.service


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

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

doc/quickstart.md

Kixunil · 2021-11-01T11:44:42Z

I can understand the appeal of making a guide that looks shorter than the full guide. The problem I see is this one teaches less secure practices and makes assumptions about things. Everyone trying it will have a different system/setup and will have things differently so it'll generate issues and making it more detailed would lead to our current guide.

I was actually seriously considering creating a web-based "install wizard"-style tutorial, where users would answer some questions (just in-browser) and it'd walk them through whole process.

Something like this:

Intro:

Install electrs
I already have electrs

Install electrs:

I use Debian 10
I use Nix
I use macOS
I use Windows

...

I hope you get the idea. This way people wouldn't be bothered by stuff that doesn't apply to their platform.

Co-authored-by: Roman Zeyde <git@romanzey.de>

k3tan172 · 2021-11-01T12:39:07Z

If you haven't seen it already, I have a guide on installing electrs on Ubuntu, you can view it here: https://www.youtube.com/watch?v=vGuxGTtHEYA

I'll probably do another video when Ubuntu 22.04LTS comes out to reflect any changes.

romanz · 2021-11-01T12:41:39Z

I have a guide on installing electrs on Ubuntu, you can view it here: https://www.youtube.com/watch?v=vGuxGTtHEYA

Wow, looks great - many thanks!

Kixunil · 2021-11-02T10:22:37Z

@k3tan172 since you're making videos about various node software, perhaps consider making one about Cryptoanarchy Debian Repository, which saves people lot of trouble with configuring electrs and a lot of other software while remaining highly secure?

k3tan172 · 2021-11-02T10:41:54Z

i prefer showing people how to take the software provided by various bitcoin project developers and building it up manually, instead of relying on others to package it. "Give a Man a Fish, and You Feed Him for a Day. Teach a Man To Fish, and You Feed Him for a Lifetime" type thing.
nevertheless, i'll try out your project when i get the chance.

Kixunil · 2021-11-02T10:58:43Z

Understandable and a great thing to learn. I did that for years too. After som time I found there's nothing more to learn by rebuilding same thing for 100th time and it's actually detrimental to security, so I made the packages. :)

k3tan172 · 2021-11-02T11:01:43Z

...and that's great, until a user is having issues, has no skills to troubleshoot and you're no longer around to help.

Kixunil · 2021-11-02T11:07:02Z

Sure, build those skills. Best of both worlds. :)

k3tan172 · 2021-11-12T09:58:50Z

The reason I created this quickstart guide is to get people up and running with electrs on their own machines. Unfortunately, it is already out of date and no longer works, giving an error:
Error: please use `log_filters` to set logging verbosity

This is because the sample config_example.toml file contains verbosity = 2.
Guide documentation has not been updated and the upgrade notes that relate to this does not provide a solution. I put log_filters = 1 (???) in my electrs.toml file based on the below, which caused an error. Removing verbosity = 2 from the config file works, but shows no output or logs.

Important changes from versions older than 0.9.3

    If you use verbose (or -v argument), switch to log_filters (or RUST_LOG environment variable). Please note that it allows to set per-module filters, but module naming is considered unstable.

I guess what I'm saying here is, you have a warning on the main page not to use community guides, citing 'various problems' and out of date information. Yet, the "official" guides don't yield a satisfactory outcome. They are all over the place and rather confusing. It weaves the reader through various options and links.

Electrs is a critical piece of software for various bitcoin wallets. Either let the community help you out with documentation, or spend considerably more time cleaning this up as a matter of priority.

Just my 2 sats. I'm not a dev, I'm not an expert, I'm just a user helping others use the software.

romanz · 2021-11-12T10:13:18Z

Sorry for the confusion (and the delayed response), will update the documentation.

romanz · 2021-11-12T10:21:05Z

I should have done it as a part of #615...

Kixunil · 2021-11-12T14:18:21Z

you have a warning on the main page not to use community guides, citing 'various problems' and out of date information. Yet, the "official" guides don't yield a satisfactory outcome.

We usually take care of this but surely, nobody's perfect. I should've caught this in the review, sorry. :(

The main reasons we have that warning is:

If you notify us of a problem, we fix it ASAP. (Compare to RaspiBolt which was outdated for a year I think and didn't react to PRs.)
We understand electrs deeply so we can suggest best possible approaches to solve problems.

They are all over the place and rather confusing.

Could you suggest changes that retain important information? Note that originally usage was shorter but over time as more and more issues popped up we had to add various clarifications to it. I think the only way out of this is having a big warning "we only support x86_64 Debian 11" and then optimize the guide for that. This would obviously make many people sad.

let the community help you out with documentation

AFAIR there never was a case when a relevant doc PR was rejected or stalled for a long time. Quite opposite, there were huge changes based on feedback from community.

k3tan172 · 2021-11-12T14:45:25Z

Could you suggest changes that retain important information? Note that originally usage was shorter but over time as more and more issues popped up we had to add various clarifications to it. I think the only way out of this is having a big warning "we only support x86_64 Debian 11" and then optimize the guide for that. This would obviously make many people sad.

This quickstart guide doc is my sincere attempt at a simple one pager that outlines to the user what to input into the command line to get electrs up and running. I'm not suggesting you change any of your existing documentation.

Kixunil · 2021-11-12T14:51:31Z

Sure, I'd still love to see it without the downsides. I think the best approach would be to have some kind of "dispatch wizard" that first figures out what system the user is running and what he wants then suggests best approach.

romanz · 2021-11-13T08:28:06Z

raspibolt/raspibolt#777 (comment)

Creating the quickstart guide

fe75ab0

Electrs is an incredibly critical piece of software and requires a quick and easy way to get up and running. I have written this guide for beginners hoping others can use it. Feedback welcome.

romanz self-requested a review November 1, 2021 11:30

romanz requested changes Nov 1, 2021

View reviewed changes

Update doc/quickstart.md

69454cc

Co-authored-by: Roman Zeyde <git@romanzey.de>

romanz self-requested a review November 1, 2021 20:44

romanz removed their request for review November 2, 2021 10:24

This was referenced Nov 12, 2021

Fixup --log-filters documentation and examples #618

Closed

Prepare an "asciinema" screencast for a quickstart installation #619

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Creating the quickstart guide #606

Creating the quickstart guide #606

k3tan172 commented Nov 1, 2021

romanz commented Nov 1, 2021 •

edited

romanz Nov 1, 2021

k3tan172 Nov 1, 2021

Kixunil Nov 2, 2021

k3tan172 Nov 2, 2021

romanz Nov 1, 2021

k3tan172 Nov 1, 2021

romanz Nov 1, 2021

k3tan172 Nov 1, 2021 •

edited

Kixunil Nov 2, 2021

k3tan172 Nov 2, 2021

Kixunil Nov 12, 2021

k3tan172 Nov 12, 2021

romanz Nov 1, 2021

romanz Nov 1, 2021

k3tan172 Nov 1, 2021

Kixunil commented Nov 1, 2021

k3tan172 commented Nov 1, 2021

romanz commented Nov 1, 2021 •

edited

Kixunil commented Nov 2, 2021

k3tan172 commented Nov 2, 2021

Kixunil commented Nov 2, 2021

k3tan172 commented Nov 2, 2021

Kixunil commented Nov 2, 2021

k3tan172 commented Nov 12, 2021

romanz commented Nov 12, 2021

romanz commented Nov 12, 2021 •

edited

Kixunil commented Nov 12, 2021

k3tan172 commented Nov 12, 2021

Kixunil commented Nov 12, 2021

romanz commented Nov 13, 2021


		### Install latest version of Rust

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

	electrum_rpc_addr = "0.0.0.0:50001"
	electrum_rpc_addr = "127.0.0.1:50001"


		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.

Creating the quickstart guide #606

Are you sure you want to change the base?

Creating the quickstart guide #606

Conversation

k3tan172 commented Nov 1, 2021

romanz commented Nov 1, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

k3tan172 Nov 1, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kixunil commented Nov 1, 2021

k3tan172 commented Nov 1, 2021

romanz commented Nov 1, 2021 • edited

Kixunil commented Nov 2, 2021

k3tan172 commented Nov 2, 2021

Kixunil commented Nov 2, 2021

k3tan172 commented Nov 2, 2021

Kixunil commented Nov 2, 2021

k3tan172 commented Nov 12, 2021

romanz commented Nov 12, 2021

romanz commented Nov 12, 2021 • edited

Kixunil commented Nov 12, 2021

k3tan172 commented Nov 12, 2021

Kixunil commented Nov 12, 2021

romanz commented Nov 13, 2021

romanz commented Nov 1, 2021 •

edited

k3tan172 Nov 1, 2021 •

edited

romanz commented Nov 1, 2021 •

edited

romanz commented Nov 12, 2021 •

edited