Skip to content

mlaunch

Jump to bottom
Thomas Rueckstiess edited this page Sep 9, 2013 · 30 revisions

This tool lets you quickly spin up MongoDB environments on your local machine. It supports various configurations of stand-alone servers, replica sets and sharded clusters. In addition to all the listed parameters of mlaunch below, you can pass in any arbitrary options that a mongos or mongod binary would understand, and mlaunch will pass them on to the correct binary.

Usage

mlaunch [-h] [--version] (--single | --replicaset | --restart)
        [--verbose] [--dir DIR] [--port PORT] [--authentication] [--binarypath PATH]
        [--nodes NUM] [--arbiter] [--name NAME] 
        [--sharded S [S ...]] [--config N] [--mongos N]

Required Parameters

mlaunch requires exactly one of the following parameters to run: --single, --replicaset or --restart. They are mutually exclusive and one must be specified for each mlaunch execution.

Single Node

--single
This parameter will create a single stand-alone node. If --sharded is also specified, this parameter will create each shard as a single stand-alone node.

Example
mlaunch --single

This command would start a single mongod instance on port 27017.


###### Replica Set `--replicaset`
This parameter will create a replica set rather than a single node. Other [replica set parameters](./mlaunch#replica-set-parameters) apply and can modify the properties of the replica set to launch. If `--sharded` is also specified, this parameter will create one such replica sets for each shard.
Example
mlaunch --replicaset

This command would start a replica set with (by default) 3 nodes on ports 27017, 27018, 27019.


###### Restart Existing Environment `--restart`, `--restore` (alias)
Either of these options will search for a `.mlaunch` directory under the given "`--dir`" directory (by default `./data`, see [Data Directory](./mlaunch#data-directory)). This is where **mlaunch** stores information about previous starts. If such a directory exists, **mlaunch** will restart the same setup as before. This is useful if you need to tear down and bring up the same environment multiple times.

General Parameters

Help

-h, --help
shows the help text and exits.

Version

--version
shows the version number and exits.

Verbosity

--verbose
In addition to launching the specified setup, this parameter will print how each of the instances was launched.

Data Directory

--dir DIR
This parameter changes the directory where mlaunch stores its data and log files. By default, the directory is the local directory ./data, below the current working directory.

Start Port

--port PORT
Uses PORT as the start port number for the first instance, and increases the number by one for each additional instance (mongod/mongos). By default, the start port value is MongoDB's standard port 27017. Use this parameter to start several setups in parallel on different port ranges.

Example
mlaunch --replicaset --nodes 3 --port 30000

This command would start a replica set of 3 nodes using ports 30000, 30001 and 30002.


###### Authentication `--authentication`
This parameter enables authentication on your setup. It will transparently work with single instances (that require `--auth`) as well as replica sets and sharded environments (that require `--keyFile`). There is no need to additionally specify a keyfile, a random keyfile will be generated for you.
Binary Path

--binarypath PATH
Will set the path where mlaunch looks for the binaries of mongod and mongos to the provided PATH. By default, the $PATH environment variable is used to determine which binary is started. You can use this option to overwrite the default setting. This is useful for example if you compile your own source code and want mlaunch to use the compiled version.

Example
mlaunch --single --binarypath ./build/bin

This command will look for the mongod binary in ./build/bin/mongod instead of the default location.


Replica Set Parameters

The following parameters change how a replica set is set up. These parameters require that you picked the --replicaset option from the required parameters.

Number of Nodes

--nodes N
Specifies the number of data-bearing nodes (arbiters not included) for this replica set. The default value is 3.

Example
mlaunch --replicaset --nodes 5

This command starts 5 mongod instances and configures them to one replica set.


###### Arbiter `--arbiter` If this parameter is present, an additional arbiter is added to the replica set. Currently, **mlaunch** only supports adding one arbiter. Additional arbiters can be started and added to the replica set manually.
Example
mlaunch --replicaset --nodes 2 --arbiter

This command starts 2 data-bearing mongod instances and adds one arbiter to the replica set, for a total of 3 voting nodes.


###### Replica Set Name `--name NAME`
This option lets you modify the name of the replica set. This will change both the name and the sub-directory of the `dbpath`. This option is only allowed for a single replica sets and will not work in sharded setups, where replica set names are given automatically. The default name is `replset`.
Example
mlaunch --replicaset --name "my_rs_1"

This command will create a replica set with the name my_rs_1 and will also store the dbpath and log files under ./data/my_rs_1.


### Sharding Parameters

The following parameters influence the setup of a sharded environment. Each shard will be a copy of the previously specified setup, be it a single instance or a replica set.

Shards

--sharded S [S ...]
If this parameter is provided, sharding is enabled and mlaunch will create the specified number of shards and add the shards together to a sharded cluster. The parameter can work in two ways: Either by specifying a single number, which is the number of shards, or by specifying a list of shard names.

Example
mlaunch --single --sharded 3

This command will create an environment of 3 shards, each consisting of a single stand-alone node. The shard names are shard0001, shard0002, shard0003. It will also create 1 config server and 1 mongos per default.


> ###### Example > > mlaunch --replicaset --sharded tic tac toe > > This command will create 3 shards, named `tic`, `tac` and `toe`. Each shard will consist of a replica set of (per default) 3 nodes. It will also create > 1 config server and 1 mongos per default.
###### Config Servers `--config N`
This parameter determines, how many config servers are launched in a sharded environment. The default number is 1. The only valid options for `N` are 1 or 3.
Mongos

--mongos N
This parameter determines, how many mongos instances are launched in a sharded environment. The default number is 1. With this setting, the default can be changed to N mongos instances.

Clone this wiki locally