-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #242 from nolim1t/cleanup-and-documentation
Options works so merged to master
- Loading branch information
Showing
35 changed files
with
214 additions
and
2,193 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,101 +1,65 @@ | ||
| Pi-Factory | ||
| =========================================== | ||
|
|
||
| ### _Create your own bitcoin lightning box!_ | ||
| ### _Easily build your own Alpine Linux box on Raspberry PI or Raspberry Zero!_ | ||
|
|
||
| This repository lets you build a _bitcoin lightning_ box for [Raspberry Pi](https://www.raspberrypi.org) 3 Model B & 3B+ based on [Alpine](https://alpinelinux.org) Linux. | ||
| This repository lets you build you build an _[Alpine](https://alpinelinux.org) Linux_ box for [Raspberry Pi](https://www.raspberrypi.org) Model B/B+/4/Zero | ||
|
|
||
| **Work in progress.** While stable enough for development, this software is subject to change, some of which may be breaking changes. | ||
| **Warning!** *Do not put money at stake that you are not willing to lose!* | ||
|
|
||
| [](https://travis-ci.com/lncm/pi-factory) | ||
| [](https://pi-factory.readthedocs.io/en/latest/?badge=latest) | ||
|
|
||
|
|
||
| ### Features | ||
|
|
||
| * `Tor` onion-routing for enhanced privacy and improved connectivity | ||
| * Lightning Labs' `LND` bundled with our *autoconnect* and *autounlock* tools | ||
| * Bitcoin Core `bitcoind` bundled with our implementation of Nicholas Dorier's *fastsync* to drastically reduce initial sync time | ||
| * `Alpine Linux`, a security-oriented, lightweight Linux distribution based on musl *libc* and `Busybox` | ||
| * Containerization of most components including `nginx`, `iotwifi`, `invoicer`, `bitcoind`, `lnd` | ||
| * *Stateless OS* - the microSD card image can be replaced with a newer version *without loss of user data* | ||
| * Simple `shell`, `Python` scripts and `Go` backends enable easy auditing and provide a small *attack surface* | ||
| * `Docker` & `docker-compose` make updates easier and orchestration painless | ||
| * [Future] the microSD card can be mounted in read-only mode for zero-wear operation | ||
| * [Future] Redundant storage persistence using RAID | ||
|
|
||
| - pi-factory is now a persistent OS Only! For Nodes, please refer to earlier versions or go to the [noma](https://github.com/lncm/noma) project | ||
| - Latest version updated to Alpine 3.10.2 | ||
| - We now have 64 bit (aarch64) and 32 bit images (armhf). The Raspberry PI 3/3b works well on 64 bit | ||
| - Deterministic builds. Images now built and released automatically through github actions. | ||
|
|
||
| ### LNCM components | ||
|
|
||
| * [invoicer](https://github.com/lncm/invoicer): lightweight `bitcoind` and `LND` backend in Go. | ||
| * [invoicer-ui](https://github.com/lncm/invoicer-ui): Point of Sale for Bitcoin and Lightning in React. | ||
| * [iotwifi-ui](https://github.com/lncm/iotwifi-ui): Wi-Fi connection wizard in React. | ||
| * [noma](https://github.com/lncm/noma): CLI node management utility and API in Python. | ||
| * [docker-bitcoind](https://github.com/lncm/docker-bitcoind): arm & amd64 support | ||
| * [docker-berkeleydb](https://github.com/lncm/docker-berkeleydb): arm & amd64 support | ||
| * [docker-lnd](https://github.com/lncm/docker-lnd): arm & amd64 support | ||
|
|
||
|
|
||
| Hardware Requirements | ||
| --------------------- | ||
|
|
||
| * **Raspberry Pi** | ||
| * Recommended: model 3B+ | ||
| * Optional: case, heatsink, LAN cable | ||
|
|
||
| We recommend using a heatsink on 3B+ models to unlock their full sustained performance. Useful, e.g. during syncing or filtering blocks. | ||
|
|
||
| * Optional: case, heatsink, LAN cable, HDMI cable and monitor (for troubleshooting and issue tracking), Keyboard (to use for troubleshooting and issue tracking) | ||
|
|
||
|
|
||
| * **microSD** card | ||
| * Recommended: SanDisk 16GB or more | ||
| * microSD card to USB adapter or built-in hardware | ||
|
|
||
| Quality goes over quantity here! | ||
|
|
||
| * **USB storage** devices | ||
| * Recommended: 4 USB flash drives of 16GB or more | ||
| * Alternatively for bitcoin full-archival nodes: | ||
| * 2 or 3 flash devices | ||
| * a hard drive or SSD for the blockchain | ||
|
|
||
| You may need to use a powered USB hub to prevent undervoltage when using some hard drives. | ||
|
|
||
| * **Power Supply** (5V/2.5A) with micro-USB cable | ||
| * Recommended: official Raspberry Pi power supply | ||
| * Alternatively: | ||
| * Alternatively: | ||
| * high-quality USB charger (e.g. Samsung) | ||
| * short USB to micro-USB cable. (a longer cable can work with 5.1V chargers) | ||
|
|
||
| **Warning!** Your Raspberry Pi will *not work* properly without a correctly rated power supply and cable. | ||
|
|
||
| You **risk losing bitcoin** and **data** when running your Raspberry Pi in an underpowered state. | ||
|
|
||
|
|
||
| **Warning!** Your Raspberry Pi will *not work* properly without a correctly rated power supply and cable, and may result in data loss. We are not responsible if you lose any data. | ||
|
|
||
|
|
||
| Instructions | ||
| ------------ | ||
|
|
||
| 1. Download [Etcher](https://www.balena.io/etcher/) | ||
| * *Experienced users:* it is possible to use `dd` instead | ||
| 2. Download latest [lncm-box.img.zip]( | ||
| https://github.com/lncm/pi-factory/releases/download/v0.4.1/lncm-box-v0.4.1.img.zip) | ||
| 3. Run Etcher and follow on-screen instructions to burn `lncm-box.img.zip` to microSD card | ||
| 4. Place the SD card in your *Raspberry Pi* | ||
| 5. Connect your *Raspberry Pi* to a **correctly rated power supply** | ||
| 6. If you are using wired *LAN*: | ||
| * connect the cable to your Pi | ||
| * is your LAN cable active? | ||
| * congratulations, you are done! | ||
| 7. If you are using *WiFi*: | ||
| * find a device with a *web browser* and *WiFi*, e.g. your smartphone or laptop | ||
| 8. On your device, search for and connect to a *WiFi* network called **LNCM-Box** | ||
| * Password: **lncm box** | ||
| 9. Open the *web browser* on your device, e.g. `Chrome` or `Safari` | ||
| * Navigate to "[http://box.local/wifi](http://box.local/wifi)" | ||
| * Choose your *WiFi* network from the list | ||
| * Type in your password & *connect* | ||
|
|
||
| Your **lightning box** will automatically start installing itself to *microSD* card once it has an internet connection. This usually takes less than *15 minutes* depending on the speed of your card and internet connection. | ||
|
|
||
| Once the box has *synced* up the **invoicing** service will be available at [http://box.local/pos](http://box.local/pos). Depending on the speed of your internet connection and your USB storage devices the process may take *30 minutes* to *an hour* or more. | ||
| 1. Download [Etcher](https://www.balena.io/etcher/) | ||
| 2. Download the image from the [Releases page](https://github.com/lncm/pi-factory/releases) or simply clone the ```https://github.com/lncm/pi-factory.git``` repository on github | ||
| 3. Insert SD Card and open up Etcher | ||
| 4. Etch one of the images onto the SD card | ||
| 5. Remount the SD card and create a file called ```wpa_supplicant.conf``` | ||
| 6. Inside the file put the following | ||
|
|
||
| ``` | ||
| network={ | ||
| ssid="Your Wifi SSID goes here" | ||
| key_mgmt=WPA-PSK | ||
| psk="YOUR Password goes here" | ||
| } | ||
| ``` | ||
|
|
||
| 7. Unmount the drive and put it into a PI or PI zero and then start it up. And in about 10-20 minutes (PI-Zero will take longer), you will be able to login through avahi/mdns ```box.local``` , or if you don't have avahi/mdns on your desktop you will need to grab the IP address from plugging in your PI to a TV or from your router. | ||
|
|
||
|
|
||
| Access | ||
| ------ | ||
|
|
@@ -111,44 +75,32 @@ Access | |
| - **username**: root | ||
| - **password**: chiangmai | ||
|
|
||
| **Note:** `sudo` is not installed, use `su` instead | ||
| **Note:** `sudo` is not installed, use `su` instead. We also highly recommend that you change the password. | ||
|
|
||
|
|
||
|
|
||
| ### Command-line via ssh | ||
| `ssh [email protected]` | ||
|
|
||
| **Note:** First boot will take some time as ssh host keys are generated. | ||
|
|
||
| ### Connect to WiFi hotspot | ||
|
|
||
| The Raspberry Pi lightning box provides it's own WiFi hotspot to ease access and configuration. | ||
|
|
||
| - **WiFi name** (SSID): "LNCM-Box" | ||
| - **WiFi password**: "lncm box" | ||
|
|
||
|
|
||
| - **IP address**: 192.168.27.1 | ||
| - **hostname**: box.local | ||
|
|
||
| ### WiFi hotspot | ||
|
|
||
| The box provides it's own WiFi hotspot to ease access and configuration. | ||
| #### Advanced configuration | ||
|
|
||
| - **WiFi name** (SSID): "LNCM-Box" | ||
| - **WiFi password**: "lncm box" | ||
| - **IP address**: 192.168.27.1 | ||
| - **hostname**: box.local | ||
| When building the image yourself you can create a ```wpa_supplicant.automatic.conf``` file with all your wifi passwords. | ||
|
|
||
| #### Advanced configuration | ||
| You may disable several stuff by placing an empty file inside the FAT partition. This should be done **before first boot** | ||
|
|
||
| If the wifi configuration manager does not work (currently there is an issue where the wifi manager is not getting downloaded), you may SSH in and invoke the following command. | ||
| Filename | Description | ||
| ------------ | ------------- | ||
| noswap | disables SWAP generation (not recommended unless you know what you are doing!) | ||
| noavahi | disables install for avahi-daemon / mdns discovery (not recommended unless you know what you are doing!) | ||
| nodocker | disables Docker installation | ||
| nopython | Disables python3 installation | ||
| notor | Disables tor installation | ||
|
|
||
| ```bash | ||
| curl -w "\n" -d '{"ssid":"YOUR-SSID-NAME", "psk":"YOUR-PASSWORD"}' \ | ||
| -H "Content-Type: application/json" \ | ||
| -X POST http://192.168.27.1:8080/connect | ||
| ``` | ||
|
|
||
| Alternatively, when building the image you can create a ```wpa_supplicant.automatic.conf``` file with all your wifi passwords. | ||
| You may disable swap generation by touching a file in the FAT partition called "noswap". This needs to be done the first time. | ||
|
|
||
| Documentation | ||
| ------------- | ||
|
|
@@ -157,7 +109,7 @@ Documentation | |
|
|
||
| Building | ||
| -------- | ||
| To generate a fresh image from source run `make_img.sh` as __root__ on a *Debian*, *Ubuntu* or *Alpine* system. | ||
| To generate a fresh image from source run `./make_img.sh` as __root__ on a *Debian*, *Ubuntu* or *Alpine* system. | ||
|
|
||
| For convenience, we also support `vagrant` to automate setting up your development VM. | ||
|
|
||
|
|
@@ -187,8 +139,7 @@ Also useful: | |
| Support | ||
| ------- | ||
|
|
||
| If you are having problems, please let us know. | ||
| We have a public [chat room](https://gitter.im/lcnm/box) | ||
| If you are having problems, please [create an issue](https://github.com/lncm/pi-factory/issues/new) | ||
|
|
||
|
|
||
| Contribute | ||
|
|
@@ -198,13 +149,7 @@ Bug reports, pull-requests and suggestions are very welcome! | |
|
|
||
| - [Issue Tracker](http://github.com/lncm/pi-factory/issues) | ||
| - [Source Code](https://github.com/lncm/pi-factory) | ||
|
|
||
| In the Wild | ||
| ----------- | ||
|
|
||
| There are two public [installations](http://nodes.lncm.io) of this lightning box in Chiang Mai, Thailand acting as Bitcoin and Lightning points of sale in combination with a tablet. | ||
|
|
||
| Please do let us know about your own or those you spot! | ||
| - [Contributing Guidelines](https://github.com/lncm/pi-factory/blob/master/CONTRIBUTING.md) | ||
|
|
||
| License | ||
| ------- | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.