Quick Start

Version 2.1.0

Download

Desktop distributions are electron applications and you can start Mongoclient without installation thanks to electron. But desktop distributions come with pre-packaged MongoDB and NodeJS within them, that sometimes causes trouble. Feel free to open an issue on github if you encounter one. It's recommended to use desktop distributions if you're a new developer and don't want to do anything else but a few clicks.
But if you already have docker, it's better to use docker build, so that you can use latest features all the time, and docker isolates containers from your environment.

Desktop App Docker Web (Compile)

Pricing & Features

No worries, Mongoclient is completely free, open-source and it will be forever. But if you need an in-house deployment, special feature implementation or enterprise support just contact with us by sending a mail to info@mongoclient.com

Features
  • Supports LDAP, Kerberos (GSSAPI) enterprise authentications
  • Beginner helper query wizard
  • Live charts for active collection read/write operations
  • Live monitoring for memory and database statistics
  • Smart mongodb shell with auto completion
  • Supports X509 authentication
  • SSH tunneling
  • In-place data update, insert
  • Export result set as JSON, CSV
  • Import mongoexport results
  • Database dump/restore
  • User management from an intuitive UI without queries
  • File (GridFS) management from an intuitive UI without queries
  • Index management from an intuitive UI without queries
  • Aggregation pipeline tool, drag & drop stages between your pipeline list
  • Supports extended JSON
  • Manage stored functions
  • Multiple result views with keeping their history and query style
  • Schema analyzer (using variety.js)
  • Field auto completion for queries
  • Supports SCRAM_SHA_1 and MONGODB_CR authentications
Enterprise Features
  • Save live monitoring data for later use
  • Email notification for per incident (RAM, CPU usage) for the specified levels
  • Performance analyzer
  • Save & Share your queries with your teammates with only single link.
  • Manage replica sets & shard clusters from an intuitive GUI
  • Save aggregation tool's queries for later use
  • Data comparision between collections & databases
  • Priority support response time (2 business days)
  • Contact us for more...

Installation

Docker

TL;DR
docker run -d -p 3000:3000 -v <path>:/data/db mongoclient/mongoclient

Docker is one of the best ways to quickly start using a Mongoclient instance. Mongoclient offers a pre-built docker container which you can just pull and start using. The container depends below frameworks, but you don't have to explicitly setup these, it comes with these frameworks.

Also since it isolates your environment from container it gives you to advantage of using Mongoclient regardless of your system and hosting service (AWS, Digital Ocean etc...)

Inside of image, there's a new user named node, to apply best practices of docker (not starting with root) node user is capable of managing mongodb that's installed to inside of container as well as managing built Mongoclient application

Dependencies
  • Debian 8 as base image
    • curl
    • ca-certificates
    • bzip2
    • build-essential
    • numactl
    • python
    • git
    • wget (to get gosu)
    • gosu
  • NodeJS >= 4.7.3
  • MongoDB >= 3.4.2
  • MeteorJS >= 1.4.3.2

The container itself comes along with its dependencies, but you can define some of them explicitly with environment variables

Environment Variables
# Variable Description
1 ROOT_URL Useful to start mongoclient from another base URL, by default uses root
2 MONGO_URL Set an external mongodb URL to use for mongoclient, by default an internal mongodb is being used
3 MONGO_OPLOG_URL To track mongoclient's mongo operations set an external mongodb URL, by default there's no tracking
4 STARTUP_DELAY Delay container's startup to let everything startup, by default there's no delay
5 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
6 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
7 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
8 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.
Available Tags

Each released version is being tagged at docker hub to be used as stable releases. But it's okay to use latest tag everytime.

  • latest
  • 2.1.0
  • 2.0.0
  • 1.5.0
  • 1.4.0 (deprecated)
Example Docker Run Commands
# Example Description
1 docker pull mongoclient/mongoclient Runs master branch
2 docker pull mongoclient/mongoclient:2.1.0 Runs version 2.1.0
3 docker run -d -p 3000:3000 \
-v <path>:/data/db \
mongoclient/mongoclient
Bind an extra volume to /data/db to keep your connections, settings persistent
4 docker run -d -p 3000:3000 \
-e ROOT_URL=http://example.com/mongoclient \
mongoclient/mongoclient
Set ROOT_URL environment variable to start Mongoclient from another base url

Compile as Meteor Application (WEB)

This is a hard way to start using Mongoclient, but if you're already a MeteorJS developer and want to try some experimental stuff that you've implemented you can choose this way

TL;DR
  1. Install MeteorJS (supports all platforms)
  2. Download latest Mongoclient source
  3. Unzip source code and navigate into mongoclient-master
  4. Execute meteor npm install
  5. Execute meteor --port 3000
  6. All set, now you can reach Mongoclient from your browser localhost:3000

