Commit 671fd66d authored by Siebers, Michael's avatar Siebers, Michael
Browse files

document docker image

parent 91281e97
......@@ -85,6 +85,7 @@ The _daemon_ mode supports all options of the _interactive_ mode. Additionally,
| --pidfile | | The file the PID of the running server shall be/is stored | `` |
| --outfile | | The file additional prolog output is stored in | _equivalent to_ =|/dev/null|= |
| --shutdown | | Shuts down a running server. Ignores all options except =|--pidfile|= | `false` |
| --user | | When started as root, this option must be provided to switch to the target user for operating the server. | `none` |
When starting the server, predicates loaded from the irrelevance template file are reported. On successful startup further messages are discarded or writen to the file denoted with =|--outfile|=.
......@@ -22,7 +22,8 @@ sequenceDiagram
The WebAPI server is implemented as [SWI-Prolog]( program using several libraries. It requires SWI-Prolog version 8.2.2 or above to run.
The server may operate in two different modes: in _interactive_ mode or as a unix _deamon_.
In the _interactive_ mode the server is running as background _thread_ within the interactive prolog interpreter. This mode allows to inspect and debug the running of the server as well as to apply changes on the fly.
On the other hand, the server runs as background _process_ of the operating system in _daemon_ mode. This mode is intended for production use.
On the other hand, the server runs as background _process_ of the operating system in _daemon_ mode. This mode is intended for production use.
Additional to manually starting the server, the _daemon_ mode can be started as [Docker]( container (see [below](#docker-container)).
Before starting the server, you have to clone the git repository.
......@@ -115,6 +116,47 @@ The daemon is stopped using the `--shutdown` command line switch.
swipl --shutdown
### Docker Container
The _daemon_ mode is ideal to be run in a docker container. For this, we provide docker images in the project Container Repository. To get an image, pull it using docker:
docker image pull
Images are based on Debian 9 and use SWI-Prolog 8.2.2. Tags for the following builds are available:
- **latest**: the latest build of the master branch
- **vx.y.z**: build of the corresponding version (starting with v.1.0.2)
Alternatively, you may build the image yourself. Assuming you have already cloned the git repository, you may build the image in the main directory. For simpler reference, you should tag the image, e.g. 'webapi:custom'. Then you may use this name instead of the url to our image in the following descriptions.
docker build --tag webapi:custom .
The image may be run without further configuration. Per default, the daemon is serving HTTP requests at port 80 and is discarding Prolog output after successful server start. As usual, the container port can be published to the host machine, e.g. to port 5555.
docker run -p "5555:80"
The daemon in the container may not be configured with command line arguments, but with environment variables. The following variables are available:
| Environment Variable | Description | Default |
| --- | --- | --- |
| LOG_FILE | Location to place the servers log file | webapi.log |
| OUT_FILE | Location to store the Prolog output after successful start. | /dev/null |
| PORT | The port to serve. | 80 |
_Please note_: The daemon starts up as user root. After startup, the daemon drops root priviledges and continues as user webapi. Thus, the locations `LOG_FILE` and `OUT_FILE` must be writeable for user webapi (by default only the main working directory `/app`).
For example, to serve on port 8080 and to store the Prolog output in file `/app/output`:
docker run -e PORT=8080 -e OUT_FILE=output \
## Documentation
[^local]: Links to localhost in section _Documentation_ assume that you started the server without explicit port option. If you started the server under another port, please replace `4444` accordingly.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment