{"id":13557685,"url":"https://github.com/zalando-incubator/docker-locust","last_synced_at":"2025-04-03T12:30:57.058Z","repository":{"id":49378150,"uuid":"52012685","full_name":"zalando-incubator/docker-locust","owner":"zalando-incubator","description":"Docker image for the Locust.io open source load testing tool","archived":true,"fork":false,"pushed_at":"2021-06-01T10:58:33.000Z","size":314,"stargazers_count":204,"open_issues_count":9,"forks_count":66,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-11-04T08:35:34.794Z","etag":null,"topics":["docker-locust","load-testing","loadtest","locust","performanceanalytics","testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zalando-incubator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2016-02-18T14:23:09.000Z","updated_at":"2024-09-15T16:57:08.000Z","dependencies_parsed_at":"2022-09-01T00:22:46.876Z","dependency_job_id":null,"html_url":"https://github.com/zalando-incubator/docker-locust","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando-incubator%2Fdocker-locust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando-incubator%2Fdocker-locust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando-incubator%2Fdocker-locust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando-incubator%2Fdocker-locust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zalando-incubator","download_url":"https://codeload.github.com/zalando-incubator/docker-locust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247002178,"owners_count":20867416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-locust","load-testing","loadtest","locust","performanceanalytics","testing"],"created_at":"2024-08-01T12:04:29.435Z","updated_at":"2025-04-03T12:30:56.608Z","avatar_url":"https://github.com/zalando-incubator.png","language":"Python","funding_links":[],"categories":["Python","testing"],"sub_categories":[],"readme":"Docker-Locust\n=============\n\n[![Build Status](https://travis-ci.org/zalando-incubator/docker-locust.svg?branch=master)](https://travis-ci.org/zalando-incubator/docker-locust)\n[![codecov](https://codecov.io/gh/zalando-incubator/docker-locust/branch/master/graph/badge.svg)](https://codecov.io/gh/zalando-incubator/docker-locust)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/5a235d56b27647f9b73982933c00314a)](https://www.codacy.com/app/butomo1989/docker-locust?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=zalando-incubator/docker-locust\u0026amp;utm_campaign=Badge_Grade)\n\nThe purpose of this project is to provide a ready and easy-to-use version of [locust.io] which also contains additional/useful features that are required.\n\nArchitecture\n------------\nDocker-Locust container can be started in 4 different roles:\n\n- `master`: Runs Locust's web interface where you start and stop the load test and see live statistics.\n- `slave`: Simulates users and attacks the target url based on user parameters.\n- `controller`: Orchestrates Master in automatic mode and downloads reports when the test is over.\n- `standalone`: Automatically starts the above components locally.\n\nThere are 2 supported run types:\n- Manual: when a user manually starts and stops a test via a Locust Master UI.\n- Automatic: when a test is started by the Controller and runs for a specified time interval.\n\nAnd there are 2 ways to deploy it:\n- Local deployment (using `standalone` mode or [docker-compose]): when a singe machine can generate enough traffic.\n- Distributed deployment: when multiple machines are required to generate a bigger load. This type of deployment might be used in AWS or Kubernetes.\nAn example deployment with different container roles can be found in [docker-compose].\nUsing Automatic mode together with Distributed deployment requires the `TOTAL_SLAVES` variable to be set on the `controller` side. \n\nKey advantages\n--------------\n\n1. It allows locust to read load test scenario/script from different resources (any HTTP/HTTPS URL, S3 bucket, and local machine).\n2. It has the ability to be run in any CI tool e.g. [Jenkins] (It can start/stop load test automatically) and provides an HTML report at the end of a load test.\n3. It is also possible to be deployed in AWS to create bigger load.\n\nRequirements\n------------\n1. [docker engine] version 1.9.1+\n2. [docker-compose] version 1.6.0+ (optional)\n\nGetting Started\n---------------\n\n### Single machine / Standalone mode\n---\n\ndocker-locust will be run as **standalone** version by default. Standalone version is for users who has only 1 single machine.\n\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy\n```\n\nYou will be prompted for certains inputs required (You can use [our example] in github as load test script).\n\n```\nTarget url: https://targeturl.com\nWhere load test script is stored: https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py\nNumber of slave(s): 4\nRun type [automatic/manual]: manual\n```\n\n*All of it can be simplify in one line:*\n\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy --target=https://targeturl.com --locust-file=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py --slaves=4 --mode=manual\n```\n\nIt is also possible to run with normal docker command:\n\n```bash\ndocker run -i --rm -v $PWD/reports:/opt/reports -v ~/.aws:/root/.aws -v $PWD/:/opt/script -v $PWD/credentials:/meta/credentials -p 8089:8089 -e ROLE=standalone -e TARGET_HOST=https://targeturl.com -e LOCUST_FILE=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py -e SLAVE_MUL=4 -e AUTOMATIC=False registry.opensource.zalan.do/tip/docker-locust\n```\n\n### Multiple machines\n---\n\ndocker-locust can be run in multiple docker-containers. It is useful for users who has more than one machine to create bigger load. In this point we are using docker-compose, but it is also possible to run it in different ways, e.g. Cloudformation in AWS.\n\nRun the application with the command:\n\n```bash\nDOCKER_COMPOSE=true bash \u003c(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy\n```\n\nRead multiple files\n-------------------\ndocker-locust has the ability to read multiple files from s3 or any http/https, e.g. [1 file is the load test file / python file](https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple_post.py) and [1 other file is json file](https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/payloads.json) where payloads are stored. Sample command:\n\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh) deploy --target=https://targeturl.com --locust-file=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple_post.py,https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/payloads.json --slaves=4 --mode=manual\n```\n\nReport Generation\n-----------------\n\nPlease add following lines to your load test script, like [this example].\n\n```\nfrom locust.web import app\nfrom src import report\napp.add_url_rule('/htmlreport', 'htmlreport', report.download_report)\n```\n\nSimply after load test run, append \"/htmlreport\" to the URL which will download the report of the recent run. Example:\n\n![][Download report]\n\nSetup in jenkins\n----------------\n\ndocker-locust can be run automatically by using CI tool like jenkins.\n\n**Sample case:**\n\n- Number of users [total users that will be simulated]: 100\n- Hatch rate [number of user will be added per second]: 5\n- Duration [in seconds]: 30\n- Target url: https://targeturl.com\n- Load test script: simple.py\n- Number of slaves: 4\n\n**Steps:**\n\n1. Put following command in \"Execute shell\" field:\n\n\t```bash\n\tcurl -O https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/local.sh \u0026\u0026 DOCKER_COMPOSE=true bash local.sh deploy --target=https://targeturl.com --locust-file=https://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py --slaves=4 --mode=automatic --users=100 --hatch-rate=5 --duration=30\n\t```\n\n2. Install [html-publisher-plugin] in jenkins to display load test result. Example configuration in jenkins job:\n\n ![][HTML-Publisher configuration]\n\nTroubleshooting\n---------------\n\nAll output from containers can be see by running:\n\n```bash\ndocker-compose logs -f\n```\n\nAbout the project versioning\n----------------------------\nA version number is combination between the locust version being supported and patch level, e.g. when a release is 0.7.3-p0, it support locust 0.7.3.\n\nCapacity of docker-locust in AWS\n--------------------------------\n\nAll the data based on load testing against simple [hello-world] application with the default max_wait and min_wait values (1000ms).\n\n|No.   |Group Type   |EC2   |vCPU   |RAM (GiB)   |Clock Speed (GHz)   |Enhanced Networking   |Max total RPS that can be created per 1 slave machine (rough number)   |Price per hour (EU - Frankfurt)   |RPS per cent   |\n|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|\n|1|General Purpose|t2.nano|1|0.5|up to 3.3|-|200|$0.0068|294.12|\n|2|General Purpose|t2.micro|1|1|up to 3.3|-|500|$0.014|357.14|\n|3|General Purpose|t2.small|1|2|up to 3.3|-|500|$0.027|185.19|\n|4|General Purpose|t2.medium|2|4|up to 3.3|-|1100|$0.054|203.7|\n|5|General Purpose|t2.large|2|8|up to 3.0|-|1100|$0.108|101.85|\n|6|General Purpose|t2.xlarge|4|16|up to 3.0|-|2200|$0.216|101.85|\n|7|General Purpose|t2.2xlarge|8|32|up to 3.0|-|4700|$0.432|108.8|\n|8|General Purpose|m4.large|2|8|2.4|Yes|700|$0.12|58.33|\n|9|General Purpose|m4.xlarge|4|16|2.4|Yes|1500|$0.24|62.5|\n|10|General Purpose|m4.2xlarge|8|32|2.4|Yes|2500|$0.48|52.08|\n|11|General Purpose|m4.4xlarge|16|64|2.4|Yes|6500|$0.96|67.71|\n|12|General Purpose|m4.10xlarge|40|160|2.4|Yes|10000|$2.4|41.67|\n|13|General Purpose|m4.16xlarge|64|256|2.3|Yes|17000|$3.84|44.27|\n|14|General Purpose|m3.medium|1|3.75|2.5|-|250|$0.079|31.65|\n|15|General Purpose|m3.large|2|7.5|2.5|-|600|$0.158|37.97|\n|16|General Purpose|m3.xlarge|4|15|2.5|-|1300|$0.315|41.27|\n|17|General Purpose|m3.2xlarge|8|30|2.5|-|2600|$0.632|41.14|\n|18|Compute Optimized|c4.large|2|3.75|2.9|Yes|800|$0.114|70.18|\n|19|Compute Optimized|c4.xlarge|4|7.5|2.9|Yes|1600|$0.227|70.48|\n|20|Compute Optimized|c4.2xlarge|8|15|2.9|Yes|2500|$0.454|55.07|\n|21|Compute Optimized|c4.4xlarge|16|30|2.9|Yes|6500|$0.909|71.51|\n|22|Compute Optimized|c4.8xlarge|36|60|2.9|Yes|12500|$1.817|68.79|\n|23|Compute Optimized|c3.large|2|3.75|2.8|Yes|650|$0.129|50.39|\n|24|Compute Optimized|c3.xlarge|4|7.5|2.8|Yes|1300|$0.258|50.39|\n|25|Compute Optimized|c3.2xlarge|8|15|2.8|Yes|2500|$0.516|48.45|\n|26|Compute Optimized|c3.4xlarge|16|30|2.8|Yes|5500|$1.032|53.29|\n|27|Compute Optimized|c3.8xlarge|32|60|2.8|Yes|9000|$2.064|43.6|\n\n**NOTE:**\n\n1. Please check [AWS-EC2-Type] and [AWS-EC2-pricing] before use data above, because some of them could be changed time to time.\n2. Number of total RPS could be different because of n reasons.\n\nContributions\n-------------\nAny feedback or contributions are welcome! Please check our [guidelines].\n\nUnit tests\n----------\n\nRun the unit tests with this command:\n\n```bash\nlocal.sh test\n```\n\nLicense\n-------\nSee [License]\n\nSecurity\n--------\nSee [Security]\n\n[locust.io]: \u003chttp://locust.io\u003e\n[docker-compose]: \u003cdocker-compose.yaml\u003e\n[Jenkins]: \u003chttps://jenkins.io\u003e\n[docker engine]: \u003chttps://docs.docker.com/engine/installation/\u003e\n[docker-compose]: \u003chttps://docs.docker.com/compose/install/\u003e\n[our example]: \u003chttps://raw.githubusercontent.com/zalando-incubator/docker-locust/master/example/simple.py\u003e\n[awscli]: \u003chttp://docs.aws.amazon.com/cli/latest/userguide/installing.html\u003e\n[html-publisher-plugin]: \u003chttps://wiki.jenkins-ci.org/display/JENKINS/HTML+Publisher+Plugin\u003e\n[this example]: \u003chttps://github.com/zalando-incubator/docker-locust/blob/master/example/simple.py#L4-L9\u003e\n[Download report]: \u003cimages/download_report.png\u003e \"Download report\"\n[HTML-Publisher configuration]: \u003cimages/usage_html_publisher.png\u003e \"Example configuration of HTML Publisher in jenkins job\"\n[hello-world]: \u003chttps://github.com/zalando-incubator/docker-locust/blob/master/flask-sample/app.py\u003e\n[AWS-EC2-Type]: \u003chttps://aws.amazon.com/ec2/instance-types/\u003e\n[AWS-EC2-pricing]: \u003chttps://aws.amazon.com/ec2/pricing/on-demand/?nc1=h_ls\u003e\n[guidelines]: \u003cCONTRIBUTING.md\u003e\n[maintainers]: \u003cMAINTAINERS\u003e\n[License]: \u003cLICENSE.md\u003e\n[Security]: \u003cSECURITY.md\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzalando-incubator%2Fdocker-locust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzalando-incubator%2Fdocker-locust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzalando-incubator%2Fdocker-locust/lists"}