MongoSoup

This add-on is operated by comSysto GmbH

German based MongoDB Provider

MongoSoup

Last Updated: 20 February 2014

The MongoSoup add-on is currently in beta.

Table of Contents

MongoSoup is the first German-based MongoDB cloud hosting solution. Supported by a team of experts from MongoDB Inc’s first German partner comSysto you can have a running MongoDB database in virtually no time.

Provisioning the add-on

MongoSoup can be attached to a Heroku application through the add-on catalog or via the heroku command. The heroku command for our free, sandbox plan (the default) is:

$ heroku addons:add mongosoup
-----> Adding mongosoup to sharp-mountain-4005... done, v18 (free)

This will add a free sandbox plan, if you need something bigger then select one of MongoSoup’s plan offerings.

Other MongoSoup plans can be chosen by adding the plan id to the heroku command, like:

$ heroku addons:add mongosoup:de-medium

A list of all plans available can be found here.

When added, MongoSoup automatically creates a new user account and database for the plan you’ve chosen.

You can manage your database and data easily from the web console by clicking the MongoSoup add-on entry on your app’s deployment page, and you gain immediate access (by Heroku’s SSO mechanism) to the MongoSoup ControlPanel.

Access the provisioned MongoDB instance

Once MongoSoup has been provisioned a MONGOSOUP_URL will be available in the app configuration and will contain the canonical URL used to access the newly provisioned MongoDB instance. This can be confirmed using the heroku config:get command.

$ heroku config:get MONGOSOUP_URL
mongodb://USER:PASSWORD@dbs001.mongosoup.de//DBNAME

Your app-name, password and db-name are all automatically generated by Heroku and MongoSoup.

In the event that MongoSoup must update your MONGOSOUP_URL, you will be notified through the email address you have provided to Heroku.

After installing MongoSoup the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export MONGOSOUP_URL=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the MONGOSOUP_URL values retrieved from heroku config to .env.

$ heroku config -s | grep MONGOSOUP_URL >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Ruby

require "rubygems"
require "mongo"

uriString = ENV['MONGOSOUP_URL']
puts(uriString)
client = Mongo::MongoClient.from_uri(uriString)
dbname = uriString[%r{/([^/\?]+)(\?|$)}, 1]
db = client.db(dbname)
db.collection("grades").find().each { |obj| puts obj }

Using with Ruby for SSL

require "rubygems"
require "mongo"

uriString = ENV['MONGOSOUP_URL']
puts(uriString)
client = Mongo::MongoClient.from_uri(uriString, extra_opts={:ssl => true})
dbname = uriString[%r{/([^/\?]+)(\?|$)}, 1]
db = client.db(dbname)
db.collection("grades").find().each { |obj| puts obj }

Using with Python/Django

import os
import pymongo

uriString = os.environ['MONGOSOUP_URL']
client = pymongo.MongoClient(uriString)
db = client.get_default_database()
collection = db['grades']
for obj in collection.find():
      print obj

Using with Python/Django for SSL

import os
import pymongo

uriString = os.environ['MONGOSOUP_URL']
client = pymongo.MongoClient(uriString, ssl=True)
db = client.get_default_database()
collection = db['grades']
for obj in collection.find():
      print obj

Using with Java

String uriString = System.getenv("MONGOSOUP_URL");
MongoClientURI uri = new MongoClientURI(uriString);
MongoClient mongo = new MongoClient(uri);
DB db = mongo.getDB(uri.getDatabase());
DBCollection collection = db.getCollection("grades");
DBCursor cur = collection.find();
while(cur.hasNext()){
    DBObject obj = cur.next();
    System.out.println(obj);
}

Using with PHP

<?php
$uri = getenv('MONGOSOUP_URL');
$m = new MongoClient($uri);
$db = $m->selectDB("students");
$col = new MongoCollection($db, "grades");
$cursor = $col->find();
foreach ($cursor as $doc) { print_r($doc);}

?>

Using with PHP for SSL

<?php
$uri = getenv('MONGOSOUP_URL');
$m = new MongoClient($uri, array( 'ssl' => true ));
$db = $m->selectDB("students");
$col = new MongoCollection($db, "grades");
$cursor = $col->find();
foreach ($cursor as $doc) { print_r($doc);}

?>

Dashboard and Monitoring

The MongoSoup ControlPanel shows you statistics about your MongoDB instance(s) and your application data.

The dashboard can be accessed via the CLI:

$ heroku addons:open mongosoup
Opening mongosoup for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select MongoSoup from the Add-ons menu.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Shared plans

Currently, you can only automatically change to another plan within the shared environment. Moving to smaller plans will only work if your data will fit into the smaller plan’s limit.

Use the heroku addons:upgrade command to migrate to a new plan:

$ heroku addons:upgrade mongosoup:newplan
-----> Upgrading mongosoup:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: mongosoup:newplan

Dedicated plans

These are the steps to follow if you’ve outgrown or anticipate outgrowing your current dedicated plan. First, stop your app and any other processes running against your database. Then:

  • Backup your database
  • Remove your existing Add-on
  • Add a new Add-on
  • Restore your database
  • Redeploy your app

Providing you’re using the MONGOSOUP_URL, no application changes are required.

Removing the add-on

MongoSoup can be removed via the CLI.

All data in your database will be lost if you remove the MongoSoup add-on and cannot be undone!

    $ heroku addons:remove mongosoup
    -----> Removing mongosoup from sharp-mountain-4005... done, v20 (free)

Before removing MongoSoup a data export can be performed via the MongoSoup ControlPanel.

Support

All MongoSoup support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome via the MongoSoup ConrolPanel.