Mongoclient uses MeteorJS version 1.4.4.2 as of version 2.1.0. To read complete MeteorJS guide you can follow this link. To read more about code guideline, and how to contribute, you can check here

Available Environment Variables
# Environment Variable Description
1 ROOT_URL Useful to start mongoclient from another base URL, by default uses root
2 MONGO_URL Set an external mongodb URL to use for mongoclient, by default an internal mongodb is being used by meteor itself
3 PORT Change port of meteor, can be also set by --port argument at startup by default it's set to 3000
4 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
5 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
6 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
7 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Updating Mongoclient From Previous Version

Mongoclient checks newer versions each time you select a collection from left panel. It's main cause is forcing people to update the newest version all the time.

Per deployment type, or distribution type Mongoclient offers a solution to migrate your old connections and settings into new version.

In case of migrating from 1.x version to 2.x version you may want to use Import/Export feature, which will automatically migrate your data to 2.x versions regardless of your system or deployment.

1. Update Windows Portable

Mongoclient keeps it's internal mongodb's data path in %appdata%/Mongoclient/db folder across versions. Therefore you don't have to worry about version update, you can simply download newer version from the github page and double click to open Mongoclient.

2. Update Linux Portable

Mongoclient keeps it's internal mongodb's data path in %HOME%/var/local/Mongoclient/db folder across versions. Therefore you don't have to worry about version update, you can simply download newer version from the github page and double click to open Mongoclient.

3. Update OSx Portable

Mongoclient keeps it's internal mongodb's data path in %HOME%/Library/Preferences/Mongoclient/db folder across versions. Therefore you don't have to worry about version update, you can simply download newer version from the github page and double click to open Mongoclient.

4. Update Docker

The easiest way to update Mongoclient is using Docker, if you're binding proper volume to Mongoclient across its versions, everything should work fine. Check here for more info.

5. Update Other Deployments/Compile From Source

If you're compiling Mongoclient from its source or doing another deployment, you may find the relative data in the my-deployment/local/db, so copying data path would be enough to keep everything.

Except from that, it's always recommended to use MONGO_URL environment variable, therefore you'll lose nothing across version updates.

Other Deployment Options

If you're not familiar with Docker and don't want to struggle with compiling Mongoclient as MeteorJS application you can consider using one of these deployment options, some of them lets you to deploy Mongoclient platform, as a service, (PaaS) and for the rest you need to manually setup Mongoclient

Systemd (Linux)

TL;DR
  1. Clone Mongoclient git clone https://github.com/mongoclient/mongoclient.git
  2. Install MeteorJS
  3. Navigate to systemd folder cd /etc/systemd/system/
  4. Create file mongoclient.service with the content:

    [Unit]
    Description=MongoDB management tool
    After=network-online.target
    [Service]
    User=mongoclient
    Group=mongoclient
    WorkingDirectory=/path/to/clone/mongoclient/
    Environment=MONGOCLIENT_AUTH=true
    Environment=MONGOCLIENT_USERNAME=MYUSERNAME
    Environment=MONGOCLIENT_PASSWORD=MYPASSWORD
    ExecStart=/usr/local/bin/meteor --port MYPORT
    [Install]
    WantedBy=multi-user.target
  5. Execute systemctl enable mongoclient.service

Systemd is an init system used in Linux. Check wikipedia for more information.

Environment Variables
# Configuration Description
1 ROOT_URL Useful to start mongoclient from another base URL, by default uses root if empty
2 MONGO_URL Set an external mongodb URL to use for mongoclient, by default it uses an internal one that comes from Meteor
3 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
4 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
5 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
6 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Heroku

TL;DR
Deploy

Heroku is a cloud platform as a service (PaaS) and bypasses infrastructure stuff. Mongoclient takes advantage of heroku-16 stack which comes with Ubuntu 16.04. Since Mongoclient's shell and schema analyzer depends on Mongo executable 3.4 and the executable depends on GLIBC's 2.23 version, this stack suits Mongoclient most.

There's only one configuration you have to do while deploying to Heroku

Environment Variables
# Configuration Description
1 ROOT_URL This has to be set as http://<heroku-app-name>.herokuapp.com/<optional-path>, heroku-app-name must be same as your application name
MongoDB Dependency

As Mongoclient needs a running mongodb instance to persist your connections and settings, it uses mLab addon's free edition which is enough to keep these details.

Cloud Foundry

TL;DR
  1. Clone Mongoclient git clone https://github.com/mongoclient/mongoclient.git
  2. Navigate into it cd mongoclient
  3. Execute mv manifest.yml.sample manifest.yml
  4. Change variables inside of manifest.yml as how you wish
  5. Install command line tool
  6. Execute cf login -a api.ng.bluemix.net -u username -p password
  7. Execute cf push

