mirror of
https://github.com/OutlineFoundation/outline-server.git
synced 2026-08-04 14:37:34 +00:00
Several documentation fixes
This commit is contained in:
fortuna
parent
b466c4a139
commit
e3a6538ef9
5 changed files with 47 additions and 82 deletions
|
|
@ -14,7 +14,7 @@ To install and run Shadowbox on your own server, run
|
|||
sudo bash -c "$(wget -qO- https://raw.githubusercontent.com/Jigsaw-Code/outline-server/master/src/server_manager/install_scripts/install_server.sh)"
|
||||
```
|
||||
|
||||
Use `bash -x` instead at the end of the command if you need to debug the installation.
|
||||
Use `sudo --preserve-env` if you need to pass environment variables. Use `bash -x` if you need to debug the installation.
|
||||
|
||||
## Running from source code
|
||||
|
||||
|
|
@ -25,25 +25,16 @@ Besides [Node](https://nodejs.org/en/download/) and [Yarn](https://yarnpkg.com/e
|
|||
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 editing `/etc/default/docker` or by passing
|
||||
another storage driver in the daemon commandline:
|
||||
```
|
||||
sudo dockerd --storage-driver=devicemapper
|
||||
```
|
||||
|
||||
### Running Shadowbox as a Node.js app
|
||||
|
||||
Build the server as a Node.js app:
|
||||
> **NOTE:**: This is currently broken. Use the docker option instead.
|
||||
|
||||
Build and run the server as a Node.js app:
|
||||
```
|
||||
yarn do shadowbox/server/build
|
||||
yarn do shadowbox/server/run
|
||||
```
|
||||
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
|
||||
|
||||
> **NOTE**: This does not currently work in Docker on Mac due to use of
|
||||
|
|
@ -52,16 +43,21 @@ testing section below.
|
|||
|
||||
### With docker command
|
||||
|
||||
Build the `outline/shadowbox` Docker image:
|
||||
```
|
||||
yarn do shadowbox/docker/build
|
||||
```
|
||||
|
||||
Run server:
|
||||
Build the image and run server:
|
||||
```
|
||||
yarn do shadowbox/docker/run
|
||||
```
|
||||
|
||||
You should be able to successfully query the management API:
|
||||
```
|
||||
curl --insecure https://[::]:8081/TestApiPrefix/server
|
||||
```
|
||||
|
||||
To build the image only:
|
||||
```
|
||||
yarn do shadowbox/docker/build
|
||||
```
|
||||
|
||||
Debug image:
|
||||
```
|
||||
docker run --rm -it --entrypoint=sh outline/shadowbox
|
||||
|
|
@ -72,7 +68,6 @@ Or a running container:
|
|||
docker exec -it shadowbox sh
|
||||
```
|
||||
|
||||
|
||||
Delete dangling images:
|
||||
```
|
||||
docker rmi $(docker images -f dangling=true -q)
|
||||
|
|
@ -81,7 +76,14 @@ docker rmi $(docker images -f dangling=true -q)
|
|||
|
||||
## Access Keys Management API
|
||||
|
||||
In order to utilize the Management API, you'll need to know the apiUrl for your Outline server. You can obtain this information from the 'access.txt' file under the 'shadowbox' directory of your server. An example apiUrl is: https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z.
|
||||
In order to utilize the Management API, you'll need to know the apiUrl for your Outline server.
|
||||
You can obtain this information from the "Settings" tab of the server page in the Outline Manager.
|
||||
Alternatively, you can check the 'access.txt' file under the '/opt/outline' directory of an Outline server. An example apiUrl is: https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z.
|
||||
|
||||
See [Full API Documentation](https://rebilly.github.io/ReDoc/?url=https://raw.githubusercontent.com/Jigsaw-Code/outline-server/master/src/shadowbox/server/api.yml).
|
||||
The OpenAPI specification can be found at [api.yml](./api.yml).
|
||||
|
||||
### Examples
|
||||
|
||||
Start by storing the apiURL you see see in that file, as a variable. For example:
|
||||
```
|
||||
|
|
@ -90,71 +92,28 @@ API_URL=https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z
|
|||
|
||||
You can then perform the following operations on the server, remotely.
|
||||
|
||||
List users
|
||||
List access keys
|
||||
```
|
||||
curl --insecure $API_URL/access-keys/
|
||||
```
|
||||
|
||||
Create a user
|
||||
Create an access keys
|
||||
```
|
||||
curl --insecure -X POST $API_URL/access-keys
|
||||
```
|
||||
|
||||
Rename a user
|
||||
(e.g. rename user ID 2 to 'albion')
|
||||
Rename an access keys
|
||||
(e.g. rename access key 2 to 'albion')
|
||||
```
|
||||
curl --insecure -X PUT curl -F 'name=albion' $API_URL/access-keys/2/name
|
||||
```
|
||||
|
||||
Remove a user
|
||||
(e.g. remove user ID 2)
|
||||
Remove as access keys
|
||||
(e.g. remove access key 2)
|
||||
```
|
||||
curl --insecure -X DELETE $API_URL/access-keys/2
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
Example output
|
||||
</summary>
|
||||
|
||||
```
|
||||
$ API_URL=https://1.2.3.4:1234/3pQ4jf6qSr5WVeMO0XOo4z
|
||||
$ curl --insecure $API_URL/access-keys
|
||||
{"users":[]}
|
||||
|
||||
$ curl --insecure -X POST $API_URL/access-keys
|
||||
{"id":"0","password":"Nm9wtQkPeshs","port":34180}
|
||||
|
||||
$ curl --insecure -X POST $API_URL/access-keys
|
||||
{"id":"1","password":"32mW3jhuhBGv","port":55625}
|
||||
|
||||
$ curl --insecure -X POST $API_URL/access-keys
|
||||
{"id":"2","password":"jFOKrJcpbgIb","port":15884}
|
||||
|
||||
$ curl --insecure $API_URL/access-keys
|
||||
{"users":[{"id":"0","password":"Nm9wtQkPeshs","port":34180},{"id":"1","password":"32mW3jhuhBGv","port":55625},{"id":"2","password":"jFOKrJcpbgIb","port":15884}]}
|
||||
|
||||
$ curl --insecure -X DELETE $API_URL/access-keys/0 -v
|
||||
* Hostname was NOT found in DNS cache
|
||||
* Trying ::1...
|
||||
* Connected to 1.2.3.4 (::1) port 1234 (#0)
|
||||
> DELETE /access-keys/0 HTTP/1.1
|
||||
> User-Agent: curl/7.35.0
|
||||
> Host: 1.2.3.4:1234
|
||||
> Accept: */*
|
||||
>
|
||||
< HTTP/1.1 204 No Content
|
||||
< Date: Fri, 03 Feb 2017 22:46:39 GMT
|
||||
< Connection: keep-alive
|
||||
<
|
||||
* Connection #0 to host 1.2.3.4 left intact
|
||||
|
||||
$ curl --insecure $API_URL/access-keys
|
||||
{"users":[{"id":"1","password":"32mW3jhuhBGv","port":55625},{"id":"2","password":"jFOKrJcpbgIb","port":15884}]}
|
||||
```
|
||||
</details>
|
||||
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual
|
||||
|
|
|
|||
|
|
@ -14,19 +14,22 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
touch /tmp/config.json
|
||||
source $ROOT_DIR/src/shadowbox/scripts/make_certificate.sh
|
||||
do_action shadowbox/docker/build
|
||||
|
||||
OUTLINE_DIR=/tmp/outline
|
||||
touch "$OUTLINE_DIR/config.json"
|
||||
source $ROOT_DIR/src/shadowbox/scripts/make_test_certificate.sh "${OUTLINE_DIR}"
|
||||
|
||||
# TODO: mount a folder rather than individual files.
|
||||
declare -a docker_bindings=(
|
||||
-v /tmp/config.json:/root/shadowbox/shadowbox_config.json
|
||||
-v /tmp/stats.json:/root/shadowbox/shadowbox_stats.json
|
||||
-v "$OUTLINE_DIR/config.json":/root/shadowbox/shadowbox_config.json
|
||||
-v "$OUTLINE_DIR/stats.json":/root/shadowbox/shadowbox_stats.json
|
||||
-v ${SB_CERTIFICATE_FILE}:${SB_CERTIFICATE_FILE}
|
||||
-v ${SB_PRIVATE_KEY_FILE}:${SB_PRIVATE_KEY_FILE}
|
||||
-e "LOG_LEVEL=${LOG_LEVEL:-debug}"
|
||||
-e SB_API_PREFIX=TestApiPrefix
|
||||
-e SB_CERTIFICATE_FILE
|
||||
-e SB_PRIVATE_KEY_FILE
|
||||
-e SB_CERTIFICATE_FILE=${SB_CERTIFICATE_FILE}
|
||||
-e SB_PRIVATE_KEY_FILE=${SB_PRIVATE_KEY_FILE}
|
||||
)
|
||||
export DOCKER_CONTENT_TRUST=${DOCKER_CONTENT_TRUST:-1}
|
||||
docker run --rm -it --network=host --name shadowbox "${docker_bindings[@]}" outline/shadowbox
|
||||
sudo docker run --rm -it --network=host --name shadowbox "${docker_bindings[@]}" outline/shadowbox
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ function cleanup() {
|
|||
(($DEBUG != 0)) && set -x
|
||||
|
||||
# Make the certificate
|
||||
source ../scripts/make_certificate.sh
|
||||
source ../scripts/make_test_certificate.sh /tmp
|
||||
|
||||
# Ensure proper shut down on exit if not in debug mode
|
||||
trap "cleanup" EXIT
|
||||
|
|
|
|||
|
|
@ -16,7 +16,8 @@
|
|||
|
||||
# Make a certificate for development purposes, and populate the
|
||||
# corresponding environment variables.
|
||||
CERTIFICATE_NAME='/tmp/shadowbox-selfsigned-dev'
|
||||
|
||||
CERTIFICATE_NAME="$1/shadowbox-selfsigned-dev"
|
||||
export SB_CERTIFICATE_FILE="${CERTIFICATE_NAME}.crt"
|
||||
export SB_PRIVATE_KEY_FILE="${CERTIFICATE_NAME}.key"
|
||||
declare -a openssl_req_flags=(
|
||||
|
|
@ -21,8 +21,10 @@ 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
|
||||
export SB_STATE_DIR=/tmp/outline
|
||||
|
||||
source $ROOT_DIR/src/shadowbox/scripts/make_certificate.sh
|
||||
source $ROOT_DIR/src/shadowbox/scripts/make_test_certificate.sh $SB_STATE_DIR
|
||||
|
||||
# This will fail because it expects prometheus and outline-ss-server to be in /root/shadowbox/bin.
|
||||
# TODO: Fix it
|
||||
node $BUILD_DIR/shadowbox/app/server/main
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue