romanz
Creating the quickstart guide
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.
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?
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.
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.
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!
@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?
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.
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. :)
...and that's great, until a user is having issues, has no skills to troubleshoot and you're no longer around to help.
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.
Sorry for the confusion (and the delayed response), will update the documentation.
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.
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.
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.