A CLI tool to control MongoDB deployments on Docker
Project description
tomodo
tomodo is a Toolbox for MongoDB on Docker.
Use it to create and manage Docker-based MongoDB community deployments - standalone instances, replica sets, and sharded clusters.
Installation
Install with Homebrew
Homebrew is a popular package manager for macOS. You can install tomodo by running the following commands:
brew tap yuviherziger/homebrew-tomodo
brew install tomodo
After installing the tool with brew, you can run it the following way:
tomodo --help
Install with pip
To install with pip, run the following command:
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 Python package manager.
Requirements:
- Python 3.8 or higher
Install with Poetry Package Manager for Python
If you have the Poetry Python package manager installed locally, you can install the CLI the following way:
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:
tomodo --help
Install from source with pip
You can install the dependencies with pip using the following command:
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:
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.
Create a Deployment
Create a deployment with the provision command. For example, here's how you create a standalone
instance with zero configuration:
tomodo provision --standalone
To create a replica set with zero configuration, run the provision command in the following way:
tomodo provision --replica-set
To create a sharded cluster with zero configuration, run the provision command in the following way:
tomodo provision --sharded
Take a look at the provision command's help page to read the full set of options
with tomodo provision --help:
Usage: tomodo provision [OPTIONS]
Provision a MongoDB deployment
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────╮
│ --standalone --no-standalone Provision a MongoDB │
│ standalone instance │
│ [default: no-standalone] │
│ --replica-set --no-replica-set Provision a MongoDB replica │
│ set │
│ [default: no-replica-set] │
│ --sharded --no-sharded Provision a MongoDB sharded │
│ cluster │
│ [default: no-sharded] │
│ --replicas [1|3|5|7] The number of replica set │
│ nodes to provision │
│ [default: 3] │
│ --shards INTEGER The number of shards to │
│ provision in a sharded │
│ cluster │
│ [default: 2] │
│ --arbiter --no-arbiter Add an arbiter node to a │
│ replica set │
│ [default: no-arbiter] │
│ --name TEXT The deployment's name; │
│ auto-generated if not │
│ provided │
│ [default: None] │
│ --priority --no-priority Priority (currently │
│ ignored) │
│ [default: no-priority] │
│ --port INTEGER RANGE The deployment's start port │
│ [0<=x<=65535] [default: 27017] │
│ --config-servers INTEGER The number of config server │
│ replica set nodes │
│ [default: 1] │
│ --mongos INTEGER RANGE [x>=1] The number of mongos │
│ routers │
│ [default: 1] │
│ --auth --no-auth Whether to enable │
│ authentication (currently │
│ ignored) │
│ [default: no-auth] │
│ --username TEXT Optional authentication │
│ username │
│ [default: None] │
│ --password TEXT Optional authentication │
│ password │
│ [default: None] │
│ --auth-db TEXT Authorization DB (currently │
│ ignored) │
│ [default: None] │
│ --auth-roles TEXT Default authentication │
│ roles (currently ignored) │
│ [default: │
│ dbAdminAnyDatabase │
│ readWriteAnyDatabase │
│ userAdminAnyDatabase │
│ clusterAdmin] │
│ --image-repo TEXT The MongoDB image name/repo │
│ [default: mongo] │
│ --image-tag TEXT The MongoDB image tag, │
│ which determines the │
│ MongoDB version to install │
│ [default: latest] │
│ --network-name TEXT The Docker network to │
│ provision the deployment │
│ in; will create a new one │
│ or use an existing one with │
│ the same name if such │
│ network exists │
│ [default: mongo_network] │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────
Describe Deployments
Use the describe command to print the details of one or all deployments:
# 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:
# List all deployments
tomodo list
# List only running deployments
tomodo list --exclude-stopped
Stop Deployments
Use the stop command to stop your deployments:
# 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:
tomodo start --name printed-lemming
Remove Deployments
Use the remove command to permanently remove deployments:
# 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
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).
from typing import Dict
from tomodo import functional as tfunc
from tomodo.common.errors import DeploymentNotFound
from tomodo.common.models import Deployment, Mongod, ReplicaSet, ShardedCluster
# Create a standalone instance:
mongod: Mongod = tfunc.provision_standalone_instance(port=1000)
# Create a replica set:
replica_set: ReplicaSet = tfunc.provision_replica_set(port=2000, replicas=3)
# Create a sharded cluster:
sh_cluster: ShardedCluster = tfunc.provision_sharded_cluster(port=3000, shards=2, config_servers=3, mongos=2)
# Stop a deployment:
mongod.stop()
# Restart a 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}")
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
