Skip to main content

A CLI tool to control MongoDB deployments on Docker

Project description

tomodo logo

Latest Release Unit Tests Python Version License

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                              INTEGER                      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                                     Arbiter node (currently ignored) [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 [0<=x<=65535]  The deployment's start port [default: 27017]                                        │
│ --config-servers                        INTEGER                      The number of config server replica set nodes [default: 1]                          │
│ --mongos                                INTEGER                      The number of mongos routers (currently ignored) [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                         [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

# Describe 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 a deployment 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 a deployment 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 machine running, but you'll be able to invoke tomodo programmatically.

from tomodo import Provisioner, ProvisionerConfig

provisioner = Provisioner(
    config=ProvisionerConfig(
        port=20000,
        replica_set=True,
        replicas=3,
        name="my-replica-set"
    )
)

deployment = provisioner.provision()

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tomodo-0.1.5.tar.gz (20.7 kB view hashes)

Uploaded Source

Built Distribution

tomodo-0.1.5-py3-none-any.whl (23.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page