diff --git a/LICENSE b/LICENSE
index 89de354..d7ea187 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,3 +1,7 @@
+The MIT License (MIT)
+
+Copyright 2018 Nadav Ivgi
+
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
diff --git a/README.md b/README.md
index df5202b..d52e525 100644
--- a/README.md
+++ b/README.md
@@ -1,47 +1,67 @@
# Spark Lightning Wallet
-A minimalistic wallet GUI for [c-lightning](https://github.com/ElementsProject/lightning),
-accessible over the web or through mobile and desktop apps.
-
[![npm release](https://img.shields.io/npm/v/spark-wallet.svg)](https://www.npmjs.com/package/spark-wallet)
[![docker release](https://img.shields.io/docker/pulls/shesek/spark.svg)](https://hub.docker.com/r/shesek/spark)
[![MIT license](https://img.shields.io/github/license/elementsproject/spark.svg)](https://github.com/elementsproject/spark/blob/master/LICENSE)
[![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
-[![IRC](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)](https://webchat.freenode.net/?channels=c-lightning)
+[![IRC](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)](https://webchat.freenode.net/?channels=spark-wallet)
:zap: Simple & minimalistic
:zap: Purely off-chain
:zap: Near-zero configuration
:zap: Progressive Web App
-:zap: Cordova and Electron builds
:zap: Personalizable themes
-:zap: Automatic self-signed certs
+:zap: Mobile and desktop apps
+:zap: Automatic self-signed TLS
:zap: LetsEncrypt integration
:zap: Tor hidden service (v3)
:zap:
------
+![Spark screenshot](https://user-images.githubusercontent.com/877904/44296418-74688a80-a2c7-11e8-8dba-08a017eceb11.png)
+
+## Contents
+
+- [Introduction](#introduction)
+- [Server installation](#server-installation) (for web access)
+- [Desktop apps](#desktop-apps) (for Linux, macOS and Windows)
+- [Mobile app](#mobile-app) (for Android, iOS coming soon)
+- [Progressive Web App](#progressive-web-app)
+- [GUI controls](#gui-controls)
+- [Browser support](#browser-support)
+- [Developing](#developing)
+- [Code signing & reproducible builds](#code-signing--reproducible-builds)
+- [CLI options](#cli-options)
+
+## Introduction
+
+Spark is a minimalistic wallet GUI for c-lightning, accessible over the web or
+through mobile and desktop apps (for Android, Linux, macOS and Windows).
+It is currently aimed for technically oriented users and is not an all-in-one package,
+but rather a "remote control" interface for a c-lightning node that has to be managed separately.
+
+Spark currently focuses on the core aspects of day-to-day usage: sending, receiving and viewing history.
+Peers and channels are expected to be managed using the RPC for now.
-
-
-
-
-
-
-
+Spark is a purely off-chain wallet, with no on-chain payments.
+This allows Spark to fully realize the awesome UX enabled by lightning,
+without worrying about the complications and friction of on-chain.
+This might change someday.
+
+Spark has a responsive UI suitable for mobile, tablet and desktop devices,
+but is best optimized for use on mobile.
> ⚠️ Spark is alpha-quality software under active development.
> Please use with care, preferably on testnet or with insignificant amounts.
-> Spark comes with no guarantees and with support on a best-effort basis.
+> Spark comes with no guarantees, use at your own risk.
+
+Big shout out to [Blockstream](https://blockstream.com) for generously sponsoring this work!
-## Installation
+## Server installation
-Spark requires a running [c-lightning](https://github.com/ElementsProject/lightning) node
+Requires a running [c-lightning](https://github.com/ElementsProject/lightning) node
(see setup instructions in [the official docs](https://github.com/ElementsProject/lightning/blob/master/doc/INSTALL.md)
or [this tutorial](https://hackernoon.com/harnessing-lightning-for-instant-bitcoin-transacting-a-tutorial-3b9dcdc00552))
-and nodejs (v6.0 or newer).
-
-Once c-lightning is running, install and start Spark (on the same machine) with:
+and nodejs v6.0 or newer (v8 is recommended, see [instructions here](https://nodejs.org/en/download/package-manager/)).
```bash
# $ npm install -g spark-wallet
@@ -51,25 +71,16 @@ $ npm install -g git+ssh://git@github.com:ElementsProject/spark#dist
$ spark-wallet # defaults: --ln-path ~/.lightning --port 9737
```
-Or simply `$ npx spark-wallet`, which will install and start Spark in one go.
-This should normally Just Work ™.
+Or simply `$ npx spark-wallet`, which will install and start Spark (with the default args) in one go.
Spark will generate and print a random username and password that'll be used to login into the wallet.
To specify your own login credentials, set `--login [user]:[pass]` or the `LOGIN` environment variable.
To access the wallet, open `http://localhost:9737/` in your browser and login with the username/password.
-To accept remote connections, set `--host ` (shorthand `-i`, e.g. `-i 0.0.0.0`).
-This will automatically enable TLS ([more details below](#tls)).
+See `$ spark-wallet --help` for the full list of command-line options (also available under [*CLI options*](#cli-options)).
-Spark can also be accessed using mobile and desktop apps instead of through the browser.
-See [*Mobile app (Cordova)*](#mobile-app-cordova) and [*Desktop app (Electron)*](#desktop-app-electron)
-for more details.
-Note that the desktop app comes bundled with the Spark server and doesn't require the manual server setup described here.
-
-See `$ spark-wallet --help` for the full list of available options (also available under [*CLI options*](#cli-options)).
-
-### Configuration file
+#### Configuration file
Spark reads configuration options from `~/.spark-wallet/config` (can be overridden with `--config/-c `).
The expected format is one `key=value` per line, like so:
@@ -80,189 +91,100 @@ login=bob:superSecretPassword
port=8000
```
-### Deploy with Docker
+#### Connecting remotely
-Spark is also available as a Docker image that comes bundled with bitcoind and c-lightning.
-See [`doc/docker.md`](https://github.com/ElementsProject/spark/blob/master/doc/docker.md) for more details.
+To accept remote connections, set `--host ` (shorthand `-i`, e.g. `-i 0.0.0.0`).
+This will automatically enable TLS with a self-signed certificate.
-## Features
+For more information on TLS, instructions for setting up a CA-signed certificate using the built-in LetsEncrypt integration
+and for adding the self-signed certificate to Android,
+see [`doc/tls.md`](https://github.com/ElementsProject/spark/blob/master/doc/tls.md).
-Spark currently focuses on the core aspects of day-to-day usage: sending, receiving and viewing history.
-Peers and channels are expected to be managed using the RPC for now.
+To start Spark as a Tor hidden service, set `--onion`. You don't need Tor pre-installed for this to work.
+See [`doc/onion.md`](https://github.com/ElementsProject/spark/blob/master/doc/onion.md) for more details,
+the advantages of using an hidden service, and instructions for connecting from Android.
+*This is highly recommended.*
-Spark is a purely off-chain wallet, with no on-chain payments.
-This allows Spark to fully realize the awesome UX enabled by lightning,
-without worrying about the complications and friction of on-chain.
-This might change someday.
+#### Deploy with Docker
-Spark has a responsive UI suitable for mobile, tablet and desktop devices,
-but is best optimized for use on mobile.
+Spark is also available as a Docker image that comes bundled with bitcoind and c-lightning.
+See [`doc/docker.md`](https://github.com/ElementsProject/spark/blob/master/doc/docker.md) for details.
-### Controls
+#### Adding to startup with `systemd`
-- **Display unit:** Click the balance on the top-right or the unit in the "request payment" page to toggle the currency display unit.
- The available options are sat, bits, milli, btc and usd.
+See [`doc/startup-systemd.md`](https://github.com/ElementsProject/spark/blob/master/doc/startup-systemd.md).
-- **Theme switcher:** Click the theme name on the bottom-right to change themes (you can choose between over 15 [bootswatch](https://bootswatch.com) themes).
+## Desktop apps
-- **Collapse payments:** Click on payments in the list to display more details.
+Electron-based desktop apps for Linux (packaged as `deb`, `AppImage`, `snap` and `tar.gz`),
+macOS (as `zip`) and Windows (installer and a portable) are available for download from the
+[releases page](https://github.com/ElementsProject/spark/releases).
-- **Expert mode:** Click the version number on the bottom-left to toggle expert mode.
- This will add [two new menu items](https://user-images.githubusercontent.com/877904/43125383-89ac19b4-8f32-11e8-9a5e-d91eb5a637ea.png), "*Logs*" and
- ["*RPC Console*"](https://user-images.githubusercontent.com/877904/43122285-3854be8a-8f29-11e8-9329-d4c5c881c5e2.png),
- and display yaml dumps with additional information throughout the app.
+The desktop apps comes bundled with the Spark server-side component. If you're connecting to a local
+c-lightning instance, you [can configure](https://user-images.githubusercontent.com/877904/44290659-5c224c80-a282-11e8-9433-bb442f11ca88.png)
+the desktop app to connect to it directly without manually setting up the Spark server.
-### Browser support
+Connecting to a remote c-lightning instance requires setting up the Spark server on the same machine
+running c-lightning and connecting through it.
-Supported on recent desktop and mobile version of Chrome, Firefox and Safari.
+## Mobile app
-Requires iOS 11+ for WebRTC (used by the QR scanner), but works otherwise with iOS 9+.
-Chrome on iOS does not support WebRTC.
+A Cordova-based native app for Android is available for download from the
+[releases page](https://github.com/ElementsProject/spark/releases) (`spark-wallet-[x.y.z]-android.apk`).
+It is not currently published to the app store.
-Untested on IE.
+The app requires a Spark server to communicate with, which you need [to setup](#server-installation) as a prerequisite.
+
+When the app starts for the first time, you'll need to configure your Spark server URL and API access key.
+You can print your access key to the console by starting Spark with `--print-key/-k`.
+You can also scan this information from a QR, which you can get with `--pairing-qr/-Q`.
+
+For the native app to properly communicate with the server, the TLS certificate has to be
+[signed by a CA](https://github.com/ElementsProject/spark/blob/master/doc/tls.md#letsencrypt-integration)
+or manually [added as a user trusted certificate](https://github.com/ElementsProject/spark/blob/master/doc/tls.md#add-as-trusted-certificate-to-android).
## Progressive Web App
-You can install Spark as a [PWA](https://developer.mozilla.org/en-US/Apps/Progressive) to get a more native-app-like experience,
-including an home launcher that opens up in full screen, system notifications and improved page load times.
+You can install Spark as a [PWA](https://developer.mozilla.org/en-US/Apps/Progressive) (on mobile and desktop) to get a more native-app-like experience,
+including an home launcher that opens up in full screen, system notifications and faster load times.
Available in Chrome mobile under `⋮` -> `Add to homescreen` ([see here](https://imgur.com/zVe1sOH)),
in Chrome desktop under `More tools` -> `Install to desktop` ([see here](https://i.imgur.com/Pj6FpGA.png))
and in Firefox mobile with an icon next to the address bar ([see here](https://mdn.mozillademos.org/files/15762/add-to-home-screen-icon.png)).
-iOS has a [bug](https://github.com/webrtc/samples/issues/933) [preventing](https://stackoverflow.com/questions/46228218/how-to-access-camera-on-ios11-home-screen-web-app/46350136)
-PWAs from using WebRTC (used by the QR scanner), but it works otherwise.
-The QR scanner works if you access Spark without using the "Add to homescreen" feature.
-
-Note that installing the PWA on Android requires the TLS certificate to be signed by a CA
-or manually added as a user trusted certificate ([instructions below](#add-as-trusted-certificate-to-android)).
+Installing the PWA requires TLS and a [CA-signed certificate](https://github.com/ElementsProject/spark/blob/master/doc/tls.md#letsencrypt-integration).
-Compared to the PWA, the main advantages of the mobile and desktop apps (below) are
+Compared to the PWA, the main advantages of the mobile and desktop apps are
the ability to handle `lightning:` URIs,
better security sandbox (detached from the browser)
and static client-side code.
-## Mobile app (Cordova)
-
-A Cordova-based native app for Android is available for download from the
-[releases page](https://github.com/ElementsProject/spark/releases) (`spark.apk`).
-It is not currently published to the app store.
-
-When the app starts for the first time, you'll need to configure your Spark server URL and API access key.
-You can print your access key to the console by starting Spark with `--print-key/-k`.
-You can also scan this information from a QR, which you can get with `--pairing-qr/-Q`.
-
-For the native app to properly communicate with the server, the TLS certificate has to be signed by a CA,
-or manually added as a user trusted certificate ([instructions below](#add-as-trusted-certificate-to-android)).
-
-## Desktop app (Electron)
-
-Electron-based desktop apps for Linux (packaged as `AppImage`, `deb`, `snap` and `tar.gz`),
-OS X and Windows are available for download from the
-[releases page](https://github.com/ElementsProject/spark/releases).
-
-The desktop app comes bundled with the Spark server-side component. If you're connecting to a local
-c-lightning instance, you can configure the client to connect to it directly without manually setting-up
-the Spark server.
-
-Connecting to a remote c-lightning instance requires setting up the Spark server on the same machine
-running c-lightning and connecting through it.
-
-## TLS
-
-Spark will by default generate a self-signed certificate and enable TLS when binding on a non-`localhost` address.
-
-The self-signed certificate and key material will be saved to `~/.spark-wallet/tls/`.
-To save to a different location, set `--tls-path`.
-To set a custom "common name" for the generated certificate, set `--tls-name` (defaults to the value of `--host`).
-
-To use your own TLS key and certificate, put your `key.pem` and `cert.pem` files in the `--tls-path` directory.
-
-To disable TLS and start a plaintext HTTP server instead, set `--no-tls`.
-Note that without TLS, Chrome will not allow accessing the camera on non-`localhost` hosts.
-
-To enable TLS even for `localhost`, set `--force-tls`.
-
-#### LetsEncrypt integration
-
-Setting `--letsencrypt ` will automatically register a CA-signed certificate using LetsEncrypt.
-This will make your certificate work everywhere without self-signed warnings.
-
-`$ spark-wallet --host mydomain.com --letsencrypt webmaster@mydomain.com`
-
-Requires a domain name, cannot be used with IP addresses.
-If your domain is different from the host you're binding on, set `--tls-name`
-(e.g. `--host 0.0.0.0 --tls-name mydomain.com`).
-
-Note that verifying domain ownership requires binding an HTTP server on port 80, which normally requires root permissions.
-You can either:
-
-1. Start `spark-wallet` as root (simplest, but not recommended).
-2. Use `setcap` to allow nodejs processes to bind on all ports: `$ sudo setcap 'cap_net_bind_service=+ep' $(which node)`
-3. Bind the verification server to a different port with `--le-port 8080` (any port >1024 will work),
- then forward port 80 to it with `$ sudo iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080`.
-
-After initially verifying your domain, you may start Spark with `--le-noverify` to skip starting the verification server.
-This will work until the next renewal is due (every 90 days).
-
-If you're having troubles, set `--le-debug` to show more debug information.
-
-#### Add as Trusted Certificate to Android
+**Note for iOS users:** iOS [does](https://github.com/webrtc/samples/issues/933) [not](https://stackoverflow.com/questions/46228218/how-to-access-camera-on-ios11-home-screen-web-app/46350136)
+allow PWAs to use WebRTC (required for the QR scanner), but it works otherwise.
+The QR scanner works if you access Spark without using the PWA "Add to homescreen" feature.
-To avoid the self-signed certificate warnings (without a CA), you can add the certificate to your Android's "user trusted certificates"
-by following these steps:
+## GUI controls
-1. Open Spark in your mobile web browser (skipping the warning).
-2. Click the red TLS warning in the URL bar to view the certificate and ensure it matches the expected one
- (the certificate's SHA1 fingerprint is printed to the console during Spark's startup).
-3. Navigate to `/cert.pem` to download the certificate file from the server and open it.
-4. You should now see [this screen](https://i.imgur.com/f2DMWdL.png), allowing you to add a user trusted certificate.
- Fill in a name (e.g. "Spark"), leave "Used for" on "VPN and apps", and click OK.
-
-Note that adding a user trusted certificate causes android to display a "Network may be monitored" notification.
-It can be flicked off.
-
-## Tor Onion Hidden Service
-
-To start Spark as a Tor hidden service (v3), set `--onion`.
-Spark will install Tor automatically (via [granax](https://github.com/bookchin/granax));
-you don't have to pre-install anything for this to work.
-
-Running Spark as a Tor hidden service has the following benefits:
-
-- Tor onion URLs are self-authenticating and are pinned to your server's public key.
-- In addition to authenticating the server, they also serve as a mean to authenticate the user - you can't access the server without knowing the `.onion` hostname.
-- You don't have to setup port forwarding, everything is done with outbound connections.
-
-Tor data files (including secret key material for the hidden service) will be saved to `~/.spark-wallet/tor/`. This can be overridden with `--onion-path`.
-
-#### Connecting from Android
+- **Display unit:** Click the balance on the top-right or the unit in the "request payment" page to toggle the currency display unit.
+ The available options are sat, bits, milli, btc and usd.
-To connect to your hidden service using a web browser, install the
-[Orbot](https://guardianproject.info/apps/orbot/) and [Orfox](https://guardianproject.info/apps/orfox/)
-applications, open the `.onion` URL in Orfox, and enable JavaScript under `⋮` -> `NoScript`.
+- **Theme switcher:** Click the theme name on the bottom-right to change themes (you can choose between over 15 [bootswatch](https://bootswatch.com) themes).
-To connect using the Cordova app, configure Orbot to route Spark's traffic over the Tor VPN
-(under "Tor-Enabled Apps"), then configure Spark to use the `.onion` server URL.
+- **Collapse payments:** Click on payments in the list to display more details.
-Instead of manually copying the `.onion` URL, you may want to specify `--print-qr/-q` to print
-the URL as a QR to the console, or `--pairing-qr/-Q` to also include the access key.
+- **Expert mode:** Click the version number on the bottom-left to toggle expert mode.
+ This will add [two new menu items](https://user-images.githubusercontent.com/877904/44295422-37919900-a2b1-11e8-93b1-9220cdfc113a.png), "*Logs*" and
+ ["*RPC Console*"](https://user-images.githubusercontent.com/877904/44295439-7fb0bb80-a2b1-11e8-8506-f5afb1c9f1d7.png),
+ and display yaml dumps with additional information throughout the app.
-## Adding to startup with `systemd`
+## Browser support
-```bash
-# set config options in ~/.spark-wallet/config
-$ echo login=bob:superSecretPass123 | tee -a ~/.spark-wallet/config
+Supported on recent desktop and mobile version of Chrome, Firefox and Safari.
+IE is unsupported.
-# create service file from template
-$ curl -s https://raw.githubusercontent.com/ElementsProject/spark/master/scripts/spark-wallet.service |
- sed "s~{cmd}~`which spark-wallet`~;s~{user}~`whoami`~" |
- sudo tee /etc/systemd/system/spark-wallet.service
+Requires iOS 11+ for WebRTC (used by the QR scanner), but works otherwise with iOS 9+.
+Chrome on iOS does not support WebRTC.
-# inspect the generated service file, then load and start the service with:
-$ sudo systemctl daemon-reload
-$ sudo systemctl enable spark-wallet && sudo systemctl start spark-wallet
-```
## Developing
@@ -287,7 +209,7 @@ To get more verbose output in the browser developer console, set `localStorage.d
Pull requests, suggestions and comments and welcome!
-## Code signing & Reproducible builds
+## Code signing & reproducible builds
Signed distribution checksums are available in the git repo at
[`SHA256SUMS.asc`](https://github.com/ElementsProject/spark/blob/master/SHA256SUMS.asc)
@@ -302,15 +224,14 @@ The public key can be verified on [keybase](https://keybase.io/nadav),
[HN](https://news.ycombinator.com/user?id=nadaviv)
or on [a domain he's known to control](https://www.bitrated.com/.keys/staff/nadav.asc).
-To install the signed NPM package, rather than downloading it from the NPM registry, download it from
+To install the signed NPM package, download it from
[the releases page](https://github.com/ElementsProject/spark/releases), verify the hash
-and install using `$ npm install -g spark-wallet-[x.y.z]-npm.tgz`,
-or install it from a signed git commit hash using `$ npm install -g github:ElementsProject/spark#[commit-hash-verified-to-be-signed]`.
+and install using `$ npm install -g spark-wallet-[x.y.z]-npm.tgz`.
To install the signed Docker image, get the image hash from `SHA256SUMS.asc` and install it with
`$ docker pull shesek/spark@sha256:[image-hash-verified-by-be-signed]`.
-The distribution checksums for the NPM package, Android `apk` builds, Linux `tar.gz`/`deb`/`snap` builds, macOS `zip` builds and Windows builds (installer and portable)
+The NPM package, Android `apk` builds, Linux `tar.gz`/`deb`/`snap` builds, macOS `zip` builds and Windows builds (installer and portable)
[are deterministically reproducible](https://github.com/ElementsProject/spark/blob/master/doc/reproducible-builds.md).
## CLI options
@@ -326,9 +247,9 @@ $ spark-wallet --help
Options
-l, --ln-path path to c-lightning data directory [default: ~/.lightning]
-u, --login http basic auth login, "username:password" format [default: generate random]
-
-p, --port http(s) server port [default: 9737]
-i, --host http(s) server listen address [default: localhost]
+ --no-webui run API server without serving client assets [default: false]
--force-tls enable TLS even when binding on localhost [default: enable for non-localhost only]
--no-tls disable TLS for non-localhost hosts [default: false]
@@ -336,13 +257,12 @@ $ spark-wallet --help
--tls-name common name for the TLS cert [default: {host}]
--letsencrypt enable CA-signed certificate via LetsEncrypt [default: false]
- -o, --onion start Tor Hidden Service (v3) [default: false]
- -O, --onion-path directory to read/store hidden service data [default: ~/.spark-wallet/tor/]
-
-k, --print-key print access key to console (for use with the Cordova/Electron apps) [default: false]
-q, --print-qr print QR code with the server URL [default: false]
-Q, --pairing-qr print QR code with embedded access key [default: false]
- --no-webui run API server without serving client assets [default: false]
+
+ -o, --onion start Tor Hidden Service (v3) [default: false]
+ -O, --onion-path directory to read/store hidden service data [default: ~/.spark-wallet/tor/]
-c, --config path to config file [default: ~/.spark-wallet/config]
-V, --verbose display debugging information [default: false]
@@ -358,4 +278,4 @@ $ spark-wallet --help
## License
-MIT
+[MIT](https://github.com/ElementsProject/spark/blob/master/LICENSE)
diff --git a/doc/docker.md b/doc/docker.md
index 07b7db5..cad649b 100644
--- a/doc/docker.md
+++ b/doc/docker.md
@@ -3,7 +3,7 @@
You can use Docker To setup Spark, a bitcoind node and a c-lightning node all in go with the following command:
```bash
-$ docker run -v $HOME/.spark-docker:/data -p 9737:9737 \
+$ docker run -v ~/.spark-docker:/data -p 9737:9737 \
shesek/spark --login bob:superSecretPass456
```
@@ -12,7 +12,7 @@ You will then be able to access the Spark wallet at `https://localhost:9737`.
Runs in `testnet` mode by default, set `NETWORK` to override (e.g. `-e NETWORK=bitcoin`).
Data files will be stored in `~/.spark-docker/{bitcoin,lightning,spark}`.
-You cat set Spark's configuration options in `~/.spark-docker/spark/config`.
+You can set Spark's configuration options in `~/.spark-docker/spark/config`.
When starting for the first time, you'll have to wait for the bitcoin node to sync up.
You can check the progress by tailing `~/.spark-docker/bitcoin/debug.log`.
@@ -29,8 +29,8 @@ To connect to an existing `lightningd` instance running on the same machine,
mount the lightning data directory to `/etc/lightning`:
```bash
-$ docker run -v $HOME/.spark-docker:/data -p 9737:9737 \
- -v $HOME/.lightning:/etc/lightning \
+$ docker run -v ~/.spark-docker:/data -p 9737:9737 \
+ -v ~/.lightning:/etc/lightning \
shesek/spark
```
@@ -39,7 +39,7 @@ Connecting to remote lightningd instances is currently not supported.
#### With existing `bitcoind`, but with bundled `lightningd`
To connect to an existing `bitcoind` instance running on the same machine,
-mount the bitcoin data directory to `/etc/bitcoin` (e.g. `-v $HOME/.bitcoin:/etc/bitcoin`),
+mount the bitcoin data directory to `/etc/bitcoin` (e.g. `-v ~/.bitcoin:/etc/bitcoin`),
and either use host networking (`--network host`) or specify the IP where bitcoind is reachable via `BITCOIND_RPCCONNECT`.
The RPC credentials and port will be read from bitcoind's config file.
diff --git a/doc/onion.md b/doc/onion.md
new file mode 100644
index 0000000..899a95a
--- /dev/null
+++ b/doc/onion.md
@@ -0,0 +1,30 @@
+# Tor Onion Hidden Service
+
+To start Spark as a Tor hidden service (v3), set `--onion`.
+Spark will install Tor automatically (via [granax](https://gitlab.com/bookchin/granax)/[hsv3](https://gitlab.com/bookchin/hsv3));
+you don't have to pre-install anything for this to work.
+
+Running Spark as a Tor hidden service has the following benefits:
+
+- Tor `.onion` hostnames are self-authenticating and are pinned to your server's public key.
+
+- In addition to authenticating the server, they also serve as a mean to authenticate the user - you can't access the server without knowing the `.onion` hostname.
+ That means that even if a security vulnerability is found on nodejs/Spark,
+ an attacker will not be able the access to server in order to exploit it.
+
+- You don't have to setup port forwarding, everything is done with outbound connections.
+ Punch through routers with ease.
+
+Tor data files (including secret key material for the hidden service) will be saved to `~/.spark-wallet/tor/`. This can be overridden with `--onion-path`.
+
+### Connecting from Android
+
+To connect to your hidden service using a web browser, install the
+[Orbot](https://guardianproject.info/apps/orbot/) and [Orfox](https://guardianproject.info/apps/orfox/)
+applications, open the `.onion` URL in Orfox, and enable JavaScript under `⋮` -> `NoScript`.
+
+To connect using the Cordova app, configure Orbot to route Spark's traffic over the Tor VPN
+(under "Tor-Enabled Apps"), then configure Spark to use the `.onion` server URL.
+
+Instead of manually copying the `.onion` URL, you may want to specify `--print-qr/-q` to print
+the URL as a QR to the console, or `--pairing-qr/-Q` to also include the access key.
diff --git a/doc/startup-systemd.md b/doc/startup-systemd.md
new file mode 100644
index 0000000..77c7be3
--- /dev/null
+++ b/doc/startup-systemd.md
@@ -0,0 +1,15 @@
+# Adding Spark to startup with `systemd`
+
+```bash
+# Set config options in ~/.spark-wallet/config
+$ echo login=bob:superSecretPass123 | tee -a ~/.spark-wallet/config
+
+# Create service file from template
+$ curl -s https://raw.githubusercontent.com/ElementsProject/spark/master/scripts/spark-wallet.service |
+ sed "s~{cmd}~`which spark-wallet`~;s~{user}~`whoami`~" |
+ sudo tee /etc/systemd/system/spark-wallet.service
+
+# Inspect the generated service file, then load and start the service
+$ sudo systemctl daemon-reload
+$ sudo systemctl enable spark-wallet && sudo systemctl start spark-wallet
+```
diff --git a/doc/tls.md b/doc/tls.md
new file mode 100644
index 0000000..1e324e4
--- /dev/null
+++ b/doc/tls.md
@@ -0,0 +1,59 @@
+# TLS
+
+Spark will by default generate a self-signed certificate and enable TLS when binding on a non-`localhost` address.
+
+The self-signed certificate and key material will be saved to `~/.spark-wallet/tls/`.
+To save to a different location, set `--tls-path`.
+To set a custom "common name" for the generated certificate, set `--tls-name` (defaults to the value of `--host`).
+
+To use your own TLS key and certificate, put your `key.pem` and `cert.pem` files in the `--tls-path` directory.
+
+To disable TLS and start a plaintext HTTP server instead, set `--no-tls`.
+Note that without TLS, Chrome will not allow accessing the camera on non-`localhost` hosts.
+
+To enable TLS even for `localhost`, set `--force-tls`.
+
+### LetsEncrypt integration
+
+Setting `--letsencrypt ` will automatically setup a CA-signed certificate using LetsEncrypt.
+This will make your certificate work everywhere without self-signed warnings.
+
+```
+$ spark-wallet --host mydomain.com --letsencrypt webmaster@mydomain.com
+```
+
+Requires a (sub)domain name, cannot be used with IP addresses.
+If your domain is different from the host you're binding on, set `--tls-name`
+(e.g. `--host 0.0.0.0 --tls-name mydomain.com`).
+
+Note that verifying domain ownership requires binding an HTTP server on port 80, which normally requires root permissions.
+You can either:
+
+1. Start `spark-wallet` as root (simplest, but not recommended).
+2. Use `setcap` to allow nodejs processes to bind on all ports: `$ sudo setcap 'cap_net_bind_service=+ep' $(which node)`
+3. Bind the verification server to a different port with `--le-port 8080` (any port >1024 will work), then forward port 80 to it with:
+ `$ iptables -A PREROUTING -t nat -p tcp --dport 80 -j REDIRECT --to-port 8080 && iptables -t nat -A OUTPUT -o lo -p tcp --dport 80 -j DNAT --to-destination :8080`
+
+After initially verifying your domain, you may start Spark with `--le-noverify` to skip starting the verification server.
+This will work until the next renewal is due (every 90 days).
+
+If you're having troubles, set `--le-debug` to show more debug information.
+
+### Add as Trusted Certificate to Android
+
+To avoid the self-signed certificate warnings (without a CA), you can add the certificate to your Android's "user trusted certificates"
+by following these steps:
+
+1. Open Spark in your mobile web browser (skipping the warning).
+2. Click the red TLS warning in the URL bar to view the certificate and ensure it matches the expected one
+ (the certificate's SHA1 fingerprint is printed to the console during Spark's startup).
+3. Navigate to `/cert.pem` to download the certificate file from the server and open it.
+4. You should now see [this screen](https://i.imgur.com/f2DMWdL.png), allowing you to add a user trusted certificate.
+ Fill in a name (e.g. "Spark"), leave "Used for" on "VPN and apps", and click OK.
+
+Note that adding a user trusted certificate causes android to display a "Network may be monitored" notification.
+It can be flicked off.
+
+Unfortunately, adding a user trusted certificate is not enough for Android to allow installing the PWA.
+This requires a CA-signed certificate.
+
diff --git a/src/cli.js b/src/cli.js
index 52b1a0a..bb8dc04 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -7,9 +7,9 @@ const args = require('meow')(`
Options
-l, --ln-path path to c-lightning data directory [default: ~/.lightning]
-u, --login http basic auth login, "username:password" format [default: generate random]
-
-p, --port http(s) server port [default: 9737]
-i, --host http(s) server listen address [default: localhost]
+ --no-webui run API server without serving client assets [default: false]
--force-tls enable TLS even when binding on localhost [default: enable for non-localhost only]
--no-tls disable TLS for non-localhost hosts [default: false]
@@ -24,8 +24,6 @@ const args = require('meow')(`
-o, --onion start Tor Hidden Service (v3) [default: false]
-O, --onion-path directory to read/store hidden service data [default: ~/.spark-wallet/tor/]
- --no-webui run API server without serving client assets [default: false]
-
-c, --config path to config file [default: ~/.spark-wallet/config]
-V, --verbose display debugging information [default: false]
-h, --help output usage information
diff --git a/src/transport/tls.js b/src/transport/tls.js
index b5d9452..b07835e 100644
--- a/src/transport/tls.js
+++ b/src/transport/tls.js
@@ -86,7 +86,7 @@ const letsencrypt = (name, dir, email) => {
if (err.errno == 'EACCES') {
console.error(`\nYou don't have prmission to bind on ${err.address}:${err.port}.`);
- console.error('See https://github.com/ElementsProject/spark/blob/master/README.md#letsencrypt-integration for advice.');
+ console.error('See https://github.com/ElementsProject/spark/blob/master/doc/tls.md#letsencrypt-integration for advice.');
} else if (err.errno == 'EADDRINUSE') {
console.error(`\n${err.address}:${err.port} is already being used by some other program. Stop it and try again.`);
}