mirror of
https://github.com/OutlineFoundation/outline-server.git
synced 2026-05-13 05:52:04 +00:00
Update documentation
This commit is contained in:
Vinicius Fortuna
GitHub
parent
519dbb7964
commit
4ee66c5ff9
4 changed files with 121 additions and 108 deletions
75
README.md
75
README.md
|
|
@ -1,77 +1,50 @@
|
|||
# Outline Server Creator
|
||||
# Outline Server
|
||||
|
||||
[](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
|
||||
|
|
|
|||
32
src/server_manager/README.md
Normal file
32
src/server_manager/README.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
|||
```
|
||||
</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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue