Remove docker_start.sh script. Instead set locust as entrypoint for official Docker image.

Dockerfile

@@ -16,7 +16,7 @@ RUN chmod +x docker_start.sh
 EXPOSE 8089 5557
 
 USER locust
-CMD ["./docker_start.sh"]
+ENTRYPOINT ["locust"]
 
 # turn off python output buffering
 ENV PYTHONUNBUFFERED=1

docker_start.sh

@@ -1,25 +0,0 @@
-#!/usr/bin/env sh
-
-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}" = "worker" ]; then
-    if [ -z "${LOCUST_MASTER_HOST}" ]; then
-        echo "ERROR: MASTER_HOST is empty. Worker mode requires a master" >&2
-        exit 1
-    fi
-
-    _LOCUST_OPTS="${_LOCUST_OPTS} --worker --master-host=${LOCUST_MASTER_HOST} --master-port=${LOCUST_MASTER_PORT:-5557}"
-fi
-
-echo "Starting Locust in ${LOCUST_MODE} mode..."
-echo "$ locust ${LOCUST_OPTS} ${_LOCUST_OPTS}"
-
-exec locust ${LOCUST_OPTS} ${_LOCUST_OPTS}

docs/changelog.rst

@@ -28,6 +28,9 @@ Breaking changes
           print("test is stopping")
 * ``TaskSequence`` and ``@seq_task`` has been replaced with :ref:`SequentialTaskSet <sequential-taskset>`.
 * A ``User count`` column has been added to the history stats CSV file. The column order and column names has been changed.
+* The official docker image no longer uses a shell script with a bunch of special environment variables to configure how 
+  how locust is started. Instead, the ``locust`` command is now set as ``ENTRYPOINT`` of the docker image. See
+  :ref:`running-locust-docker` for more info.
 
 
 0.14.0

docs/running-locust-docker.rst

@@ -4,59 +4,31 @@
 Running Locust with Docker
 =================================
 
-To keep things simple we provide a single Docker image that can run standalone, as a master, or as a worker.
+The official Docker image is currently found at `locustio/locust <https://hub.docker.com/r/locustio/locust>`_.
 
-Environment Variables
----------------------------------------------
+The docker image can be used like this (assuming that the ``locustifile.py`` exists in the current working directory)::
 
-- ``LOCUST_MODE``
+    docker run -p 8089:8089 -v $PWD:/mnt/locust locustio/locust -f /mnt/locust/locustfile.py
 
-One of 'standalone', 'master', or 'worker'. Defaults to 'standalone'.
 
-- ``LOCUSTFILE_PATH``
+Docker Compose
+==============
 
-The path inside the container to the locustfile. Defaults to '/locustfile.py'
+Here's an example Docker Compose file that could ber used to start both a master node, and slave nodes:
 
-- ``LOCUST_MASTER_HOST``
+.. literalinclude:: ../examples/docker-compose/docker-compose.yml
+    :language: yaml
 
-The hostname of the master.
+The above compose configuration could be used to start a master node and 4 workers using the following command::
 
-- ``LOCUST_MASTER_PORT``
+    docker-compose up --scale worker=4
 
-The port used to communicate with the master. Defaults to 5557.
 
-- ``LOCUST_OPTS``
+Use docker image as a base image
+================================
 
-Additional options to pass to locust. Defaults to ''
-
-Running 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``:
-
-.. code-block:: docker
+It's very common to have test scripts that rely on third party python packages. In those cases you can use the 
+official Locust docker image as a base image::
 
     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.
-
-For debugging locally you can run a container and pass your locustfile in as a volume:
-
-.. code-block:: console
-
-    docker run -p 8089:8089 --volume $PWD/dir/of/locustfile:/mnt/locust -e LOCUSTFILE_PATH=/mnt/locust/locustfile.py -e TARGET_URL=https://abc.com locustio/locust
-
-
-To run in standalone mode without the web UI, you can use the ``LOCUST_OPTS`` environment variable to add the required options:
-
-.. code-block:: console
-
-    docker run --volume $PWD/dir/of/locustfile:/mnt/locust -e LOCUSTFILE_PATH=/mnt/locust/locustfile.py -e TARGET_URL=https://abc.com -e LOCUST_OPTS="--clients=10 --headless --run-time=600" locustio/locust
-
-
-If you are Kubernetes user, you can use the `Helm chart <https://github.com/helm/charts/tree/master/stable/locust>`_ to scale and run locust.
+    RUN pip3 install some-python-package

examples/docker-compose/docker-compose.yml

@@ -1,25 +1,16 @@
-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
+version: '3'
 
 services:
-  locust-master:
-    <<: *common
+  master:
+    image: locustio/locust
     ports:
-      - 8089:8089
-    environment:
-      <<: *common-env
-      LOCUST_MODE: master
+     - "8089:8089"
+    volumes:
+      - ./:/mnt/locust
+    command: -f /mnt/locust/locustfile.py --master -H http://master:8089
   
-  locust-worker:
-    <<: *common
-    environment:
-      <<: *common-env
-      LOCUST_MODE: worker
-      LOCUST_MASTER_HOST: locust-master
+  worker:
+    image: locustio/locust
+    volumes:
+      - ./:/mnt/locust
+    command: -f /mnt/locust/locustfile.py --worker --master-host master