Server Installation (leash)

The server can be launched from a virtualenv or a docker container.

Even if it is not mandatory, we recommend to run the service over TLS, gunicorn can do it since version 17.0. Alternativelly, you can use any reverse proxy you are used to.

Also, Flask ship an internal webserver, it should be avoided on production, just use a dedicated WSGI HTTP Server like gunicorn or wsgi.

Table of Contents

• Server Installation (leash)
  • Using virtualenv
    • Running the service
      • Using flask internal webserver
      • Using gunicorn
  • Using Docker container
    • Building the image
    • Running the service

The server is the central point of authorization and configuration. Run it on a server reachable by your clients (docker daemon). For a better availability, don’t hesitate to scale your deployment.

Using virtualenv

Install Docker Leash in a virtualenv

$ virtualenv venv
$ source ./venv/bin/activate
$ pip install docker-leash
$ pip install -r requirements.txt

Running the service

Using flask internal webserver

Launch Docker Leash using Flask internal server.

$ export FLASK_APP=docker_leash.leash_server.py
$ python -m flask run --host 0.0.0.0 --port 80
 * Running on http://[::]:80/

Using gunicorn

Launch Docker Leash with gunicorn.

$ gunicorn --workers=5 --bind=[::]:80 --reload \
  docker_leash.leash_server:app

If you choose to support TLS directly with gunicorn, just add options certfile, keyfile, ciphers and change port listen port to 443:

Launch gunicorn with TLS support.

$ gunicorn --workers=5 --bind=[::]:443 --reload \
  --certfile=/certs/server.crt --keyfile=/certs/server.key \
  --ciphers=TLSv1.2 \
  docker_leash.leash_server:app

Using Docker container

Warning

Of course, the docker-leash server could be deployed as a Docker container, but be careful to don’t brick yourself by running the container on the same host as the one you want to secure.

We publish ready to use container images on Docker Hub, please have a look at our docker repository.

Building the image

You may want to build the image yourself.

Build docker image from sources.

$ git clone https://github.com/docker-leash/leash-server.git
$ cd leash-server
$ docker build -t leash-server .

Running the service

You can simply launch the service using docker cli or docker-compose. Don’t forget to mount the configuration over the respective files.

Launch docker-leash using docker.

$ docker run \
  -d \
  -p 443:443 \
  -v /path/to/your/certs/:/certs:ro \
  -v /path/to/your/conf/groups.yml:/srv/docker-leash/groups.yml:ro \
  -v /path/to/your/conf/policies.yml:/srv/docker-leash/policies.yml:ro \
  --certfile=/certs/server.crt --keyfile=/certs/server.key \
  --ciphers=TLSv1.2 \
  dockerleash/leash-server:latest \
  gunicorn --workers=5 --bind=[::]:443 app.leash_server:app

docker-compose.yml

version: '2'

services:
  leashserver:
    image: dockerleash/leash-server:latest
    command: gunicorn --workers=5 --bind=[::]:443 --chdir=/srv/docker-leash \
      --certfile=/certs/server.crt --keyfile=/certs/server.key \
      --ciphers=TLSv1.2 \
      docker_leash.leash_server:app
    volumes:
      - /path/to/your/certs/:/certs:ro
      - /path/to/your/conf/groups.yml:/srv/docker-leash/groups.yml:ro
      - /path/to/your/conf/policies.yml:/srv/docker-leash/policies.yml:ro
    ports:
      - "443:443"
    restart: always

Alternatively, you can build a child image including your configuration.

Your personnal Dockerfile

FROM dockerleash/leash-server:latest
COPY configuration/*.yml /srv/docker-leash/
COPY certs/* /certs/

Note

The current command launched from the image doesn’t include TLS options, and listen by default on port 80. Indeed, the bind mount of /certs, is optionnal.

Next, read Client Installation (json) if your planned rules don’t rely on clients hostname or images/containers names else Collar Installation (client).