-------------------
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.7 <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
``MONGO_ORCHESTRATION_HOME`` environment variable, which informs the
server where to find the "configurations" directory for presets as well
as where to put the log and pid files.
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.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)
Raw data
{
"_id": null,
"home_page": "https://github.com/10gen/mongo-orchestration",
"name": "mongo-orchestration",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "mongo-orchestration,mongodb,mongo,rest,testing",
"author": "MongoDB, Inc.",
"author_email": "mongodb-user@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/80/bc/46ec328dcb9abcc8e9956c02378bfd4bfb053cb94fcf40b62b75f900d147/mongo-orchestration-0.8.0.tar.gz",
"platform": "any",
"description": "-------------------\nMongo Orchestration\n-------------------\n\nSee the `wiki <https://github.com/10gen/mongo-orchestration/wiki>`__\nfor documentation.\n\nMongo Orchestration is an HTTP server that provides a REST API for\ncreating and managing MongoDB configurations on a single host.\n\n**THIS PROJECT IS FOR TESTING OF MONGODB DRIVERS.**\n\nFeatures\n--------\n\n- Start and stop mongod servers, replica sets, and sharded clusters on the host running mongo-orchestration.\n- Add and remove replica set members.\n- Add and remove shards and mongos routers.\n- Reset replica sets and clusters to restart all members that were\n stopped.\n- Freeze secondary members of replica sets.\n- Retrieve information about MongoDB resources.\n- Interaction all through REST interface.\n- Launch simple local servers using ``mongo-launch`` CLI tool.\n\nRequires\n--------\n\n- `Python >=3.7 <http://www.python.org/download/>`__\n- `bottle>=0.12.7 <https://pypi.python.org/pypi/bottle>`__\n- `pymongo>=3.0.2,<4 <https://pypi.python.org/pypi/pymongo>`__\n- `cheroot>=5.11 <https://pypi.python.org/pypi/cheroot/>`__\n\nInstallation\n------------\n\nThe easiest way to install Mongo Orchestration is with `pip <https://pypi.python.org/pypi/pip>`__:\n\n::\n\n pip install mongo-orchestration\n\nYou can also install the development version of Mongo Orchestration\nmanually:\n\n::\n\n git clone https://github.com/10gen/mongo-orchestration.git\n cd mongo-orchestration\n pip install .\n\nCloning 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\nhave to run the above commands with ``sudo``, depending on where you're\ninstalling Mongo Orchestration and what privileges you have.\nInstallation will place a ``mongo-orchestration`` script on your path.\n\nUsage\n-----\n\n::\n\n mongo-orchestration [-h] [-f CONFIG] [-e ENV] [--no-fork] [-b BIND IP=\"localhost\"] [-p PORT]\n [-s {auto,cheroot,wsgiref}] [--socket-timeout-ms MILLIS]\n [--pidfile PIDFILE] [--enable-majority-read-concern] {start,stop,restart}\n\n\nArguments:\n\n- **-h** - show help\n- **-f, --config** - path to config file\n- **-e, --env** - default release to use, as specified in the config\n file\n- **--no-fork** - run server in foreground\n- **-b, --bind** - host on which Mongo Orchestration and subordinate mongo processes should listen for requests. Defaults to \"localhost\".\n- **-s, --server** - HTTP backend to use: one of `auto`, `cheroot`, or `wsgiref`. `auto`\n configures bottle to automatically choose an available backend.\n- **-p** - port number (8889 by default)\n- **--socket-timeout-ms** - socket timeout when connecting to MongoDB servers\n- **--pidfile** - location where mongo-orchestration should place its pid file\n- **--enable-majority-read-concern** - enable \"majority\" read concern on server versions that support it.\n- **start/stop/restart**: start, stop, or restart the server,\n respectively\n\nIn addition, Mongo Orchestration can be influenced by the\n``MONGO_ORCHESTRATION_HOME`` environment variable, which informs the\nserver where to find the \"configurations\" directory for presets as well\nas where to put the log and pid files.\n\nExamples\n~~~~~~~~\n\n``mongo-orchestration start``\n\nStarts Mongo Orchestration as service on port 8889.\n\n``mongo-orchestration stop``\n\nStop the server.\n\n``mongo-orchestration -f mongo-orchestration.config -e 30-release -p 8888 --no-fork start``\n\nStarts Mongo Orchestration on port 8888 using ``30-release`` defined in\n``mongo-orchestration.config``. Stops with *Ctrl+C*.\n\nIf you have installed mongo-orchestration but you're still getting\n``command not found: mongo-orchestration`` this means that the script was\ninstalled to a directory that is not on your ``PATH``. As an alternative use:\n\n``python -m mongo_orchestration.server start``\n\nConfiguration File\n~~~~~~~~~~~~~~~~~~\n\nMongo Orchestration may be given a JSON configuration file with the\n``--config`` option specifying where to find MongoDB binaries. See\n`mongo-orchestration.config <https://github.com/10gen/mongo-orchestration/blob/master/mongo-orchestration.config>`__\nfor an example. When no configuration file is provided, Mongo\nOrchestration uses whatever binaries are on the user's PATH.\n\nPredefined Configurations\n-------------------------\n\nMongo Orchestration has a set of predefined\n`configurations <https://github.com/10gen/mongo-orchestration/tree/master/mongo_orchestration/configurations>`__\nthat can be used to start, restart, or stop MongoDB processes. You can\nuse a tool like ``curl`` to send these files directly to the Mongo\nOrchestration server, or use the ``mo`` script in the ``scripts``\ndirectory (in the `repository <https://github.com/10gen/mongo-orchestration>`__ only). Some examples:\n\n- Start a single node without SSL or auth:\n\n ::\n\n mo configurations/servers/clean.json start\n\n- Get the status of a single node without SSL or auth:\n\n ::\n\n mo configurations/servers/clean.json status\n\n- Stop a single node without SSL or auth:\n\n ::\n\n mo configurations/servers/clean.json stop\n\n- Start a replica set with ssl and auth:\n\n ::\n\n mo configurations/replica_sets/ssl_auth.json start\n\n- Use ``curl`` to create a basic sharded cluster with the id\n \"myCluster\":\n\n ::\n\n curl -XPUT http://localhost:8889/v1/sharded_clusters/myCluster \\\n -d@configurations/sharded_clusters/basic.json\n\nNote that in order to run the ``mo`` script, you need to be in the same\ndirectory as \"configurations\".\n\n**Helpful hint**: You can prettify JSON responses from the server by\npiping the response into ``python -m json.tool``, e.g.:\n\n::\n\n $ curl http://localhost:8889/v1/servers/myServer | python -m json.tool\n\n {\n \"id\": \"myServer\",\n \"mongodb_uri\": \"mongodb://localhost:1025\",\n \"orchestration\": \"servers\",\n \"procInfo\": {\n \"alive\": true,\n \"name\": \"mongod\",\n \"optfile\": \"/var/folders/v9/spc2j6cx3db71l/T/mongo-KHUACD\",\n \"params\": {\n \"dbpath\": \"/var/folders/v9/spc2j6cx3db71l/T/mongo-vAgYaQ\",\n \"ipv6\": true,\n \"journal\": true,\n \"logappend\": true,\n \"oplogSize\": 100,\n \"port\": 1025\n },\n \"pid\": 51320\n },\n // etc.\n }\n\nMongo Launch\n------------\n\nThe ``mongo-launch`` CLI tool allows you to spin up servers locally\nwith minimal configuration.\n\n..\n\n mongo-launch --help\n Usage: launch.py [single|replica|shard] [ssl] [auth]\n\n..\n\n mongo-orchestration start\n mongo-launch replica ssl auth\n\nTests\n-----\n\nIn order to run the tests, you should first clone the `repository <https://github.com/10gen/mongo-orchestration>`__.\n\nRun all tests\n~~~~~~~~~~~~~\n\n``python -m unittest``\n\nRun a test module\n~~~~~~~~~~~~~~~~~\n\n``python -m unittest tests.test_servers``\n\nRun a single test case\n~~~~~~~~~~~~~~~~~~~~~~\n\n``python -m unittest tests.test_servers.ServerSSLTestCase``\n\nRun a single test method\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n``python -m unittest tests.test_servers.ServerSSLTestCase.test_ssl_auth``\n\nRun a single test example for debugging with verbose and immediate stdout output\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n``python -m unittest -v tests.test_servers.ServerSSLTestCase``\n\nChangelog\n---------\n\nChanges in Version 0.8.0 (2023-05-16)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Add ``mongo-launch`` CLI tool.\n- Upgrade to PyMongo 4.x and set up GitHub Actions testing.\n- Remove support for managing MongoDB 3.4 or earlier servers.\n- Remove support for Python 3.5 or earlier.\n- Replaced dependency on CherryPy with cheroot. `-s auto` is the new default\n and `-s cherrypy` is no longer supported.\n- Remove transactionLifetimeLimitSeconds default.\n\nChanges in Version 0.7.0 (2021-04-06)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Remove support for managing MongoDB 2.4 servers.\n- Add support for Python 3.8 and 3.9.\n- Add support for MongoDB 4.2 and 4.4.\n- Upgrade from pymongo 3.5.1 to 3.X latest. (#284).\n- Ensure createUser succeeds on all replica set members. (#282)\n- Create admin user with both SCRAM-SHA-256 and SCRAM-SHA-1. (#281)\n- Wait for mongo-orchestration server to fully terminate in \"stop\". (#276)\n- Allow starting clusters with enableTestCommands=0. (#269)\n- Decrease transactionLifetimeLimitSeconds on 4.2+ by default. (#267)\n- Increase maxTransactionLockRequestTimeoutMillis by default. (#270)\n- Reduce periodicNoopIntervalSecs for faster driver change stream testing. (#283)\n- Enable ztsd compression by default on 4.2+ (#263)\n\nChanges in Version 0.6.12 (2018-12-14)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Allow running the mongo-orchestration server over IPv6 localhost. (#237)\n- Increase default mongodb server logging verbosity. (#255)\n- Fixed a bug when shutting down clusters where mongo-orchestration would\n hang forever if the server had already exited. (#253)\n",
"bugtrack_url": null,
"license": "http://www.apache.org/licenses/LICENSE-2.0.html",
"summary": "Restful service for managing MongoDB servers",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/10gen/mongo-orchestration"
},
"split_keywords": [
"mongo-orchestration",
"mongodb",
"mongo",
"rest",
"testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "46e51b4f8523f517174b16c9adadf84cb4e3ac1fe93d31ef7771d2d994945d6f",
"md5": "08c7a54ce6530244071069f9819b10f1",
"sha256": "8c8fc3208fde6bbfc445477c572080aecd92cd3660461d2459b2d01e7541e67e"
},
"downloads": -1,
"filename": "mongo_orchestration-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08c7a54ce6530244071069f9819b10f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 74605,
"upload_time": "2023-05-18T15:37:51",
"upload_time_iso_8601": "2023-05-18T15:37:51.402274Z",
"url": "https://files.pythonhosted.org/packages/46/e5/1b4f8523f517174b16c9adadf84cb4e3ac1fe93d31ef7771d2d994945d6f/mongo_orchestration-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "80bc46ec328dcb9abcc8e9956c02378bfd4bfb053cb94fcf40b62b75f900d147",
"md5": "0d524aad69bd559f2c75c1060a67225e",
"sha256": "9cb17a4f1a19d578a04c34ef51f4d5bc2a1c768f4968948792f330644c9398f6"
},
"downloads": -1,
"filename": "mongo-orchestration-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "0d524aad69bd559f2c75c1060a67225e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 72465,
"upload_time": "2023-05-18T15:37:54",
"upload_time_iso_8601": "2023-05-18T15:37:54.942595Z",
"url": "https://files.pythonhosted.org/packages/80/bc/46ec328dcb9abcc8e9956c02378bfd4bfb053cb94fcf40b62b75f900d147/mongo-orchestration-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-18 15:37:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "10gen",
"github_project": "mongo-orchestration",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mongo-orchestration"
}