From 4ee66c5ff9be7a9ca70a8fbdfdcfdfec2ce578f3 Mon Sep 17 00:00:00 2001 From: Vinicius Fortuna Date: Fri, 6 Apr 2018 19:02:45 -0400 Subject: [PATCH] Update documentation --- README.md | 75 ++++++------------ src/server_manager/README.md | 32 ++++++++ src/shadowbox/README.md | 121 +++++++++++++++-------------- src/shadowbox/server/run_action.sh | 1 + 4 files changed, 121 insertions(+), 108 deletions(-) create mode 100644 src/server_manager/README.md diff --git a/README.md b/README.md index 10c9c4ba..70c8f98e 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,50 @@ -# Outline Server Creator +# Outline Server [![Build Status](https://travis-ci.org/Jigsaw-Code/outline-server.svg?branch=master)](https://travis-ci.org/Jigsaw-Code/outline-server) -This repository has all the code needed to create and manage Outline servers on DigitalOcean. An Outline server runs -instances of Shadowsocks proxies and provides an API used by the Outline Manager application. +This repository has all the code needed to create and manage Outline servers on +DigitalOcean. An Outline server runs instances of Shadowsocks proxies and +provides an API used by the Outline Manager application. +Go to https://getoutline.com for ready-to-use versions of the software. ## Components The system comprises the following components: -- **Server Manager Electron App:** an Election application that wraps the Server Manager web application and runs - natively on Desktop. It adds some extra functionality, like validation of the server self-signed certificate and interception of the DigitalOcean registration flow. +- **Outline Server**: a proxy server that runs a Shadowsocks instance for each + access key and a REST API to manage the access keys. The Outline Server runs + in a Docker container in the host machine. - Code: `src/server_manager/electron_app` -- **Proxy Server**: a server that runs the Shadowsocks instances and a REST API to manage its users. Used as backend by the - Server Manager app. + See [`src/shadowbox`](src/shadowbox) - Code: `src/shadowbox` +- **Outline Manager:** an [Electron](https://electronjs.org/) application that + can create Outline Servers on the cloud and talks to their access key + management API to manage who has access to the server. -## Server Manager + See [`src/server_manager`](src/server_manager) -### Setup +- **Metrics Server:** a REST service that the Outline Server talks to + if the user opts-in to anonymous metrics sharing. -Ensure you have the following installed: + See [`src/metrics_server`](src/metrics_server) + + +## Code Prerequisites + +In order to build and run the code, you need the following installed: - [Node](https://nodejs.org/) - [Yarn](https://yarnpkg.com/en/docs/install) - [Wine](https://www.winehq.org/download), if you would like to generate binaries for Windows. -Install dependencies: +Then you need to install all the NPM package dependencies: ``` yarn ``` -If you are using root (not recommended on your dev machine, maybe in a container), you need to add `{ "allow_root": true }` to your `/root/.bowerrc` file. +Note: If you are using root (not recommended on your dev machine, maybe in a container), you need to add `{ "allow_root": true }` to your `/root/.bowerrc` file. - -### Electron App - -To run the electron app: -``` -yarn do server_manager/electron_app/run -``` - -To build the app for all platforms: -``` -yarn do server_manager/electron_app/package -``` - -The per-platform standalone apps will be at `build/electron_app/bundled`. - -The per-platform standalone apps packaged for distribution will be at -`build/electron_app/packaged` in the following formats: - -- Windows: zip files. Only generated if you have [wine](https://www.winehq.org/download) installed. -- Linux: tar.gz files. -- macOS: dmg files if built from macOS, zip files otherwise. - -To perform a release, use -``` -yarn do server_manager/electron_app/release -``` - -This will perform a clean and reinstall all dependencies to make sure the build is not tainted. - - -## Proxy Server - -See [`src/shadowbox/README.md`](src/shadowbox/README.md). - -## Unit Tests - -To run all the tests, run `yarn test` +This project uses [Yarn workspaces](https://yarnpkg.com/blog/2017/08/02/introducing-workspaces/). ## Build System diff --git a/src/server_manager/README.md b/src/server_manager/README.md new file mode 100644 index 00000000..21f77710 --- /dev/null +++ b/src/server_manager/README.md @@ -0,0 +1,32 @@ +# Outline Manager + +## Running + +To run the Outline Manager: +``` +yarn do server_manager/electron_app/run +``` + +## Packaging + +To build the app binary: +``` +yarn do server_manager/electron_app/package_${PLATFORM} +``` + +Where `${PLATFORM}` is one of `linux`, `macos`, `only_windows`. + +The per-platform standalone apps will be at `build/electron_app/static/dist`. + +- Windows: zip files. Only generated if you have [wine](https://www.winehq.org/download) installed. +- Linux: tar.gz files. +- macOS: dmg files if built from macOS, zip files otherwise. + +## Releases + +To perform a release, use +``` +yarn do server_manager/electron_app/release +``` + +This will perform a clean and reinstall all dependencies to make sure the build is not tainted. diff --git a/src/shadowbox/README.md b/src/shadowbox/README.md index d02cc433..e1d6fcfc 100644 --- a/src/shadowbox/README.md +++ b/src/shadowbox/README.md @@ -1,45 +1,85 @@ -# Introduction +# Outline Server -Shadowbox is a server set up that runs a user management API and starts Shadowsocks -instances on demand. +The internal name for the Outline server is "Shadowbox". It is a server set up +that runs a user management API and starts Shadowsocks instances on demand. -It aims to make it as easy as possible to set up and share a Shadowsocks server. It's -used by the Outline server launcher. +It aims to make it as easy as possible to set up and share a Shadowsocks +server. It's managed by the Outline Manager and used as proxy by the Outline +client apps. Shadowbox is also compatible with standard Shadowsocks clients. -## Requirements +## Self-hosted installation + +To install and run Shadowbox on your own server, run +``` +wget -qO- https://raw.githubusercontent.com/Jigsaw-Code/outline-server/master/src/server_manager/install_scripts/install_server.sh | bash +``` + +Use `bash -x` instead at the end of the command if you need to debug the installation. + +## Running from source code + +### Prerequisites + +Besides [Node](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/en/docs/install), you will also need: -1. [Node](https://nodejs.org/en/download/) -1. [Yarn](https://yarnpkg.com/en/docs/install) 1. [Docker 1.13+](https://docs.docker.com/engine/installation/) 1. [docker-compose 1.11+](https://docs.docker.com/compose/install/) -Run `docker info` and make sure `Storage Driver` is `devicemapper`. If it is not, you can override it by -editting `/etc/default/docker` or by passing another storage driver in the daemon commandline: +Run `docker info` and make sure `Storage Driver` is `devicemapper`. If it is +not, you can override it by editting `/etc/default/docker` or by passing +another storage driver in the daemon commandline: ``` sudo dockerd --storage-driver=devicemapper ``` -## Development +### Running Shadowbox as a Node.js app -Set up -``` -yarn -``` - -Start the server -``` -yarn do shadowbox/server/run -``` - -If you just want to build the server: +Build the server as a Node.js app: ``` yarn do shadowbox/server/build ``` - The output will be at `build/shadowbox/app`. -## Queries +You can see how to run the server at [`shadowbox/server/run_action.sh`](server/run_action.sh). + + +### Running Shadowbox as a Docker container + +> **NOTE**: This does not currently work in Docker on Mac due to use of +`--host=net` and integrity checks failing. For now, please see the Manual +testing section below. + +### With docker command + +Build the `outline/shadowbox` Docker image: +``` +yarn do shadowbox/docker/build +``` + +Run server: +``` +yarn do shadowbox/docker/run +``` + +Debug image: +``` +docker run --rm -it --entrypoint=sh outline/shadowbox +``` + +Or a running container: +``` +docker exec -it shadowbox sh +``` + + +Delete dangling images: +``` +docker rmi $(docker images -f dangling=true -q) +``` + + +## Access Keys Management API List users ``` @@ -98,39 +138,6 @@ $ curl --insecure https://localhost:8081/TestApiPrefix/access-keys ``` -## Docker Deployment - -**NOTE**: This does not currently work in Docker on Mac due to use of -`--host=net` and integrity checks failing. For now, please see the Manual -testing section below. - -### With docker command - -Build Docker image: -``` -yarn do shadowbox/docker/build -``` - -Run server: -``` -yarn do shadowbox/docker/run -``` - -Debug image: -``` -docker run --rm -it --entrypoint=sh quay.io/outline/shadowbox -``` - -or -``` -docker exec -it shadowbox sh -``` - - -Delete dangling images: -``` -docker rmi $(docker images -f dangling=true -q) -``` ## Testing diff --git a/src/shadowbox/server/run_action.sh b/src/shadowbox/server/run_action.sh index 91a16b24..d44be570 100755 --- a/src/shadowbox/server/run_action.sh +++ b/src/shadowbox/server/run_action.sh @@ -18,6 +18,7 @@ do_action shadowbox/server/build export LOG_LEVEL="${LOG_LEVEL:-debug}" export SB_PUBLIC_IP="${SB_PUBLIC_IP:-$(curl https://ipinfo.io/ip)}" +# WARNING: The SB_API_PREFIX should be kept secret! export SB_API_PREFIX=TestApiPrefix export SB_METRICS_URL=https://metrics-test.uproxy.org export SB_STATE_DIR=/tmp