Official Docker image and documentation

.travis.yml

@@ -11,6 +11,8 @@ matrix:
       env: TOXENV=py34
     - python: 2.7
       env: TOXENV=py27
+    - stage: Verify Docker image builds
+      script: docker build -t locustio/locust .
 addons:
   apt:
     packages:

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.6
+
+RUN pip install locustio pyzmq
+
+ADD docker_start.sh /usr/bin/docker_start
+RUN chmod 755 /usr/bin/docker_start
+
+EXPOSE 8089 5557 5558
+
+CMD ["docker_start"]

docker_start.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+if [ -z "${TARGET_URL}" ]; then
+  echo "ERROR: TARGET_URL not configured" >&2
+  exit 1
+fi
+
+LOCUST_MODE="${LOCUST_MODE:=standalone}"
+LOCUST_OPTS="-f ${LOCUSTFILE_PATH:-/locustfile.py} -H ${TARGET_URL}"
+
+if [ "${LOCUST_MODE}" = "master" ]; then
+    LOCUST_OPTS="${LOCUST_OPTS} --master"
+elif [ "${LOCUST_MODE}" = "slave" ]; then
+    if [ -z "${LOCUST_MASTER_HOST}" ]; then
+        echo "ERROR: MASTER_HOST is empty. Slave mode requires a master" >&2
+        exit 1
+    fi
+
+    LOCUST_OPTS="${LOCUST_OPTS} --slave --master-host=${LOCUST_MASTER_HOST} --master-port=${LOCUST_MASTER_PORT:-5557}"
+fi
+
+echo "Starting Locust..."
+echo "$ locust ${LOCUST_OPTS}"
+
+locust ${LOCUST_OPTS}

docs/running-locust-distributed.rst

@@ -81,6 +81,12 @@ Used when starting the master node with ``--no-web``. The master node will then
 nodes has connected before the test is started.
 
 
+Running distributed with Docker
+=============================================
+
+See :ref:`running-locust-docker`
+
+
 Running Locust distributed without the web UI
 =============================================
 

docs/running-locust-docker.rst

@@ -0,0 +1,43 @@
+.. _running-locust-docker:
+
+=================================
+Running Locust with Docker
+=================================
+
+To keep things simple we provide a single Docker image that can run standalone, as a master, or as a slave. 
+
+
+Environment Variables
+---------------------------------------------
+
+- ``LOCUST_MODE``
+
+One of 'standalone', 'master', or 'slave'. Defaults to 'standalone'.
+
+- ``LOCUSTFILE_PATH``
+
+The path inside the container to the locustfile. Defaults to '/locustfile.py`
+
+- ``LOCUST_MASTER_HOST``
+
+The hostname of the master.
+
+- ``LOCUST_MASTER_PORT``
+
+The port used to communicate with the master. Defaults to 5557.
+
+
+Add your tests
+---------------------------------------------
+
+The easiest way to get your tests running is to build an image with your test file built in. Once you've 
+written your locustfile you can bake it into a Docker image with a simple ``Dockerfile``:
+
+```
+FROM locustio/locust
+ADD locustfile.py locustfile.py
+```
+
+You'll need to push the built image to a Docker repository such as Dockerhub, AWS ECR, or GCR in order for
+distributed infrastructure to be able to pull the image. See your chosen repository's documentation on how
+to authenticate with the repository to pull the image.

examples/docker-compose/docker-compose.yml

@@ -0,0 +1,25 @@
+version: "3.4"
+
+x-common: &common
+  image: locustio/locust
+  environment: &common-env
+    TARGET_URL: http://locust-master:8089
+    LOCUSTFILE_PATH: /tests/basic.py
+  volumes:
+    - ../:/tests
+
+services:
+  locust-master:
+    <<: *common
+    ports:
+      - 8089:8089
+    environment:
+      <<: *common-env
+      LOCUST_MODE: master
+
+  locust-slave:
+    <<: *common
+    environment:
+      <<: *common-env
+      LOCUST_MODE: slave
+      LOCUST_MASTER_HOST: locust-master