As a developer you can trail the instance of CloudFoundry, either from IBM Bluemix or Pivotal. Since Mongoclient needs a MongoDB instance to persist your connections and settings, you need an external mongodb which can be acquired from Mlab for free.

You can change a few environment variable from inside of manifest.yml

Environment Variables (manifest.yml)
# Configuration Description
1 ROOT_URL Useful to start mongoclient from another base URL, by default uses root if empty
2 MONGO_URL Set an external mongodb URL to use for mongoclient, by default it's empty and has to be set
3 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
4 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
5 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
6 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Meteor Galaxy

TL;DR
  1. Install MeteorJS (supports all platforms)
  2. Clone Mongoclient git clone https://github.com/mongoclient/mongoclient.git
  3. Navigate into it cd mongoclient
  4. Create a settings.json file with content: { "galaxy.meteor.com": { "env": { "MONGO_URL": "mongodb://..." } } }
  5. Follow here for last command and deploy

Galaxy has slightly better prices comparing to other hosting services and it's best to keep a MeteorJS application since it's a MeteorJS product.

You can use a few environment variables during deployment, follow here to learn how to set them.

Environment Variables (over galaxy)
# Configuration Description
1 ROOT_URL If you want to change base url of Mongoclient you can use this parameter.
2 MONGO_URL This has to be set to deploy galaxy, since Mongoclient depends on a MongoDB instance to persist connections and settings
3 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
4 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
5 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
6 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Google Compute Engine (GCP)

TL;DR
  1. Create a compute instance with a linux image, ubuntu preferred
  2. Install docker with sudo wget -qO- https://get.docker.com/ | sh
  3. Install and run mongodb docker image sudo docker run --name db -d mongo --smallfiles
  4. Install and run Mongoclient docker image docker run --name mongoclient -d -p 3000:3000 -e MONGO_URL=mongodb://localhost:27017/meteor mongoclient/mongoclient
  5. From GCP web iterface choose your instance and click Edit
  6. Add custom metadata:
    • key: "startup-script"
    • value "sudo docker start db; sudo docker start mongoclient"

GCP offers a flexibility to setup a server instance with a few clicks. And then you can just manage your mongoclient with docker, even can set nginx and letsencrypt for SSL

Environment Variables (docker)
# Configuration Description
1 ROOT_URL If you want to change base url of Mongoclient you can use this parameter.
2 MONGO_URL This has to be set, since Mongoclient depends on a MongoDB instance to persist connections and settings, and you're setting up an another container for mongodb.
3 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
4 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
5 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
6 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Amazon Web Services (AWS)

TL;DR
  1. Create EC2 instance (ubuntu 16.04 preferred) as t2.micro
  2. Follow 2nd, 3rd, 4th elements from here

Since docker is best way to isolate system from Mongoclient, all manual deployments should be done via docker, regardless of the hosting service (GCP, AWS...)

Environment Variables (docker)
# Configuration Description
1 ROOT_URL If you want to change base url of Mongoclient you can use this parameter.
2 MONGO_URL This has to be set, since Mongoclient depends on a MongoDB instance to persist connections and settings, and you're setting up an another container for mongodb.
3 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
4 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
5 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
6 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Jelastic

TL;DR
  1. Create a new Docker environment
  2. Click Select Container, type mongoclient, and choose mongoclient/mongoclient which will come as first in the list
  3. Enter container via SSH
  4. Start MongoDB /opt/mongodb/bin/mongod
  5. Start Mongoclient node /opt/meteor/dist/bundle/main.js
  6. Create an endpoint for your environment and select 3000 as private port
Environment Variables (from jelastic console)
# Configuration Description
1 ROOT_URL If you want to change base url of Mongoclient you can use this parameter.
2 MONGO_URL This has to be set, since Mongoclient depends on a MongoDB instance to persist connections and settings, you can create an another app on jelastic and change Mongoclient's MongoDB to there with this URL.
3 MONGOCLIENT_AUTH Enable basic authentication for Mongoclient, by default it's set to false
4 MONGOCLIENT_USERNAME Basic authentication's username, has to be set with MONGOCLIENT_AUTH, by default there's no username
5 MONGOCLIENT_PASSWORD Basic authentication's password, has to be set with MONGOCLIENT_AUTH and MONGOCLIENT_USERNAME, by default there's no password
6 MONGOCLIENT_DEFAULT_CONNECTION_URL You can specify a default connection url, that will be injected into Mongoclient at startup so that, you won't have to create connection manually after installation.

Health Check

TL;DR
http(s)://<ROOT_URL>:<PORT>/healthcheck

Mongoclient has a very simple single health check endpoint. You can simply navigate to http(s)://<ROOT_URL>:<PORT>/healthcheck and expect to get 200 HTTP OK, If so, everything is alright. Such simple endpoint makes it easy to deploy Mongoclient with third party deployment tools such as marathon without worrying about deployment errors.