From b3c8a2a7119f4a1ec6bfa40af5a84ff737d02efe Mon Sep 17 00:00:00 2001 From: Mayank Date: Fri, 29 May 2020 10:30:26 +0530 Subject: [PATCH] Update README --- README.md | 78 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 52 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 88826d2..e8c2170 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,47 @@ -# Umbrel Compose System +[![Umbrel Compose](https://i.imgur.com/4it3IiB.png)](https://github.com/getumbrel/umbrel-compose) -## Abstract +[![Version](https://img.shields.io/github/v/release/getumbrel/umbrel-compose?color=%235351FB&label=version)](https://github.com/getumbrel/umbrel-compose/releases) +[![Chat](https://img.shields.io/badge/chat%20on-telegram-%235351FB)](https://t.me/getumbrel) -This is a basic framework for orchestration of the services required to run an Umbrel bitcoin and lightning node. +[![Twitter](https://img.shields.io/twitter/follow/getumbrel?style=social)](https://twitter.com/getumbrel) +[![Reddit](https://img.shields.io/reddit/subreddit-subscribers/getumbrel?label=Subscribe%20%2Fr%2Fgetumbrel&style=social)](https://reddit.com/r/getumbrel) -## How to use -Ideally, you should create a user for this and then run it within the root of that user. There are some root privilege needed stuff, however LND doesn't support tor passwords yet so we will need to wait. +# ☂️ compose -### Step 1 +Compose is a framework for orchestration of all containerized services running on [Umbrel OS](https://github.com/getumbrel/umbrel-os). -Ensure you have the [latest docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/) installed, python3 (for docker-compose), and docker-compose (installed from python3 pip). +It is platform and architecture-agnostic, thus can be used to directly spin up instances of Umbrel without installing the [Umbrel OS](https://github.com/getumbrel/umbrel-os) since all orchestrated services use multi-architecture images. -Ensure that you have the latest tor (currently working with 0.3.5.8), and you are using system default paths. +We run it on Raspbery Pis (ARMv7) as a part of [Umbrel OS](https://github.com/getumbrel/umbrel-os), Ubuntu (x64) for [testnet.getumbrel.com](https://testnet.getumbrel.com) and macOS (x64) for local development. -For the install script, you should also have git installed. +## 🚀 Getting started -For the configuration script you should also have wget. +If you are looking to run Umbrel on your hardware, you do not need to use this framework on it's own. Just download [Umbrel OS](https://github.com/getumbrel/umbrel-os/releases) and you're good to go. -These scripts all are able to run as non-interactive sessions. +## 🎹 Services orchestrated by Compose -### Step 2 +- [`bitcoind`](https://github.com/getumbrel/docker-bitcoind) +- [`lnd`](https://github.com/getumbrel/docker-lnd) +- [`nginx`](https://github.com/nginx/nginx) +- [`umbrel-dashboard`](https://github.com/getumbrel/umbrel-dashboard) +- [`umbrel-manager`](https://github.com/getumbrel/umbrel-manager) +- [`umbrel-middleware`](https://github.com/getumbrel/umbrel-middleware) -Ensure that your account is permissioned for docker. +## 🛠 Using Compose -### Step 3 +### Requirements -Run this from your home directory. This clones this repo into your home directory, as well as preserving the existing structure. +- [Docker](https://docs.docker.com/engine/install) +- [Python 3.0+](https://www.python.org/downloads) +- [Docker Compose](https://docs.docker.com/compose/install/#install-using-pip) (installed via python3 pip) +- [Tor](https://2019.www.torproject.org/docs/debian.html.en) (using default system paths) + +Ensure that your account is [correctly permissioned to use docker](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). + +### Step 1. Run this from your home directory (if installing on dedicated hardware) + +> It will clone this repo while preserving home directory's existing structure. ```bash # Ideally you should run this in $HOME as the docker-compose presets are in home @@ -37,30 +52,41 @@ curl "https://raw.githubusercontent.com/getumbrel/umbrel-compose/master/install- wget -qO- "https://raw.githubusercontent.com/getumbrel/umbrel-compose/master/install-box.sh" | sh ``` -### Configuring +### Step 2. Configure ```bash -# If you want to use testnet, otherwise we will use mainnet by default and be #reckless +# If you want to use testnet, otherwise it will use mainnet by default and be #reckless export TESTNET=true -# testnet mode not supported as config is completely different +# (testnet mode not fully supported) # Run this in the $HOME directory -wget -qO- "https://raw.githubusercontent.com/getumbrel/umbrel-compose/master/configure-box.sh" | sh -# or (should be in the $HOME directory after install) ./configure-box.sh ``` -### Running +### Step 3. Run the services ```bash -# Build containers in build/ always -docker-compose up -d --build -# verify the containers +docker-compose up -d +# Verify the services docker ps -a ``` +--- + +### ⚡️ Don't be too reckless + +> Umbrel is still in early development and things are expected to break every now and then. We **DO NOT** recommend running it on the mainnet with real money just yet, unless you want to be really *#reckless*. + +## ❤️ Contributing + +We welcome and appreciate new contributions. + +If you're a developer looking to help but not sure where to begin, check out [these issues](https://github.com/getumbrel/umbrel-dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) that have specifically been marked as being friendly to new contributors. + +If you're looking for a bigger challenge, before opening a pull request please [create an issue](https://github.com/getumbrel/umbrel-dashboard/issues/new/choose) or [join our community chat](https://t.me/getumbrel) to get feedback, discuss the best way to tackle the challenge, and to ensure that there's no duplication of work. -## TODO List +--- -Please see the [following tasks](https://github.com/getumbrel/umbrel-compose/issues?q=is%3Aissue+is%3Aopen+label%3ATODO) which are on this list. +[![License](https://img.shields.io/github/license/getumbrel/umbrel-compose?color=%235351FB)](https://github.com/getumbrel/umbrel-compose/blob/master/LICENSE) +[getumbrel.com](https://getumbrel.com) \ No newline at end of file