-------------------
Mongo Orchestration
-------------------

See the `wiki <https://github.com/10gen/mongo-orchestration/wiki>`__
for documentation.

Mongo Orchestration is an HTTP server that provides a REST API for
creating and managing MongoDB configurations on a single host.

**THIS PROJECT IS FOR TESTING OF MONGODB DRIVERS.**

Features
--------

-  Start and stop mongod servers, replica sets, and sharded clusters on the host running mongo-orchestration.
-  Add and remove replica set members.
-  Add and remove shards and mongos routers.
-  Reset replica sets and clusters to restart all members that were
   stopped.
-  Freeze secondary members of replica sets.
-  Retrieve information about MongoDB resources.
-  Interaction all through REST interface.
-  Launch simple local servers using ``mongo-launch`` CLI tool.

Requires
--------

-  `Python >=3.8 <http://www.python.org/download/>`__
-  `bottle>=0.12.7 <https://pypi.python.org/pypi/bottle>`__
-  `pymongo>=3.0.2,<4 <https://pypi.python.org/pypi/pymongo>`__
-  `cheroot>=5.11 <https://pypi.python.org/pypi/cheroot/>`__

Installation
------------

The easiest way to install Mongo Orchestration is with `pip <https://pypi.python.org/pypi/pip>`__:

::

    pip install mongo-orchestration

You can also install the development version of Mongo Orchestration
manually:

::

    git clone https://github.com/10gen/mongo-orchestration.git
    cd mongo-orchestration
    pip install .

Cloning the `repository <https://github.com/10gen/mongo-orchestration>`__ this way will also give you access to the tests for Mongo Orchestration as well as the ``mo`` script. Note that you may
have to run the above commands with ``sudo``, depending on where you're
installing Mongo Orchestration and what privileges you have.
Installation will place a ``mongo-orchestration`` script on your path.

Usage
-----

::

    mongo-orchestration [-h] [-f CONFIG] [-e ENV] [--no-fork] [-b BIND IP="localhost"] [-p PORT]
                        [-s {auto,cheroot,wsgiref}] [--socket-timeout-ms MILLIS]
                        [--pidfile PIDFILE] [--enable-majority-read-concern] {start,stop,restart}


Arguments:

-  **-h** - show help
-  **-f, --config** - path to config file
-  **-e, --env** - default release to use, as specified in the config
   file
-  **--no-fork** - run server in foreground
-  **-b, --bind** - host on which Mongo Orchestration and subordinate mongo processes should listen for requests. Defaults to "localhost".
-  **-s, --server** - HTTP backend to use: one of `auto`, `cheroot`, or `wsgiref`. `auto`
   configures bottle to automatically choose an available backend.
-  **-p** - port number (8889 by default)
-  **--socket-timeout-ms** - socket timeout when connecting to MongoDB servers
-  **--pidfile** - location where mongo-orchestration should place its pid file
-  **--enable-majority-read-concern** - enable "majority" read concern on server versions that support it.
-  **start/stop/restart**: start, stop, or restart the server,
   respectively

In addition, Mongo Orchestration can be influenced by the following environment variables:

- ``MONGO_ORCHESTRATION_HOME`` - informs the
  server where to find the "configurations" directory for presets as well
  as where to put the log and pid files.
- ``MONGO_ORCHESTRATION_TMP`` - the temporary folder root location.
- ``MO_HOST`` - the server host (``localhost`` by default)
- ``MO_PORT`` - the server port (8889 by default)
- ``MONGO_ORCHESTRATION_CLIENT_CERT`` -  set the client certificate file 
  to be used by ``mongo-orchestration``.

Examples
~~~~~~~~

``mongo-orchestration start``

Starts Mongo Orchestration as service on port 8889.

``mongo-orchestration stop``

Stop the server.

``mongo-orchestration -f mongo-orchestration.config -e 30-release -p 8888 --no-fork start``

Starts Mongo Orchestration on port 8888 using ``30-release`` defined in
``mongo-orchestration.config``. Stops with *Ctrl+C*.

If you have installed mongo-orchestration but you're still getting
``command not found: mongo-orchestration`` this means that the script was
installed to a directory that is not on your ``PATH``. As an alternative use:

``python -m mongo_orchestration.server start``

Configuration File
~~~~~~~~~~~~~~~~~~

Mongo Orchestration may be given a JSON configuration file with the
``--config`` option specifying where to find MongoDB binaries. See
`mongo-orchestration.config <https://github.com/10gen/mongo-orchestration/blob/master/mongo-orchestration.config>`__
for an example. When no configuration file is provided, Mongo
Orchestration uses whatever binaries are on the user's PATH.

Predefined Configurations
-------------------------

Mongo Orchestration has a set of predefined
`configurations <https://github.com/10gen/mongo-orchestration/tree/master/mongo_orchestration/configurations>`__
that can be used to start, restart, or stop MongoDB processes. You can
use a tool like ``curl`` to send these files directly to the Mongo
Orchestration server, or use the ``mo`` script in the ``scripts``
directory (in the `repository <https://github.com/10gen/mongo-orchestration>`__ only). Some examples:

