Merge pull request #68 from python-discord/feat/doc/57/docker-run-cmd

Document a simpler way to run snekbox

1 files changed, 28 insertions, 18 deletions

diff --git a/README.md b/README.md
index bbb8d64..f12d236 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-[![Build Status](https://dev.azure.com/python-discord/Python%20Discord/_apis/build/status/Snekbox?branchName=master)](https://dev.azure.com/python-discord/Python%20Discord/_build/latest?definitionId=13&branchName=master)
+[![Build Status][1]][2]
 
 # snekbox
 
@@ -22,34 +22,32 @@ result <- |             |<----------|           | <----------+
 
 ```
 
-The code is executed in a Python process that is launched through [NsJail](https://github.com/google/nsjail), which is responsible for sandboxing the Python process. NsJail is configured as follows:
+The code is executed in a Python process that is launched through [NsJail], which is responsible for sandboxing the Python process. See [`snekbox.cfg`] for the NsJail configuration.
 
-* All mounts are read-only
-* Time limit of 5 seconds
-* Maximum of 1 PID
-* Maximum memory of 52428800 bytes
-* Loopback interface is down
-* procfs is disabled
 
-The Python process is configured as follows:
+## HTTP REST API
 
-* Version 3.8.0
-* Isolated mode
-  * Neither the script's directory nor the user's site packages are in `sys.path`
-  * All `PYTHON*` environment variables are ignored
+Communication with snekbox is done over a HTTP REST API. The framework for the HTTP REST API is [Falcon] and the WSGI being used is [Gunicorn]. By default, the server is hosted on `0.0.0.0:8060` with two workers.
 
+See [`snekapi.py`] and [`resources`] for API documentation.
 
-## HTTP REST API
+## Running snekbox
 
-Communication with snekbox is done over a HTTP REST API. The framework for the HTTP REST API is [Falcon](https://falconframework.org/) and the WSGI being used is [Gunicorn](https://gunicorn.org/). By default, the server is hosted on `0.0.0.0:8060` with two workers.
+A Docker image is available on [Docker Hub]. A container can be started with the following command, which will also pull the image if it doesn't currently exist locally:
 
-See [`snekapi.py`](snekbox/api/snekapi.py) and [`resources`](snekbox/api/resources) for API documentation.
+```
+docker run --ipc=none --privileged -p 8060:8060 pythondiscord/snekbox
+```
+
+To run it in the background, use the `-d` option. See the documentation on [`docker run`] for more information.
+
+The above command will make the API accessible on the host via `http://localhost:8060/`. Currently there's only one endpoint: `http://localhost:8060/eval`.
 
 ## Development Environment
 
 ### Initial Setup
 
-A Python 3.8 interpreter and the [pipenv](https://docs.pipenv.org/en/latest/) package are required. Once those requirements are satisfied, install the project's dependencies:
+A Python 3.8 interpreter and the [pipenv] package are required. Once those requirements are satisfied, install the project's dependencies:
 
 ```
 pipenv sync
@@ -122,7 +120,7 @@ The HTML will output to `./htmlcov/` by default
 
 ### The `devsh` Helper Script
 
-This script starts an `bash` shell inside the venv Docker container and attaches to it. Unlike the production image, the venv image that is built by this script contains dev dependencies too. The project directory is mounted inside the container so any filesystem changes made inside the container affect the actual local project.
+This script starts a `bash` shell inside the venv Docker container and attaches to it. Unlike the production image, the venv image that is built by this script contains dev dependencies too. The project directory is mounted inside the container so any filesystem changes made inside the container affect the actual local project.
 
 #### Usage
 
@@ -143,3 +141,15 @@ nsjpy "print('hello world!')"
 ```
 
 The alias can be found in `./scripts/.profile`, which is automatically added when the shell is launched in the container.
+
+[1]: https://dev.azure.com/python-discord/Python%20Discord/_apis/build/status/Snekbox?branchName=master
+[2]: https://dev.azure.com/python-discord/Python%20Discord/_build/latest?definitionId=13&branchName=master
+[`snekbox.cfg`]: snekbox.cfg
+[`snekapi.py`]: snekbox/api/snekapi.py
+[`resources`]: snekbox/api/resources
+[`docker run`]: https://docs.docker.com/engine/reference/commandline/run/
+[nsjail]: https://github.com/google/nsjail
+[falcon]: https://falconframework.org/
+[gunicorn]: https://gunicorn.org/
+[docker hub]: https://hub.docker.com/r/pythondiscord/snekbox
+[pipenv]: https://docs.pipenv.org/en/latest/