<div align="center">
<img height="250px" src="https://github.com/yuviherziger/tomodo/raw/main/tomodo-nopg.png" alt="tomodo logo"></img>
[](https://codecov.io/gh/yuviherziger/tomodo)
</div>
# tomodo
**tomodo** is a Toolbox for MongoDB on Docker.
-------
Use it to create and manage Docker-based MongoDB community deployments - standalone instances, replica sets, sharded clusters, and local Atlas deployments.
* [Installation](#installation)
+ [Install with Homebrew](#install-with-homebrew)
+ [Install with pip](#install-with-pip)
+ [Install from Source](#install-from-source)
- [Install with Poetry Package Manager for Python](#install-with-poetry-package-manager-for-python)
- [Install from source with pip](#install-from-source-with-pip)
* [CLI Usage](#cli-usage)
+ [Create a Deployment](#create-a-deployment)
+ [Describe Deployments](#describe-deployments)
+ [List Deployments](#list-deployments)
+ [Stop Deployments](#stop-deployments)
+ [Start Deployments](#start-deployments)
+ [Remove Deployments](#remove-deployments)
+ [List Image Tags](#list-tags)
* [Programmatic Usage](#programmatic-usage)
* [Disclaimer](#disclaimer)
---
## Installation
### Install with Homebrew
[Homebrew](https://brew.sh/) is a popular package manager for macOS. You can install tomodo by
running the following commands:
```shell
brew tap yuviherziger/homebrew-tomodo
brew install tomodo
```
After installing the tool with `brew`, you can run it the following way:
```bash
tomodo --help
```
### Install with pip
To install with `pip`, run the following command:
```shell
pip install tomodo
```
### Install from Source
If you wish to set up a development environment, or if you simply can't use Homebrew or aren't a macOS user,
you can install tomodo using Python. The recommended way to perform the Python installation is by using the
[Poetry](https://python-poetry.org/) Python package manager.
**Requirements:**
* Python 3.8 or higher
#### Install with Poetry Package Manager for Python
If you have the [Poetry](https://python-poetry.org/) Python package manager installed locally, you can install
the CLI the following way:
```bash
git clone https://github.com/yuviherziger/tomodo.git
cd tomodo
poetry shell
poetry install
```
After installing the tool with Poetry, you can run it the following way:
```bash
tomodo --help
```
#### Install from source with pip
You can install the dependencies with pip using the following command:
```bash
git clone https://github.com/yuviherziger/tomodo.git
cd tomodo
pip install .
```
After installing the dependencies with pip, you can validate the installation by invoking the help page:
```bash
python tomodo/cmd.py --help
```
## CLI Usage
Before you begin, make sure you have a Docker daemon running. The most popular platform
is [Docker Desktop](https://www.docker.com/products/docker-desktop/).
### Create a Deployment
Create a deployment with the `provision` command. For example, here's how you create a standalone
instance with zero configuration:
```shell
tomodo provision standalone
```
To create a replica set with zero configuration, run the following command:
```shell
tomodo provision replica-set
```
To create a sharded cluster with zero configuration, run the following command:
```shell
tomodo provision sharded
```
To create a local Atlas deployment (a single-node replica set) with zero configuration, run the following command:
```shell
tomodo provision atlas
```
Take a look at each `provision` command's help page to read the full set of options
with `tomodo provision --help`.
```
Usage: tomodo provision [OPTIONS] COMMAND [ARGS]...
Provision a MongoDB deployment
╭─ Options ──────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────╮
│ atlas Provision a local MongoDB Atlas deployment │
│ replica-set Provision a MongoDB replica set deployment │
│ sharded Provision a MongoDB sharded cluster │
│ standalone Provision a standalone MongoDB deployment │
╰────────────────────────────────────────────────────────────────────────╯
```
### Describe Deployments
Use the `describe` command to print the details of one or all deployments:
```shell
# Describe all deployments
tomodo describe
# Describe a deployment by name
tomodo describe --name yawning-mole
# Describe only running deployments
tomodo describe --exclude-stopped
```
### List Deployments
Use the `list` command to list your deployments:
```shell
# List all deployments
tomodo list
# List only running deployments
tomodo list --exclude-stopped
```
### Stop Deployments
Use the `stop` command to stop your deployments:
```shell
# Stop all deployments
tomodo stop
# Stop a deployment by name
tomodo stop --name troubled-narwhal
# Stop all deployments without prompting for confirmation
tomodo stop --auto-approve
```
### Start Deployments
Use the `start` command to start a deployment you previously stopped:
```shell
tomodo start --name printed-lemming
```
### Remove Deployments
Use the `remove` command to permanently remove deployments:
```shell
# Remove all deployments
tomodo remove
# Remove a deployment by name
tomodo remove --name troubled-narwhal
# Remove all deployments without prompting for confirmation
tomodo remove --auto-approve
```
### List Tags
Use the `tags list` command to list the available image tags on Docker Hub.
```shell
tomodo tags list --version 7
```
Sample output:
```
7.0.6
7.0.6-jammy
7.0.6-nanoserver
7.0.6-nanoserver-1809
7.0.6-nanoserver-ltsc2022
7.0.6-windowsservercore
7.0.6-windowsservercore-1809
7.0.6-windowsservercore-ltsc2022
7.0.5
7.0.5-jammy
7.0.5-nanoserver
7.0.5-nanoserver-1809
7.0.5-nanoserver-ltsc2022
7.0.5-windowsservercore
7.0.5-windowsservercore-1809
7.0.5-windowsservercore-ltsc2022
7.0.4
7.0.4-jammy
7.0.4-nanoserver
7.0.4-nanoserver-1809
7.0.4-nanoserver-ltsc2022
7.0.4-windowsservercore
7.0.4-windowsservercore-1809
7.0.4-windowsservercore-ltsc2022
7.0.3
7.0.3-jammy
7.0.3-nanoserver
7.0.3-nanoserver-1809
7.0.3-nanoserver-ltsc2022
7.0.3-windowsservercore
7.0.3-windowsservercore-1809
7.0.3-windowsservercore-ltsc2022
7.0.2
7.0.2-jammy
7.0.2-nanoserver
7.0.2-nanoserver-1809
7.0.2-nanoserver-ltsc2022
7.0.2-windowsservercore
7.0.2-windowsservercore-1809
7.0.2-windowsservercore-ltsc2022
```
## Programmatic Usage
You can install tomodo in your Python (>=3.8) projects using `pip` or any other Python package manager, and use it
programmatically (you'll still need a Docker daemon running).
```python
from typing import Dict
from tomodo import functional as tfunc
from tomodo.common.errors import DeploymentNotFound
from tomodo.common.models import AtlasDeployment, Deployment, Mongod, ReplicaSet, ShardedCluster
# Create a standalone instance:
mongod: Mongod = tfunc.provision_standalone_instance(port=1000)
# Create an Atlas instance:
atlas_depl: AtlasDeployment = tfunc.provision_atlas_instance(port=2000)
# Create a replica set:
replica_set: ReplicaSet = tfunc.provision_replica_set(port=3000, replicas=3)
# Create a sharded cluster:
sh_cluster: ShardedCluster = tfunc.provision_sharded_cluster(port=4000, shards=2, config_servers=3, mongos=2)
# Stop a deployment:
mongod.stop()
# Start a stopped deployment:
mongod.start()
# Remove a deployment permanently:
mongod.remove()
# Find a deployment by name
try:
deployment = tfunc.get_deployment(name="elegant-leopard", include_stopped=True)
except DeploymentNotFound:
print("Deployment not found")
# List all deployments:
deployments: Dict = tfunc.list_deployments(include_stopped=True)
for name in deployments.keys():
deployment: Deployment = deployments[name]
print(f"Deployment {name} is {deployment.last_known_state}")
```
## Disclaimer
This software is not supported by MongoDB, Inc. under any of their commercial support subscriptions or otherwise.
Any usage of tomodo is at your own risk. Bug reports, feature requests, and questions can be posted in the
[Issues section](https://github.com/yuviherziger/tomodo/issues) of this repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/yuviherziger/tomodo",
"name": "tomodo",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.8",
"maintainer_email": null,
"keywords": "mongodb, docker, upgrade, python, cli",
"author": "MongoDB PS",
"author_email": "yuvi.herziger@mongodb.com",
"download_url": "https://files.pythonhosted.org/packages/a5/20/1c85016517267b7069ea04735d64ab8f9001a8a92b9f96ebe83b59220694/tomodo-1.1.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img height=\"250px\" src=\"https://github.com/yuviherziger/tomodo/raw/main/tomodo-nopg.png\" alt=\"tomodo logo\"></img>\n\n\n\n[](https://codecov.io/gh/yuviherziger/tomodo)\n\n\n\n</div>\n\n# tomodo\n\n**tomodo** is a Toolbox for MongoDB on Docker.\n\n-------\n\nUse it to create and manage Docker-based MongoDB community deployments - standalone instances, replica sets, sharded clusters, and local Atlas deployments.\n\n* [Installation](#installation)\n + [Install with Homebrew](#install-with-homebrew)\n + [Install with pip](#install-with-pip)\n + [Install from Source](#install-from-source)\n - [Install with Poetry Package Manager for Python](#install-with-poetry-package-manager-for-python)\n - [Install from source with pip](#install-from-source-with-pip)\n* [CLI Usage](#cli-usage)\n + [Create a Deployment](#create-a-deployment)\n + [Describe Deployments](#describe-deployments)\n + [List Deployments](#list-deployments)\n + [Stop Deployments](#stop-deployments)\n + [Start Deployments](#start-deployments)\n + [Remove Deployments](#remove-deployments)\n + [List Image Tags](#list-tags)\n* [Programmatic Usage](#programmatic-usage)\n* [Disclaimer](#disclaimer)\n\n--- \n\n## Installation\n\n### Install with Homebrew\n\n[Homebrew](https://brew.sh/) is a popular package manager for macOS. You can install tomodo by\nrunning the following commands:\n\n```shell\nbrew tap yuviherziger/homebrew-tomodo\nbrew install tomodo\n```\n\nAfter installing the tool with `brew`, you can run it the following way:\n\n```bash\ntomodo --help\n```\n\n### Install with pip\n\nTo install with `pip`, run the following command:\n\n```shell\npip install tomodo\n```\n\n### Install from Source\n\nIf you wish to set up a development environment, or if you simply can't use Homebrew or aren't a macOS user,\nyou can install tomodo using Python. The recommended way to perform the Python installation is by using the\n[Poetry](https://python-poetry.org/) Python package manager.\n\n**Requirements:**\n\n* Python 3.8 or higher\n\n#### Install with Poetry Package Manager for Python\n\nIf you have the [Poetry](https://python-poetry.org/) Python package manager installed locally, you can install\nthe CLI the following way:\n\n```bash\ngit clone https://github.com/yuviherziger/tomodo.git\ncd tomodo\npoetry shell\npoetry install\n```\n\nAfter installing the tool with Poetry, you can run it the following way:\n\n```bash\ntomodo --help\n```\n\n#### Install from source with pip\n\nYou can install the dependencies with pip using the following command:\n\n```bash\ngit clone https://github.com/yuviherziger/tomodo.git\ncd tomodo\npip install .\n```\n\nAfter installing the dependencies with pip, you can validate the installation by invoking the help page:\n\n```bash\npython tomodo/cmd.py --help\n```\n\n## CLI Usage\n\nBefore you begin, make sure you have a Docker daemon running. The most popular platform\nis [Docker Desktop](https://www.docker.com/products/docker-desktop/).\n\n### Create a Deployment\n\nCreate a deployment with the `provision` command. For example, here's how you create a standalone\ninstance with zero configuration:\n\n```shell\ntomodo provision standalone\n```\n\nTo create a replica set with zero configuration, run the following command:\n\n```shell\ntomodo provision replica-set\n```\n\nTo create a sharded cluster with zero configuration, run the following command:\n\n```shell\ntomodo provision sharded\n```\n\nTo create a local Atlas deployment (a single-node replica set) with zero configuration, run the following command:\n\n```shell\ntomodo provision atlas\n```\n\nTake a look at each `provision` command's help page to read the full set of options\nwith `tomodo provision --help`.\n\n```\n Usage: tomodo provision [OPTIONS] COMMAND [ARGS]...\n\n Provision a MongoDB deployment\n\n\u256d\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 --help Show this message and exit. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u256d\u2500 Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 atlas Provision a local MongoDB Atlas deployment \u2502\n\u2502 replica-set Provision a MongoDB replica set deployment \u2502\n\u2502 sharded Provision a MongoDB sharded cluster \u2502\n\u2502 standalone Provision a standalone MongoDB deployment \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n### Describe Deployments\n\nUse the `describe` command to print the details of one or all deployments:\n\n```shell\n# Describe all deployments\ntomodo describe\n\n# Describe a deployment by name\ntomodo describe --name yawning-mole\n\n# Describe only running deployments\ntomodo describe --exclude-stopped\n```\n\n### List Deployments\n\nUse the `list` command to list your deployments:\n\n```shell\n# List all deployments\ntomodo list\n\n# List only running deployments\ntomodo list --exclude-stopped\n```\n\n### Stop Deployments\n\nUse the `stop` command to stop your deployments:\n\n```shell\n# Stop all deployments\ntomodo stop\n\n# Stop a deployment by name\ntomodo stop --name troubled-narwhal\n\n# Stop all deployments without prompting for confirmation\ntomodo stop --auto-approve\n```\n\n### Start Deployments\n\nUse the `start` command to start a deployment you previously stopped:\n\n```shell\ntomodo start --name printed-lemming\n```\n\n### Remove Deployments\n\nUse the `remove` command to permanently remove deployments:\n\n```shell\n# Remove all deployments\ntomodo remove\n\n# Remove a deployment by name\ntomodo remove --name troubled-narwhal\n\n# Remove all deployments without prompting for confirmation\ntomodo remove --auto-approve\n```\n\n### List Tags\n\nUse the `tags list` command to list the available image tags on Docker Hub.\n\n```shell\ntomodo tags list --version 7\n```\n\nSample output:\n\n```\n7.0.6\n7.0.6-jammy\n7.0.6-nanoserver\n7.0.6-nanoserver-1809\n7.0.6-nanoserver-ltsc2022\n7.0.6-windowsservercore\n7.0.6-windowsservercore-1809\n7.0.6-windowsservercore-ltsc2022\n7.0.5\n7.0.5-jammy\n7.0.5-nanoserver\n7.0.5-nanoserver-1809\n7.0.5-nanoserver-ltsc2022\n7.0.5-windowsservercore\n7.0.5-windowsservercore-1809\n7.0.5-windowsservercore-ltsc2022\n7.0.4\n7.0.4-jammy\n7.0.4-nanoserver\n7.0.4-nanoserver-1809\n7.0.4-nanoserver-ltsc2022\n7.0.4-windowsservercore\n7.0.4-windowsservercore-1809\n7.0.4-windowsservercore-ltsc2022\n7.0.3\n7.0.3-jammy\n7.0.3-nanoserver\n7.0.3-nanoserver-1809\n7.0.3-nanoserver-ltsc2022\n7.0.3-windowsservercore\n7.0.3-windowsservercore-1809\n7.0.3-windowsservercore-ltsc2022\n7.0.2\n7.0.2-jammy\n7.0.2-nanoserver\n7.0.2-nanoserver-1809\n7.0.2-nanoserver-ltsc2022\n7.0.2-windowsservercore\n7.0.2-windowsservercore-1809\n7.0.2-windowsservercore-ltsc2022\n```\n\n## Programmatic Usage\n\nYou can install tomodo in your Python (>=3.8) projects using `pip` or any other Python package manager, and use it\nprogrammatically (you'll still need a Docker daemon running).\n\n```python\nfrom typing import Dict\n\nfrom tomodo import functional as tfunc\nfrom tomodo.common.errors import DeploymentNotFound\nfrom tomodo.common.models import AtlasDeployment, Deployment, Mongod, ReplicaSet, ShardedCluster\n\n# Create a standalone instance:\nmongod: Mongod = tfunc.provision_standalone_instance(port=1000)\n\n# Create an Atlas instance:\natlas_depl: AtlasDeployment = tfunc.provision_atlas_instance(port=2000)\n\n# Create a replica set:\nreplica_set: ReplicaSet = tfunc.provision_replica_set(port=3000, replicas=3)\n\n# Create a sharded cluster:\nsh_cluster: ShardedCluster = tfunc.provision_sharded_cluster(port=4000, shards=2, config_servers=3, mongos=2)\n\n# Stop a deployment:\nmongod.stop()\n\n# Start a stopped deployment:\nmongod.start()\n\n# Remove a deployment permanently:\nmongod.remove()\n\n# Find a deployment by name\ntry:\n deployment = tfunc.get_deployment(name=\"elegant-leopard\", include_stopped=True)\nexcept DeploymentNotFound:\n print(\"Deployment not found\")\n\n# List all deployments:\ndeployments: Dict = tfunc.list_deployments(include_stopped=True)\nfor name in deployments.keys():\n deployment: Deployment = deployments[name]\n print(f\"Deployment {name} is {deployment.last_known_state}\")\n```\n\n## Disclaimer\nThis software is not supported by MongoDB, Inc. under any of their commercial support subscriptions or otherwise.\nAny usage of tomodo is at your own risk. Bug reports, feature requests, and questions can be posted in the\n[Issues section](https://github.com/yuviherziger/tomodo/issues) of this repository.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI for managing MongoDB deployments on Docker",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/yuviherziger/tomodo",
"Repository": "https://github.com/yuviherziger/tomodo"
},
"split_keywords": [
"mongodb",
" docker",
" upgrade",
" python",
" cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf8d94f7af3eeb9b58b5445257727bc22ddb07ffe8418bc058afff25a27ee398",
"md5": "c64f357cce84dd425308b09060f8a701",
"sha256": "2df1fda3ca7764e6a62676f8f8da834de67eace5299f720ef9a364169a2edb28"
},
"downloads": -1,
"filename": "tomodo-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c64f357cce84dd425308b09060f8a701",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.8",
"size": 29068,
"upload_time": "2024-05-03T08:40:41",
"upload_time_iso_8601": "2024-05-03T08:40:41.546447Z",
"url": "https://files.pythonhosted.org/packages/bf/8d/94f7af3eeb9b58b5445257727bc22ddb07ffe8418bc058afff25a27ee398/tomodo-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a5201c85016517267b7069ea04735d64ab8f9001a8a92b9f96ebe83b59220694",
"md5": "9950d7835686dcc5b4c966b56a2801c0",
"sha256": "34e77475686665f242d098a27bbe4bd3700c81b7080bae5496f5aaa4c2dc4c66"
},
"downloads": -1,
"filename": "tomodo-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "9950d7835686dcc5b4c966b56a2801c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.8",
"size": 25564,
"upload_time": "2024-05-03T08:40:43",
"upload_time_iso_8601": "2024-05-03T08:40:43.155582Z",
"url": "https://files.pythonhosted.org/packages/a5/20/1c85016517267b7069ea04735d64ab8f9001a8a92b9f96ebe83b59220694/tomodo-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 08:40:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yuviherziger",
"github_project": "tomodo",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "tomodo"
}
JSON
