Update documentation

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.
-
-
-### 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
+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.
 
-To run all the tests, run `yarn test`
+This project uses [Yarn workspaces](https://yarnpkg.com/blog/2017/08/02/introducing-workspaces/).
 
 
 ## Build System

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.

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
+
+Build the server as a Node.js app:
+```
+yarn do shadowbox/server/build
+```
+The output will be at `build/shadowbox/app`.
+
+
+You can see how to run the server at [`shadowbox/server/run_action.sh`](server/run_action.sh).
+
+
+### Running Shadowbox as a Docker container
 
-Set up
+> **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
+yarn do shadowbox/docker/run
 ```
 
-Start the server
+Debug image:
 ```
-yarn do shadowbox/server/run
+docker run --rm -it --entrypoint=sh outline/shadowbox
 ```
 
-If you just want to build the server:
+Or a running container:
 ```
-yarn do shadowbox/server/build
+docker exec -it shadowbox sh
 ```
 
-The output will be at `build/shadowbox/app`.
+
+Delete dangling images:
+```
+docker rmi $(docker images -f dangling=true -q)
+```
 
 
-## Queries
+## Access Keys Management API
 
 List users
 ```
@@ -98,39 +138,6 @@ $ curl --insecure https://localhost:8081/TestApiPrefix/access-keys
 ```
 </details>
 
-## 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
 

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