From 1bd6c4f34290817258e151f1ef0eb3522fd1c012 Mon Sep 17 00:00:00 2001 From: Justin DiPierro Date: Tue, 24 Jul 2018 22:06:40 -0400 Subject: [PATCH 1/5] Dockerfile and startup script --- Dockerfile | 10 ++++++++++ docker_start.sh | 25 +++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 Dockerfile create mode 100644 docker_start.sh diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..a8dd95723e --- /dev/null +++ b/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"] \ No newline at end of file diff --git a/docker_start.sh b/docker_start.sh new file mode 100644 index 0000000000..fba7bbe6ed --- /dev/null +++ b/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} \ No newline at end of file From 105354cc6e15ec927482b45d5e624dfcf228a3fd Mon Sep 17 00:00:00 2001 From: Justin DiPierro Date: Tue, 24 Jul 2018 22:07:04 -0400 Subject: [PATCH 2/5] Docker Compose example --- examples/docker-compose/docker-compose.yml | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 examples/docker-compose/docker-compose.yml diff --git a/examples/docker-compose/docker-compose.yml b/examples/docker-compose/docker-compose.yml new file mode 100644 index 0000000000..e3de7b5b3c --- /dev/null +++ b/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 \ No newline at end of file From 1b1c3132f5f40a0cbad2bb315b2688f186b2c3ef Mon Sep 17 00:00:00 2001 From: Justin DiPierro Date: Tue, 24 Jul 2018 22:07:16 -0400 Subject: [PATCH 3/5] First pass at Docker docs --- docs/running-locust-distributed.rst | 6 +++ docs/running-locust-docker.rst | 57 +++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 docs/running-locust-docker.rst diff --git a/docs/running-locust-distributed.rst b/docs/running-locust-distributed.rst index 4f2633e80d..d0cb704871 100644 --- a/docs/running-locust-distributed.rst +++ b/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 ============================================= diff --git a/docs/running-locust-docker.rst b/docs/running-locust-docker.rst new file mode 100644 index 0000000000..996f50c1fc --- /dev/null +++ b/docs/running-locust-docker.rst @@ -0,0 +1,57 @@ +.. _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. + + +Running in Docker Compose +--------------------------------------------- + +While developing your locustfile it can be helpful to run it locally. Here's an example of a basic Docker Compose file showing Locust running distributed: + +.. literalinclude:: ../examples/docker-compose/docker-compose.yml + +When running in Docker Compose you'll probably want the locust containers to be placed in the same Docker network as your application. If you already have a ``docker-compose.yml`` for your application you could copy the example compose file into the same directory named ``docker-compose.locust.yml`` and then start your stack with: + +``docker-compose -f docker-compose.yml -f docker-compose.locust.yml up`` + +This will ensure that your application and the locust containers are placed in the same network and can easily communicate. \ No newline at end of file From acdf33af976f747ba17badefca848a5b8c1ff4f7 Mon Sep 17 00:00:00 2001 From: Justin DiPierro Date: Wed, 25 Jul 2018 07:22:03 -0400 Subject: [PATCH 4/5] Attempt to add docker build to travis matrix --- .travis.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.travis.yml b/.travis.yml index 7cd6ae159d..1436d099ae 100644 --- a/.travis.yml +++ b/.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: From cb624ebacdb2983ceecc50c1aee21141dd7cd95c Mon Sep 17 00:00:00 2001 From: Justin Date: Tue, 14 Aug 2018 18:08:34 -0400 Subject: [PATCH 5/5] Remove Docker Compose docs I've found it easier to run locust locally in standalone mode while developing the locustfile. The example docker-compose file still exists though. --- docs/running-locust-docker.rst | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/running-locust-docker.rst b/docs/running-locust-docker.rst index 996f50c1fc..7841f1fddc 100644 --- a/docs/running-locust-docker.rst +++ b/docs/running-locust-docker.rst @@ -41,17 +41,3 @@ 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. - - -Running in Docker Compose ---------------------------------------------- - -While developing your locustfile it can be helpful to run it locally. Here's an example of a basic Docker Compose file showing Locust running distributed: - -.. literalinclude:: ../examples/docker-compose/docker-compose.yml - -When running in Docker Compose you'll probably want the locust containers to be placed in the same Docker network as your application. If you already have a ``docker-compose.yml`` for your application you could copy the example compose file into the same directory named ``docker-compose.locust.yml`` and then start your stack with: - -``docker-compose -f docker-compose.yml -f docker-compose.locust.yml up`` - -This will ensure that your application and the locust containers are placed in the same network and can easily communicate. \ No newline at end of file