Configuring a mongoDB instance
rakaia supports persistent session configuration storage in mongoDB Atlas instances. The use of a mongoDB database is completely optional for rakaia users, but can provide rapid persistent storage of dataset and session variables that can be used to recreate exact images and import past session configurations. Visit the mongoDB link above for more information on mongoDB and NOSQL-style databases.
rakaia mongoDB interface & API
rakaia includes UI components for login and configuration of saved session blends in mongoDB. The UI elements can be accessed from the side panel menu; Import/Export -> Database. Credentials for authentication will depend on the specific mongoDB instance that is created for one or more users, and consist of a connection string, username, and password.
Setting up a mongoDB Atlas database
Users should visit the MongoDB cloud website to setup a rakaia database. First, users should sign up for an account, and create an organization that will house projects, clusters, and databases. For Atlas MongoDB, the hierarchy of structures/categories is as follows:
Organization -> Projects -> Clusters -> Databases -> Collections -> Documents
Once an appropriate organization for one or multiple users is set up, create a project under Organization -> Projects -> New Project. Project names are open-ended but users may choose to include rakaia in the project name to specify the types of clusters that it will contain. Projects can contain one or more clusters, but at the time of writing, each project can contain only one free cluster (M0 sandbox).
Once a project is set up, users can create clusters, which provide groups of servers for housing one of more databases:
At this point, users should decide what level of paid or free cluster is required for the specific lab/group needs. Free M0 sandbox clusters should work perfectly fine for testing out rakaia deployments and for storing basic session documents for several hundred rakaia sessions. Therefore, we recommend this option for first-time users/groups. When configuring the cluster parameters, the mame of the cluster is also open-ended depending on group/user preferences, but including rakaia in the name can be helpful for associating the database connection string to the rakaia application.
Once the cluster is successfully created (which may take a up to 5 minutes to configure the remote servers), users should select Connect under the cluster homepage. This will provide a way to retrieve the connection string, which is required in the rakaia UI. This will also allow you to create one or more users with passwords who will be able to access the cluster.
Retrieving the database connection string
The cluster connection string can be found using the following steps:
Cluster -> Connect -> Connect to your application -> Drivers.
Users should then select to connect by a driver, then select the Python driver. If successful, the modal popup should display information similar to below:
In this example the database connection string is highlighted. This connection string is specific to the mongoDB Atlas cluster created in the previous steps, and should be saved in a secure location and distributed to relevant users in a secure method as required.
When accessing the rakaia app, the connection string is provided under Import/Export -> Database -> Connection string:
Usernames nad passwords that are configured per cluster are provided in the respective input fields for mongoDB access. All of these values are auto-saved in the browser settings so that future sessions are easier to access.
Cluster databases and collections
By default, rakaia will generate a database inside the accessed cluster named rakaia, and save the session documents under a collection named blend_config. For more information on databases and documents, visit this link.
Viewing and creating configuration documents
Under the same tab where users provide login credentials for the mongoDB cluster, users can use the View saved configurations input to bring up a tabular modal showing all of the available configurations associated with a specific user account.
Saving session/blend parameters
At any point in a rakaia session that is populated by a dataset and a valid panel, users may chosoe to save the current channel blend parameters and additional session variables in the database as a JSON-style document. This document takes the same form as the JSON file output, but is stored in the cloud mongoDB cluster instead of locatlly.
Users should choose a unique, descriptive and short name for each configuration. Upon selecting Save current session, users will be informed if their configuration has been submitted successfully:
Note that if users save a configuration under a name that already exists, the most recent cofiguration will overwrite the existing one.