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.

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

Conversation

k3tan172
Copy link
Contributor

@k3tan172 k3tan172 commented Nov 1, 2021

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.

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
Copy link
Owner

romanz commented Nov 1, 2021

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?

@romanz romanz self-requested a review November 1, 2021 11:30
doc/quickstart.md Show resolved Hide resolved
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


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


# 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

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.


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


[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

doc/quickstart.md Outdated Show resolved Hide resolved
@Kixunil
Copy link
Contributor

Kixunil commented Nov 1, 2021

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 <[email protected]>
@k3tan172
Copy link
Contributor Author

k3tan172 commented Nov 1, 2021

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
Copy link
Owner

romanz commented Nov 1, 2021

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!

@romanz romanz self-requested a review November 1, 2021 20:44
@Kixunil
Copy link
Contributor

Kixunil commented Nov 2, 2021

@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?

@romanz romanz removed their request for review November 2, 2021 10:24
@k3tan172
Copy link
Contributor Author

k3tan172 commented Nov 2, 2021

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
Copy link
Contributor

Kixunil commented Nov 2, 2021

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
Copy link
Contributor Author

k3tan172 commented Nov 2, 2021

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

@Kixunil
Copy link
Contributor

Kixunil commented Nov 2, 2021

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

@k3tan172
Copy link
Contributor Author

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
Copy link
Owner

romanz commented Nov 12, 2021

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

@romanz
Copy link
Owner

romanz commented Nov 12, 2021

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

@Kixunil
Copy link
Contributor

Kixunil commented Nov 12, 2021

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
Copy link
Contributor Author

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
Copy link
Contributor

Kixunil commented Nov 12, 2021

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
Copy link
Owner

romanz commented Nov 13, 2021

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants