Deploy and manage containers (including Docker) on top of Apache Mesos at scale.
Branch: master
Clone or download
jeschkies Speed up `v2/pods/::status` (#6786)
This replace the Akka stream with a simple `Future.sequence` and uses
the same `AppInfoBaseData` instance for each pod. This we utilize the
cached instances and not limit ourselves to eight parallel threads. To
not overload Marathon we use the fixed size thread pool from #5973.

However, even with #5973 we might allocate a lot of futures and

For 100 pods with 1 instance each I got the following:

## Master
› wrk -c 10 -t 10 -d 2m http://localhost:8080/v2/pods/::status
Running 2m test @ http://localhost:8080/v2/pods/::status
  10 threads and 10 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   136.52ms   44.93ms 859.05ms   93.64%
    Req/Sec     7.71      2.49    20.00     69.81%
  8918 requests in 2.00m, 1.34GB read
Requests/sec:     74.26
Transfer/sec:     11.45MB

## This change
Running 2m test @ http://localhost:8080/v2/pods/::status
  10 threads and 10 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    62.27ms   23.24ms 220.39ms   70.17%
    Req/Sec    15.94      6.09    50.00     69.12%
  19345 requests in 2.00m, 2.91GB read
Requests/sec:    161.10
Transfer/sec:     24.85MB 

JIRA issues: MARATHON-8563
Latest commit 855ed9e Feb 12, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create pull request template. (#5527) Sep 27, 2017
ami Update Ammonite in AMI `JenkinsMarathonCI-Debian9-2018-12-17`. (#6734) Dec 17, 2018
benchmark Introduce experimental `TemplateRepository` (#6512) Dec 7, 2018
ci forward porting linux packaging updates to fix native pkgs (#6777) Jan 30, 2019
dcos default value of root for --mesos_user in Marathon Universe template (#… Nov 29, 2018
docs Add tests on reset delay endpoint and cleanup backoff delay logic (#6700 Jan 10, 2019
mesos-client Apply Scalariform rule to test code and other projects (#6191) May 7, 2018
mesos-simulation Move integration tests to its own project (#6239) May 23, 2018
plugin-interface/src/main/scala/mesosphere/marathon/plugin Introduced a Sclariform rule for multi-import formatting (#6189) May 7, 2018
project Respond back with Mesos Source field exactly as we've received it (#6749 Dec 21, 2018
src Speed up `v2/pods/::status` (#6786) Feb 12, 2019
tests Fix racy deployment rollback (#6769) Jan 19, 2019
tools Always put a newline after the config file Jan 30, 2019
type-generator Use template engine to render RAML types. (#6781) Feb 6, 2019
.dockerignore dockerignore: Ignore more Jul 20, 2015
.gitattributes Enable merge union strategy for (#6590) Oct 3, 2018
.gitignore Build MoM to Soak without release to public universe (#6538) Sep 21, 2018
.sbtopts Enable Marathon to start on Java 9+ (#6688) Nov 29, 2018
.travis.yml Update scala version in travis configuration (#5575) Oct 9, 2017 Add issue template pointing people towards JIRA (#5516) Sep 28, 2017
Jenkinsfile Introduce type generator testing. (#6742) Dec 19, 2018 Fixing SI issues for running DCOS 1.10 cluster with new CLI Jul 31, 2017 Re-introduce Jenkins `timeout` for SI tests (#6714) Dec 7, 2018
Jenkinsfile.perf Revert "DCOS-48057 - Disable Jenkins build that runs on Hamburg Macbo… Feb 11, 2019 Re-introduce Jenkins `timeout` for SI tests (#6714) Dec 7, 2018 Re-introduce Jenkins `timeout` for SI tests (#6714) Dec 7, 2018
Jenkinsfile.release Update Ammonite in AMI `JenkinsMarathonCI-Debian9-2018-12-17`. (#6734) Dec 17, 2018 Re-introduce Jenkins `timeout` for SI tests (#6714) Dec 7, 2018
LICENSE License update Sep 3, 2013 add Toss to list of companies using Marathon (#6575) Sep 27, 2018
build.sbt Fix compiler warnings (#6764) Jan 9, 2019 Remove unreachable strategy from state instance. (#6675) Dec 7, 2018 Metrics overhaul (#6279) Aug 6, 2018
version Start development on 1.8. (#6579) Oct 2, 2018

Marathon Build Status Issues

Marathon is a production-proven Apache Mesos framework for container orchestration. DC/OS is the easiest way to start using Marathon. Issues are tracked in JIRA.

Marathon provides a REST API for starting, stopping, and scaling applications. Marathon is written in Scala and can run in highly-available mode by running multiple copies. The state of running tasks gets stored in the Mesos state abstraction.

Marathon is also used as a meta framework: you can start other Mesos frameworks such as Chronos or Storm with it to ensure they survive machine failures. It can launch anything that can be launched in a standard shell. In fact, you can even start other Marathon instances via Marathon.


  • HA - run any number of Marathon schedulers, but only one gets elected as leader; if you access a non-leader, your request gets proxied to the current leader
  • Constraints - e.g., only one instance of an application per rack, node, etc.
  • Service Discovery & Load Balancing via HAProxy or the events API (see below).
  • Health Checks: check your application's health via HTTP or TCP checks.
  • Event Subscription lets you supply an HTTP endpoint to receive notifications, for example to integrate with an external load balancer.
  • Marathon UI
  • JSON/REST API for easy integration and scriptability
  • Basic Auth and SSL
  • Metrics: query them at /metrics in JSON format, push them to systems like Graphite, StatsD and DataDog, or scrape them using Prometheus.


Marathon documentation is available on the Marathon GitHub pages site.

Documentation for installing and configuring the full Mesosphere stack including Mesos and Marathon is available on the Mesosphere website.

Issue Tracking

Marathon uses JIRA to track issues. You can browse existing issues or file a new issue with your GitHub account.

Note for users of GitHub issues: All existing issues have been migrated and closed, and a reference to the related JIRA has been added as a comment. We leave the GitHub issues available for reference. Going forward please use JIRA always.


We heartily welcome external contributions to Marathon's documentation. Documentation should be committed to the master branch and published to our GitHub pages site using the instructions in docs/

Setting Up And Running Marathon


Marathon has the following compile-time dependencies:

  • sbt - A build tool for scala. You can find the instructions for installing sbt for Mac OS X and Linux over here.
  • JDK 1.8+

For run-time, Marathon has the following dependencies:

  • libmesos - JNI bindings for talking to Apache Mesos master. Look at the Install Mesos section for instructions to get libmesos.
  • Apache Zookeeper - You can have a separate Zookeeper installation specifically for Marathon, or you can use the same Zookeeper used by Mesos.


Getting started with DC/OS

The by far easiest way to get Marathon running is to use DC/OS. Marathon is pre-bundled into DC/OS.

Install Mesos

Marathon requires libmesos, a shared object library, that contains JNI bindings for Marathon to talk to the Mesos master. libmesos comes as part of the Apache Mesos installation. There are three options for installing Apache Mesos.

Installing Mesos from prepackaged releases

Instructions on how to install prepackaged releases of Mesos are available in the Marathon docs.

Building Mesos from source

NOTE: Choose this option only if building Marathon from source, else there might be version incompatibility between pre-packaged releases of Marathon and Mesos built from source.

You can find the instructions for compiling Mesos from source in the Apache Mesos getting started docs. If you want Mesos to install libraries and executables in a non-default location use the --prefix option during configuration as follows:

./configure --prefix=<path to Mesos installation>

The make install will install libmesos ( on Linux and libmesos.dylib on Mac OS X) in the install directory.

Using the Mesos Version Manager

NOTE: Choose this option only if building Marathon from source, else there might be version incompatibility between pre-packaged releases of Marathon and Mesos built from source.

The Mesos Version Manager (mvm) compiles, configures, and manages multiple versions of Apache Mesos. It allows switching between versions quickly, making it easy to test Marathon against different versions of Mesos.


The Mesos Version Manager assumes that all dependencies of Apache Mesos are readily installed.
Please refer to the Apache Mesos getting started docs for instructions on how to set up the build environment.

MVM compiles Mesos with SSL support by default, which requires openssl and libevent to be installed.
On macOS, the packages can be installed using brew: brew install openssl libevent
On CentOS, the packages can be installed using yum: sudo yum install -y libevent-devel openssl-devel


The script can be run as follows:

    cd marathon
    cd tools
    ./ <VERSION> [SHELL]

The following command will launch a bash shell configured for Mesos 1.2.0: ./ 1.2.0 bash

You should consider placing the script into a folder in your shell's PATH if you are using it regularly.

The mvm script accepts three different formats as version name:

  1. Version tags from the Mesos repository. Use ./ --tags in order to obtain a list of available tags.
  2. Commit hashes from the Mesos repository.
  3. The --latest flag, which automatically chooses the latest development version: ./ --latest.

MVM Will automatically download & compile Apache Mesos if necessary. It will then spawn a new bash shell with the chosen version of Mesos activated.
For more information see ./ --help.

Note: You will have to re-run the script if you wish to use Mesos after closing the shell. See ./ --help information on how to permanently configure your shell for mvm to avoid this.

Install Marathon

Instructions on how to install prepackaged releases are available in the Marathon docs. Alternatively, you can build Marathon from source.

Building from Source
  1. To build Marathon from source, check out this repo and use sbt to build a universal:

    git clone
    cd marathon
    sbt 'run --master localhost:5050 --zk zk://localhost:2181/marathon'


    1. Failure in retrieval of IP address of the local machine will result in an error and may look like this:

      Failed to obtain the IP address for '<local-machine>'; the DNS service may not be able to resolve it: nodename nor servname provided, or not known

      Make sure that LIBPROCESS_IP environment variable is set.

      export LIBPROCESS_IP=""
    2. When the MESOS_NATIVE_JAVA_LIBRARY environment variable is not set, the following error may occur,

      java.lang.UnsatisfiedLinkError: no mesos in java.library.path...

      Make sure that MESOS_NATIVE_JAVA_LIBRARY environment variable is set.

      export MESOS_NATIVE_JAVA_LIBRARY="/path/to/mesos/lib/libmesos.dylib"
  2. Run sbt universal:packageZipTarball to package Marathon as an txz file containing bin/marathon fully packaged.

  3. Run sbt docker:publishLocal for a local marathon docker image.

Running in Development Mode

Mesos local mode allows you to run Marathon without launching a full Mesos cluster. It is meant for experimentation and not recommended for production use. Note that you still need to run ZooKeeper for storing state. The following command launches Marathon on Mesos in local mode. Point your web browser to http://localhost:8080 to see the Marathon UI.

    sbt 'run --master localhost:5050 --zk zk://localhost:2181/marathon'

For more information on how to run Marathon in production and configuration options, see the Marathon docs.

Developing Marathon

See the documentation on how to run Marathon locally inside a virtual machine.

Running in Development Mode on Docker

  • Note: Currently the Docker container fails due to strange behavior from the latest Mesos version. There will be an error about work_dir that is still unresolved, much like this:

      Failed to start a local cluster while loading agent flags from the environment: Flag 'work_dir' is required, but it was not provided

Build it:

sbt docker:publishLocal

Note the version, e.g: [info] Built image mesosphere/marathon:1.5.0-SNAPSHOT-461-gf1cc63e => 1.5.0-SNAPSHOT-461-gf1cc63e

A running zookeeper instance is required, if there isn't one already available, there is a docker image available for this:

docker run --name some-zookeeper --restart always -d zookeeper

Run it with zookeeper container:

docker run --link some-zookeeper:zookeeper marathon-head --master local --zk zk://zookeeper:2181/marathon

Or run it without zookeeper container:

docker run marathon:{version} --master local --zk zk://localhost:2181/marathon

If you want to inspect the contents of the Docker container:

docker run -it --entrypoint=/bin/bash marathon:{version} -s


The tests and integration tests a run with:

sbt test integration/test

You have to set the Mesos test IP and disable Docker tests on Mac:

sbt test integration/test

The Docker integration tests are not supported on Mac. The tests start and stop local Mesos clusters and Marathon instances. Sometimes processes leak after failed test runs. You can check them with ps aux | grep "python|java|mesos" and kill all processes and Mesos and Marathon instances unless they do not belong to a production environment of course.

Also see the CI instructions on running specfic build pipeline targets.

Marathon UI

To develop on the web UI look into the instructions of the Marathon UI repository.

Marathon Clients

Companies using Marathon

Across all installations Marathon is managing applications on more than 100,000 nodes world-wide. These are some of the companies using it:

Not in the list? Open a pull request and add yourself!


Have you found an issue? Feel free to report it using our JIRA Issues page. In order to speed up response times, we ask you to provide as much information on how to reproduce the problem as possible. If the issue is related in any way to the web UI, we kindly ask you to use the gui label.

If you have questions, please post on the Marathon Framework email list.

You can find Marathon support in the #marathon channel, and Mesos support in the #mesos channel, on freenode (IRC). Alternatively, check out the same channels on the Mesos Slack (request an invitation here).

The team at Mesosphere is also happy to answer any questions.

If you'd like to take part in design research and test new features in Marathon before they're released, please add your name to our UX Research list.


Marathon was created by Tobias Knaup and Florian Leibert and continues to be developed by the team at Mesosphere and by many contributors from the community.


YourKit, LLC

YourKit, LLC

YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.