readme.md 7.48 KB
Newer Older
Siebers, Michael's avatar
Siebers, Michael committed
1
# Dare2Del Demonstrator – WebAPI
Sebastian Seufert's avatar
Sebastian Seufert committed
2

Siebers, Michael's avatar
Siebers, Michael committed
3 4
The Dare2Del Demonstrator identifies irrelevant files in the user's file system and suggests to delete them. This project provides the required reasoning facilities as Service over HTTP. This component holds all parts required to answer whether some file is irrelevant and to explain why this is the case. 
Basically, the core logic is encapsulated into a web-based API that receives and responds JSON objects:
Sebastian Seufert's avatar
Sebastian Seufert committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20


```mermaid
sequenceDiagram
    participant Client
    
    participant API
    Client->>API: HTTP Request
    API-->>Theory: Query
    loop Rules & Learning
        Theory-->>Theory: Irrelevancy / Explanation
    end
    Theory-->>API: Query Results
    API->>Client: HTTP Response
```

Siebers, Michael's avatar
Siebers, Michael committed
21
## Running the server
Siebers, Michael's avatar
Siebers, Michael committed
22 23 24
The WebAPI server is implemented as [SWI-Prolog](https://www.swi-prolog.org/) 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.
Siebers, Michael's avatar
Siebers, Michael committed
25 26
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](https://docker.com) container (see [below](#docker-container)). 
Siebers, Michael's avatar
Siebers, Michael committed
27

Siebers, Michael's avatar
Siebers, Michael committed
28
Before starting the server, you have to clone the git repository.
Siebers, Michael's avatar
Siebers, Michael committed
29 30 31 32 33 34

```bash
    git clone git@gitlab.rz.uni-bamberg.de:cogsys/dare2del/demonstrator.git demonstrator-webapi
    cd demonstrator-webapi
```

Siebers, Michael's avatar
Siebers, Michael committed
35 36
### Interactive Mode
The interactive mode is started using the `run.pl` script. You may supply a custom port that the server will listen on (default is 4444).
Siebers, Michael's avatar
Siebers, Michael committed
37 38 39 40 41 42

```bash
    swipl run.pl
    swipl run.pl --port 4444
```

43
After some informational messages (starting with `%`) you will see the interactive prolog interpreter. Then the server is running and accepting requests at localhost:PORT as given in the last informational message.
Siebers, Michael's avatar
Siebers, Michael committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

```
    % Loading explanation templates from file irrelevance_templates:
    %     file/1
    %     abs_path/2
    %     file_size/2
    %     directory/1
    %     in_directory/2
    %     in_directory_recursive/2
    %     in_directory_recursive/2
    %     item_name/2
    %     creation_time/2
    %     change_time/2
    %     modification_time/2
    %     access_time/2
    %     newer/2
    %     same_directory/2
    % Started server at http://localhost:4444/

    Welcome to SWI-Prolog (threaded, 64 bits, version 8.2.2)
    SWI-Prolog comes with ABSOLUTELY NO WARRANTY. This is free software.
    Please run ?- license. for legal details.

    For online help and background, visit https://www.swi-prolog.org
    For built-in help, use ?- help(Topic). or ?- apropos(Word).

    ?-
```

Siebers, Michael's avatar
Siebers, Michael committed
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
You may freely use the Prolog interpreter while the server is running.
The server access log is stored in the file `log.txt` in the working directory. To stop the server enter `server_stop.`

### Daemon Mode
> Please note that the _daemon_ mode requires a unix-like operation system to run!

The server is started and stopped in _daemon_ mode using the `daemon.pl` script. As in _interactive_ mode, the server listens on port 4444 per default. This may be configured using the `--port` command line switch.

```bash
    swipl daemon.pl
    swipl daemon.pl --port 4444
```

After some informational messages (starting with `%`), control is given back to the calling process (the command line) as soon as the server has started successfully. Further output is discarded. (_This includes the informational message that the server has started up successfully._)

```
    % Loading explanation templates from file irrelevance_templates:
    %     file/1
    %     abs_path/2
    %     file_size/2
    %     directory/1
    %     in_directory/2
    %     in_directory_recursive/2
    %     in_directory_recursive/2
    %     item_name/2
    %     creation_time/2
    %     change_time/2
    %     modification_time/2
    %     access_time/2
    %     newer/2
    %     same_directory/2
```

The server access log is stored in the file `log.txt` in the working directory.
You may use the `--outfile` command line switch to capture the Prolog output after successful server start.

```bash
    swipl daemon.pl --outfile daemon.out
```

The daemon is stopped using the `--shutdown` command line switch.

```bash
    swipl daemon.pl --shutdown
```

Siebers, Michael's avatar
Siebers, Michael committed
119 120 121 122 123 124 125 126 127 128
### 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:

```bash
    docker image pull docker-registry.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/webapi
```

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
129
- **vx-y-z**: build of the corresponding version (starting with v1.0.2/v1-0-2)
Siebers, Michael's avatar
Siebers, Michael committed
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149

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.

```bash
    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.

```bash
    docker run -p "5555:80" docker-registry.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/webapi
```

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 |
150
| WORKERS | Determine the number of worker threads. Default is fine for medium scale usage. | 10 |
Siebers, Michael's avatar
Siebers, Michael committed
151 152 153

_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`).

154
For example, to serve on port 8080 using 20 worker threads and to store the Prolog output in file `/app/output`:
Siebers, Michael's avatar
Siebers, Michael committed
155 156

```bash
157
    docker run -e PORT=8080 -e OUT_FILE=output -e WORKERS=20 \
Siebers, Michael's avatar
Siebers, Michael committed
158 159 160
            docker-registry.rz.uni-bamberg.de/cogsys/dare2del/demonstrator/webapi
```

Siebers, Michael's avatar
Siebers, Michael committed
161 162

## Documentation
163
[^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.
Sebastian Seufert's avatar
Sebastian Seufert committed
164

Siebers, Michael's avatar
Siebers, Michael committed
165
The Dare2Del Demonstrator WebAPI component serves its own documentation. Unless turned off (see [Admin Guide](http://localhost:4444/doc/admin_guide.html)[^local]), the documentation may be accessed under [/doc](http://localhost:4444/doc)[^local]. Notably the following documents are available:
Sebastian Seufert's avatar
Sebastian Seufert committed
166

Siebers, Michael's avatar
Siebers, Michael committed
167
1. A [detailed description of the API endpoints](http://localhost:4444/doc/api_endpoints.html)[^local]
168
1. A [file-by-file documentation of Prolog predicates](http://localhost:4444/doc/pldoc/doc/_API_/index.html)[^local]
Sebastian Seufert's avatar
moving  
Sebastian Seufert committed
169

Siebers, Michael's avatar
Siebers, Michael committed
170
---