From e3a6538ef9b4bdbb8d4ee5d602dae02eb9b2b442 Mon Sep 17 00:00:00 2001
From: fortuna <fortuna@users.noreply.github.com>
Date: Tue, 8 Jan 2019 19:45:52 -0500
Subject: [PATCH] Several documentation fixes

---
 src/shadowbox/README.md                       | 101 ++++++------------
 src/shadowbox/docker/run_action.sh            |  17 +--
 src/shadowbox/integration_test/test.sh        |   2 +-
 ...ertificate.sh => make_test_certificate.sh} |   3 +-
 src/shadowbox/server/run_action.sh            |   6 +-
 5 files changed, 47 insertions(+), 82 deletions(-)
 rename src/shadowbox/scripts/{make_certificate.sh => make_test_certificate.sh} (95%)

diff --git a/src/shadowbox/README.md b/src/shadowbox/README.md
index f1acd330..6de8803a 100644
--- a/src/shadowbox/README.md
+++ b/src/shadowbox/README.md
@@ -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
diff --git a/src/shadowbox/docker/run_action.sh b/src/shadowbox/docker/run_action.sh
index 6431b607..f2d7845a 100755
--- a/src/shadowbox/docker/run_action.sh
+++ b/src/shadowbox/docker/run_action.sh
@@ -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
diff --git a/src/shadowbox/integration_test/test.sh b/src/shadowbox/integration_test/test.sh
index 1641411c..e4dfc52b 100755
--- a/src/shadowbox/integration_test/test.sh
+++ b/src/shadowbox/integration_test/test.sh
@@ -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
diff --git a/src/shadowbox/scripts/make_certificate.sh b/src/shadowbox/scripts/make_test_certificate.sh
similarity index 95%
rename from src/shadowbox/scripts/make_certificate.sh
rename to src/shadowbox/scripts/make_test_certificate.sh
index 7f86a11c..d4cb59e9 100755
--- a/src/shadowbox/scripts/make_certificate.sh
+++ b/src/shadowbox/scripts/make_test_certificate.sh
@@ -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=(
diff --git a/src/shadowbox/server/run_action.sh b/src/shadowbox/server/run_action.sh
index d44be570..abd0eb8f 100755
--- a/src/shadowbox/server/run_action.sh
+++ b/src/shadowbox/server/run_action.sh
@@ -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