-  Start a single node without SSL or auth:

   ::

       mo configurations/servers/clean.json start

-  Get the status of a single node without SSL or auth:

   ::

       mo configurations/servers/clean.json status

-  Stop a single node without SSL or auth:

   ::

       mo configurations/servers/clean.json stop

-  Start a replica set with ssl and auth:

   ::

       mo configurations/replica_sets/ssl_auth.json start

-  Use ``curl`` to create a basic sharded cluster with the id
   "myCluster":

   ::

       curl -XPUT http://localhost:8889/v1/sharded_clusters/myCluster \
                  -d@configurations/sharded_clusters/basic.json

Note that in order to run the ``mo`` script, you need to be in the same
directory as "configurations".

**Helpful hint**: You can prettify JSON responses from the server by
piping the response into ``python -m json.tool``, e.g.:

::

    $ curl http://localhost:8889/v1/servers/myServer | python -m json.tool

    {
        "id": "myServer",
        "mongodb_uri": "mongodb://localhost:1025",
        "orchestration": "servers",
        "procInfo": {
            "alive": true,
            "name": "mongod",
            "optfile": "/var/folders/v9/spc2j6cx3db71l/T/mongo-KHUACD",
            "params": {
                "dbpath": "/var/folders/v9/spc2j6cx3db71l/T/mongo-vAgYaQ",
                "ipv6": true,
                "journal": true,
                "logappend": true,
                "oplogSize": 100,
                "port": 1025
            },
            "pid": 51320
        },
        // etc.
    }

Mongo Launch
------------

The ``mongo-launch`` CLI tool allows you to spin up servers locally
with minimal configuration.

..

    mongo-launch --help
    Usage: launch.py [single|replica|shard] [ssl] [auth]

..

    mongo-orchestration start
    mongo-launch replica ssl auth

Tests
-----

In order to run the tests, you should first clone the `repository <https://github.com/10gen/mongo-orchestration>`__.

Run all tests
~~~~~~~~~~~~~

``python -m unittest``

Run a test module
~~~~~~~~~~~~~~~~~

``python -m unittest tests.test_servers``

Run a single test case
~~~~~~~~~~~~~~~~~~~~~~

``python -m unittest tests.test_servers.ServerSSLTestCase``

Run a single test method
~~~~~~~~~~~~~~~~~~~~~~~~

``python -m unittest tests.test_servers.ServerSSLTestCase.test_ssl_auth``

Run a single test example for debugging with verbose and immediate stdout output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``python -m unittest -v tests.test_servers.ServerSSLTestCase``

Changelog
---------

Changes in Version 0.11.0 (2024-12-30)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Allow server daemon to be run as a library in addition to as a cli.
- Add support for ``MONGO_ORCHESTRATION_CLIENT_CERT`` environment variable to set the client certificate file 
  to be used by ``mongo-orchestration``.

Changes in Version 0.10.0 (2024-11-21)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Add support for requireApiVersion for standalone clusters and replica sets.
- Drop support for Python 3.8 and add support for Python 3.13.

Changes in Version 0.9.0 (2043-09-04)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Fix handling of ``enableMajorityReadConcern``.
- Remove 'journal' options for newer mongod ``(>=6.1)``.
- Switch to Hatch build backend.

Changes in Version 0.8.0 (2023-05-16)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Add ``mongo-launch`` CLI tool.
- Upgrade to PyMongo 4.x and set up GitHub Actions testing.
- Remove support for managing MongoDB 3.4 or earlier servers.
- Remove support for Python 3.5 or earlier.
- Replaced dependency on CherryPy with cheroot. `-s auto` is the new default
  and `-s cherrypy` is no longer supported.
- Remove transactionLifetimeLimitSeconds default.

Changes in Version 0.7.0 (2021-04-06)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Remove support for managing MongoDB 2.4 servers.
- Add support for Python 3.8 and 3.9.
- Add support for MongoDB 4.2 and 4.4.
- Upgrade from pymongo 3.5.1 to 3.X latest. (#284).
- Ensure createUser succeeds on all replica set members. (#282)
- Create admin user with both SCRAM-SHA-256 and SCRAM-SHA-1. (#281)
- Wait for mongo-orchestration server to fully terminate in "stop". (#276)
- Allow starting clusters with enableTestCommands=0. (#269)
- Decrease transactionLifetimeLimitSeconds on 4.2+ by default. (#267)
- Increase maxTransactionLockRequestTimeoutMillis by default. (#270)
- Reduce periodicNoopIntervalSecs for faster driver change stream testing. (#283)
- Enable ztsd compression by default on 4.2+ (#263)

Changes in Version 0.6.12 (2018-12-14)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Allow running the mongo-orchestration server over IPv6 localhost. (#237)
- Increase default mongodb server logging verbosity. (#255)
- Fixed a bug when shutting down clusters where mongo-orchestration would
  hang forever if the server had already exited. (#253)
