# proxy

This proxy is based on NGINX. The NGINX configuration is generated by a simple Node.js script which parses
the docker socket. NGINX acts as a reverse proxy server. The Node.js script reads the docker socket file to generate
a configuration for each running docker container. The base template for configuration is `nginx.conf.template`
All `*.template` files are written with [mustache-js](https://github.com/janl/mustache.js 'GitHub') syntax.
The templates are assembled by the Node.js program.

**Important:**

The proxy expects your backend containers to provide following structure:

- Service name for the backend container has to be `backend` in docker-compose.yml. If you don't use docker-compose
  set `com.docker.compose.service`-label to `backend`.
- Set the `stapps.version`-label of the container/service to coresponing the backend version
- The proxy container has to be executed with `--net=host`
- Port 80 or 443 being free for exclusive use by the proxy container
- Always publish the backend container ports to the host machines internal loopback interface or an interace you control. This is the only way communication with the internet is restricted to going through the proxy. E.g this can be achieved by the `ports` syntax `127.0.0.1:3000-4000:3000` in the docker-compose file (here with a random port to avoid collisions).

## SSL/TLS

For a working https configuration you need to have a valid certificate **_including the intemediate certificas without the root_** (_.crt file ) and its private key (_.key file) in two **_seperate_** files. In addition to your certificate you need to provide the certificate chain **_including_** the root certificate. [Read up on](https://medium.com/@superseb/get-your-certificate-chain-right-4b117a9c0fce) how to [create this chain](https://blog.pki.dfn.de/2015/06/ocsp-stapling-in-nginx/) (\*.crt file) or ask your admins to provide you one. The final and easiest requirement of the ssl setup is to create custom Diffie-Hellman parameters in a file:

```sh
openssl dhparam -out dhparams.pem 4096
```

## Configuration file

To Provide your own configuration file you can create a `default.json` file in the `config` directory. The JSON structure has to follow `config/default.ts`. Adding this file via docker mount is also possible (eg. `-v <path JSON file>:/app/config/default.json`)

## Status Codes

- OutdatedVersions return a `HTTP 404`
- ActiveVersions return a `HTTP 503` if currently unavailable or the given code by running backend-node
- Unsupported versions (not configured as outdated or active) return a `HTTP 404`
- No version header given returns a `HTTP 300`

**NOTE:** The default configuration expects the client to set a version header: `X-StApps-Version=<version of app>`

## Logger

The proxy uses [@openstapps/logger](https://gitlab.com/openstapps/logger). You can provide `NODE_ENV=production`
and SMTP-Configuration via environment-variables for monitoring in production use.

## Usage

The Node.js script reads out the `/var/run/docker.sock` to get the containers of the host system via
[dockerode](https://github.com/apocas/dockerode 'GitHub').

Without ssl:

```sh
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock --net="host" registry.gitlab.com/openstapps/proxy/master
```

With ssl:

```sh
docker run --rm --net="host" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v <path to *.crt-file>:/etc/nginx/certs/ssl.crt \
    -v <path to *.key-file>:/etc/nginx/certs/ssl.key \
    -v <path to certificate chain (*.crt) file>:/etc/nginx/certs/chain.crt \
    -v <path to dhparam.pem file>:/etc/nginx/certs/dhparam.pem \
    -v <path RECIPIENTS file>:/app/config/RECIPIENTS \
    registry.gitlab.com/openstapps/proxy/master
```

## Static Folder (docker run option: `-v <path to static folder>:/static`)

Der Zugriff erfolgt über: `http(s)://<url>/_static/<path-to-file>`

Beispiel Proxy auf Localhost für die Datei `static/test.json`: `http://localhost/_static/test.json`

## Bilder im Static Folder

Bilder sollten folgendermaßen abgelegt und benannt werden:

`<pfad analog zur imageURL aus der App>/<type>/<uid>-<size>.[jpg|png|gif]`

Beispiel:
`_static/images/Place/hautpmensa-thumbnail.jpg`

Aufgerufen wird das mit:
'https://server.deiner.uni.de/_static/images/Place/hauptmensa-thumbnail'

Bildgrößen sind: thumbnail, small, medium, large
