This add-on is operated by comSysto GmbH
German based MongoDB Provider
MongoSoup
Last updated June 28, 2016
This is a draft article - the text and URL may change in the future. This article is unlisted. Only those with the link can access it.
The MongoSoup add-on is currently in beta.
Table of Contents
- Provisioning the add-on
- Access the provisioned MongoDB instance
- Local setup
- Using with Ruby
- Using with Ruby for SSL
- Using with Python/Django
- Using with Python/Django for SSL
- Using with Java
- Using with PHP
- Using with PHP for SSL
- Using with Node.js (JavaScript)
- Dashboard and Monitoring
- Migrating between plans
- Removing the add-on
- Support
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:create 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:create 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 control panel.
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 the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env
file. To view all of your app’s config vars, type heroku config
. Use the following command to add the MONGOSOUP_URL values retrieved from heroku config to your .env
file.
$ 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
.
For more information, see the Heroku Local article.
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);}
?>
Using with Node.js (JavaScript)
// npm install mongodb
var mongodb = require('mongodb')
, MongoClient = mongodb.MongoClient;
MongoClient.connect(process.env.MONGOSOUP_URL, function(err, db) {
if(err) {
console.log("failed to connect to the database");
} else {
console.log("connected to database");
}
var collection = db.collection('grades')
collection.find({}).toArray(function(err, docs) {
if (err) {
return console.error(err)
}
docs.forEach(function(doc) {
console.log('found document: ', 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 Dashboard 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:destroy 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.