diff --git a/ENV-NOTES b/ENV-NOTES new file mode 100644 index 0000000..14ab73a --- /dev/null +++ b/ENV-NOTES @@ -0,0 +1,70 @@ +The following environment variables are required: + +DB_DIRECTORY - path to the database directory (if relative, to `run` script) +USERNAME - the username the server will run as if using `run` script +ELECTRUMX - path to the electrumx_server.py script (if relative, + to `run` script) +DAEMON_URL - the URL used to connect to the daemon. Should be of the form + http://username:password@hostname:port/ + Alternatively you can specify DAEMON_USERNAME, DAEMON_PASSWORD, + DAEMON_HOST and DAEMON_PORT. DAEMON_PORT is optional and + will default appropriately for COIN. + +The other environment variables are all optional and will adopt +sensible defaults if not specified. + +COIN - see lib/coins.py, must be a coin NAME. Defaults to Bitcoin. +NETWORK - see lib/coins.py, must be a coin NET. Defaults to mainnet. +DB_ENGINE - database engine for the transaction database. Default is + leveldb. Supported alternatives are rocksdb and lmdb. + You will need to install the appropriate python packages. + Not case sensitive. +REORG_LIMIT - maximum number of blocks to be able to handle in a chain + reorganisation. ElectrumX retains some fairly compact + undo information for this many blocks in levelDB. + Default is 200. +HOST - the host that the TCP and SSL servers will use. Defaults to + localhost. +TCP_PORT - if set will serve Electrum TCP clients on that HOST:TCP_PORT +SSL_PORT - if set will serve Electrum SSL clients on that HOST:SSL_PORT + If set, SSL_CERTFILE and SSL_KEYFILE must be filesystem paths. +RPC_PORT - Listen on this port for local RPC connections, defaults to + 8000. +BANNER_FILE - a path to a banner file to serve to clients. The banner file + is re-read for each new client. +DONATION_ADDRESS - server donation address. Defaults to none. +ANON_LOGS - set to remove IP addresses from logs. Default: disabled + +If you want IRC connectivity to advertise your node: + +IRC - set to anything non-empty +IRC_NICK - the nick to use when connecting to IRC. The default is a + hash of REPORT_HOST. Either way 'E_' will be prepended. +REPORT_HOST - the host to advertise. Defaults to HOST. +REPORT_SSL_PORT - the SSL port to advertise. Defaults to SSL_PORT. +REPORT_TCP_PORT - the TCP port to advertise. Defaults to TCP_PORT. + +If synchronizing from the Genesis block your performance might change +by tweaking the following cache variables. Cache size is only checked +roughly every minute, so the caches can grow beyond the specified +size. Also the Python process is often quite a bit fatter than the +combined cache size, because of Python overhead and also because +leveldb consumes a lot of memory during UTXO flushing. So I recommend +you set the sum of these to nothing over half your available physical +RAM: + +HIST_MB - amount of history cache, in MB, to retain before flushing to + disk. Default is 300; probably no benefit being much larger + as history is append-only and not searched. + +UTXO_MB - amount of UTXO and history cache, in MB, to retain before + flushing to disk. Default is 1000. This may be too large + for small boxes or too small for machines with lots of RAM. + Larger caches generally perform better as there is + significant searching of the UTXO cache during indexing. + However, I don't see much benefit in my tests pushing this + too high, and in fact performance begins to fall. My + machine has 24GB RAM; the slow down is probably because of + leveldb caching and Python GC effects. However this may be + very dependent on hardware and you may have different + results. diff --git a/HOWTO.rst b/HOWTO.rst index ad468c1..3f3fa5a 100644 --- a/HOWTO.rst +++ b/HOWTO.rst @@ -102,17 +102,17 @@ Then copy the all sample scripts from the ElectrumX source tree there:: cp -R /path/to/repo/electrumx/samples/scripts ~/scripts/electrumx -This copies 4 things: the top level server run script, a log/ directory -with the logger run script, an env/ directory, and a NOTES file. +This copies 3 things: the top level server run script, a log/ directory +with the logger run script, an env/ directory. You need to configure the environment variables under env/ to your -setup, as explained in NOTES. ElectrumX server currently takes no -command line arguments; all of its configuration is taken from its -environment which is set up according to env/ directory (see 'envdir' -man page). Finally you need to change the log/run script to use the -directory where you want the logs to be written by multilog. The -directory need not exist as multilog will create it, but its parent -directory must exist. +setup, as explained in docs/ENV-NOTES. ElectrumX server currently +takes no command line arguments; all of its configuration is taken +from its environment which is set up according to env/ directory (see +'envdir' man page). Finally you need to change the log/run script to +use the directory where you want the logs to be written by multilog. +The directory need not exist as multilog will create it, but its +parent directory must exist. Now start the 'svscan' process. This will not do much as the service directory is still empty:: @@ -143,7 +143,7 @@ The sample unit file assumes that the repository is located at change the unit file accordingly. You need to set a few configuration variables in :code:`/etc/electrumx.conf`, -see `samples/NOTES` for the list of required variables. +see `docs/ENV-NOTES` for the list of required variables. Now you can start ElectrumX using :code:`systemctl`:: @@ -172,7 +172,7 @@ machine doing the indexing is focussing on the one task and not the wider network. The HIST_MB and CACHE_MB environment variables control cache sizes -before they spill to disk; see the NOTES file under samples/scripts. +before they spill to disk; see the ENV-NOTES file under docs/. Here is my experience with the current codebase, to given heights and rough wall-time::