OpenDockerMongo: Start mongo-instance in docker

In Dans-labs/MongoPlussed: Extensions of Mongolite Package

Description

If you want to run your own mongoDB instance, this can be done as a docker container. This function initializes an instance for you from R. In a typical setup, it follows these steps:

1. Check if docker is running, if not, start it

2. If update is set to TRUE, and a container with the given dockername exists, it is stopped and removed.
   Likewise for a viewer-container, and then images are downloaded and installed.

3. Check if a container with the given dockername exists. If not, create one:

   • The script first check if the given port is still free (no process is currently listening). If yes, it uses this port.
     If not, but the port is in use by another docker-container and kickport is set to TRUE, stop that docker-container
     Or if port is given as a textstring ending with '+', increase portnumber until a free port is found
     Otherwise, an error is thrown.

   • if update is set to TRUE, the script checks whether a new version of the image is available, and updates that.

   • Finally the docker container is started.

   • If a username is given, it is initialized with the –auth option, meaning authentication is required in subsequent access as well.

   • If no image-name is provided, "mongo" is used.

   • Data (files in docker-fs /data/db) is stored in path. A logfile is located here as well (called log.log)

4. If a container with the given dockername exists, but is not running, restart it.
   In this case, the port number/imagename/path of this container is used, if needed with a warning.

5. See if the docker-container is responding: if we can establish a connection, and insert and remove documents.
   If you want to debug: it inserts and removes a document with the following content: 'ID: "ConnectionTesting_r78qfuy8asfhaksfhajklsfhajksl"'

6. if inclView is not NULL, a GUI is also initialized, as a docker container

   • Also updated if update is TRUE

   • Uses port given in viewport, increased if necessary and port ends with "+"

   • The docker container for the viewer is called dockername_view. The mongo-express container can only be coupled to a mongo instance running in docker, so currently it is not possible to set up a mongo-viewer for a remote server.

   • If there is already a container with that name, it is restarted (note that this cannot be the case if update was TRUE, then any viewer-container is already removed).
     If this container is pointing to another mongo-instance, a warning is generated.

   
   That GUI can be found with any internet browser, going to http://localhost:viewport

You can skip any of these steps with the skip parameter, e.g. if you already know you want to connect to a certain port, but don't know what the docker container is called (or there is no docker container, and you want to connect to a remote server).

Furthermore, the starting process of docker and the docker container may take some time. This can be done in the background, by setting preOnly to TRUE. If the script then encounters a situation in which it has to wait, it returns a numerical, indicating the step to resume. Thus, you can run your own script by first calling OpenDockerMongo(preOnly=TRUE, ...), then soing some useful work (that may take time), then calling OpenDockerMongo again (when it will hopefully be ready for the next step)

Usage

OpenDockerMongo(dockername, imagename = "mongo", path, host = "localhost",
  port = "27017+", kickport = FALSE, inclView = "mongo-express",
  viewport = "8081+", update = FALSE, preOnly = FALSE, skip = 0, db,
  collection, user = NULL, pswd = NULL, verbose = TRUE)

Arguments

dockername	name of docker container that is runnning the mongo-server. May be NULL if skip >1, in which case it connects to the host and port given.
imagename	name of docker image to use. If dockername is given, a container already exists and update is FALSE, this is ignored (if needed with a warning, supply NULL to also suppress warnings)
path	path to store data (docker file-system: /data/db). If dockername is given, a container already exists and update is FALSE, this is ignored (if needed with a warning, this may cause false positives if symbolic links are used, or a path needs to be further expanded) /cr If path does not exist, it is created, and a new database is initialized.
host	use to connect to a remote server. If it is not null, ”, localhost or similar, skip is set to 4, any docker parameters are ignored (with a warning if needed)
port	port to use, default mongoport is 27017. Appending with "+" means a higher port number may be used if needed. Ignored if a container is just restarted (with a warning if the port number was exact, or the difference between number provided and used is more than 10. Use port 0 to suppress any warnings)
kickport	If port is already in use by another docker container, should this container be stopped? Ignored if port ends in "+". Only looks at running containers, and stops them, but doesn't remove them.
inclView	also initialize an extra container that links to the mongo-server, for example to be used as a GUI. The default, mongo-express, gives a webinterface to the mongo-DB. Given as a string with the docker imagename, 'previous', or NULL to not start anything. The value 'previous' only works if there already is a viewer-container initialized, which you just want to restart without any checks. Currently only tested with NULL or mongo-express, unlikely to work for other vallues (but may be expanded in the future).
viewport	Port to use for the viewer-container, can also be appended with "+", ignored if inclView==FALSE. Ignored if a container is just restarted (with a warning if the port number was exact, or the difference between number provided and used is more than 10. Use port 0 to suppress any warnings)
update	logical, should the script restart everything? If TRUE does the following: stop containers with dockername or dockername_view remove containers with dockername or dockername_view Update the docker images (imagename and inclView if not NULL)
preOnly	logical, if the script has to wait for a docker action, should it return control? If TRUE and it has to wait, it returns a numerical that can be given to skip for the next call. Does not work for downloading new images (cannot be run as background task) Note that if the return is >2, any old containers are already removed and updated, so setting update to TRUE would waste extra time.
skip	steps to skip, e.g. if you already have a server instance initialized, you can use skip=4. Numbering is identical to the steps enumerated here, the script starts with skip+1.
db, collection, user, pswd	Parameters used for connecting to the server: databasename, collection-name, username and password. If user is NULL, authentication is disabled when creating the container.
verbose	print output indicating status?

Value

An monPlus-object, or if preOnly is TRUE and we have to wait for a background process, a numerical indicating what step we are (which can be given to skip).

See Also

http://www.docker.com for general information on docker
https://hub.docker.com/_/mongo/ for information on running a mongo-container in docker
mongolite
RMongo

Examples

  # From a fresh install.
  # Using preOnly means that while docker is starting, control is returned.
  DB <- OpenDockerMongo('MyMongoContainer', path='~/Docker/Mongo/MyDb',
  preOnly=TRUE, db='MyDb',collection='MyCol')
  # Generate new documents to insert, while generating these docs,
  # docker processes are running in the background:
  Docs <- data.frame(MyID=1:100, myData=rnorm(100))
  if(is.numeric(DB)) DB <- OpenDockerMongo('MyMongoContainer', path='~/Docker/Mongo/MyDb',
  db='MyDb',collection='MyCol', skip=DB)
  # Control is only returned when finished, so DB is now a monPlus-object.
  DB$insert(Docs)
  # If port 8081 was previously free, you can now browse your docs at http://localhost:8081

  # Cleaning up:
  DB$remove(paste0('{"MyID": {"$in": [',paste0(1:100, collapse=', '),']}}'))
  if(DB$count()==0) DB$drop()
  system('docker stop MyMongoContainer')
  system('docker stop MyMongoContainer_view')
  system('docker rm MyMongoContainer')
  system('docker rm MyMongoContainer_view')

Dans-labs/MongoPlussed documentation built on May 17, 2019, 6:07 a.m.