Merge remote-tracking branch 'kixunil/update_docs'

Cargo.toml

@@ -13,7 +13,7 @@ edition = "2018"
 build = "build.rs"
 
 [package.metadata.configure_me]
-spec = "config_spec.toml"
+spec = "internal/config_specification.toml"
 
 [profile.release]
 lto = true

doc/config_example.toml

@@ -0,0 +1,36 @@
+# 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.
+
+# Set if you have low-memory device (such as RPi) or you run electrs under a different user than bitcoind and do NOT have sysperms in bitcoind.
+jsonrpc_import = true
+
+# File where bitcoind stores the cookie, usually file .cookie in its datadir
+cookie_file = "/var/run/bitcoin-mainnet/cookie"
+
+# Prefer cookie file unless you have btc-rpc-proxy or a good reason to use username:password
+# cookie and cookie_file can NOT be specified at the same tie.
+# cookie = "username:password"
+
+# The listening address of bitcoind, port is usually 8332
+daemon_rpc_addr = "127.0.0.1:8332"
+
+# Directory where the index should be stored. It should have at least 70GB of free space.
+db_dir = "/some/fast/storage/with/big/size"
+
+# 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 = "127.0.0.1:50001"
+
+# How much information about internal workings should electrs print. Increase before reporting a bug.
+verbosity = 3
+

doc/usage.md

@@ -87,6 +87,9 @@ $ cd electrs
 
 ### Build
 
+Note: you need to have enough free RAM to build `electrs`. The build will fail otherwise.
+Close those 100 old tabs in the browser. ;)
+
 #### Static linking
 
 First build should take ~20 minutes:
@@ -171,7 +174,10 @@ Electrs can be configured using command line, environment variables and configur
 
 ### Configuration files and priorities
 
-The config files must be in the Toml format. These config files are (from lowest priority to highest): `/etc/electrs/config.toml`, `~/.electrs/config.toml`, `./electrs.toml`.
+The config files must be in the Toml format.
+If you've never seen a Toml configuration file, there's an [example configuration file](config_example.toml) available.
+
+The config files are (from lowest priority to highest): `/etc/electrs/config.toml`, `~/.electrs/config.toml`, `./electrs.toml`.
 
 The options in highest-priority config files override options set in lowest-priority config files. Environment variables override options in config files and finally arguments override everythig else. There are two special arguments `--conf` which reads the specified file and `--conf-dir`, which read all the files in the specified directory. The options in those files override **everything that was set previously, including arguments that were passed before these arguments**. In general, later arguments override previous ones. It is a good practice to use these special arguments at the beginning of the command line in order to avoid confusion.
 
@@ -383,3 +389,42 @@ For more complex tasks, you may need to convert addresses to
 $ ./contrib/addr.py 144STc7gcb9XCp6t4hvrcUEKg9KemivsCR  # sample address from block #640699
 144STc7gcb9XCp6t4hvrcUEKg9KemivsCR has {'confirmed': 12652436, 'unconfirmed': 0} satoshis
 ```
+
+## Upgrading
+
+As with any other application, you need to remember how you installed `electrs` to upgrade it.
+If you don't then here's a little help: run `which electrs` and compare the output
+
+* If you got an error you didn't install `electrs` into your system in any way, it's probably sitting in the `target/release` directory of source
+* If the path starts with `/bin/` then either you have used packaging system or you made a mistake the first time (non-packaged binaries must go to `/usr/local/bin`)
+* If the path starts with `/usr/local/bin` you most likely copied electrs there after building
+* If the path starts with `/home/YOUR_USERNAME/.cargo/bin` you most likely ran `cargo install`
+
+### Upgrading distribution package
+
+If you used Debian packaging system you only need this:
+
+```
+sudo apt update
+sudo apt upgrade
+```
+
+Similarly for other distributions - use their respective commands.  
+If a new version of `electrs` is not yet in the package system, try wait a few days or contact the maintainers of the packages if it's been a long time.
+
+### Upgrading manual installation
+
+1. Enter your `electrs` source directory, usually in `~/` but some people like to put it in something like `~/sources`.
+   If you've deleted it, you need to `git clone` again.
+2. `git checkout master`
+3. `git pull`
+4. Strongly recommended: `git verify-tag v0.8.6` (fix the version number if we've forgotten to update this docs ;)) should show "Good signature from 15C8 C357 4AE4 F1E2 5F3F 35C5 87CA E5FA 4691 7CBB"
+5. `git checkout v0.8.6`
+6. If you used static linking: `cargo build --locked --release`.
+   If you used dynamic linking `ROCKSDB_INCLUDE_DIR=/usr/include ROCKSDB_LIB_DIR=/usr/lib cargo build --locked --no-default-features --release`.
+   If you don't remember which linking you used, you probably used static.
+   This step will take a few tens of minutes (but dynamic linking is a bit faster), go grab a coffee.
+   Also remember that you need enough free RAM, the build will die otherwise
+7. If you've previously copied `electrs` into `/usr/local/bin` run: sudo `cp target/release/electrs /usr/local/bin`
+   If you've previously installed `electrs` using `cargo install`: `cargo install --locked --path . -f`
+8. If you've manually configured systemd service: `sudo systemctl restart electrs`

internal/README.md

@@ -0,0 +1,3 @@
+# electrs-internal files
+
+**Nothing for users here, just for developers. ;)**