Adding Support for Cosmos db Emulator for Local Environment

Azure Cosmos DB Linux Emulator

The Azure Cosmos DB Linux Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Currently, the Linux emulator only supports SQL API [Source]. The Time tracker works with the SQL API so this emulator is good for testing purposes.

Installing Docker and Docker Compose

In order to work with CosmosDB it is necessary to have Docker and Docker Compose installed.

How to install Docker

To install on Mac follow the steps shown here.

To install on Windows follow the steps shown here.

To install on Linux follow the steps shown here.

How to install Docker Compose

To install Docker Compose, please choose the operating system you use and follow the steps here.

Once installed Docker and Docker Compose we must create a .env file in the root of our project where we will put the following environment variables.

export MS_AUTHORITY=XXXX
export MS_CLIENT_ID=XXXX
export MS_SCOPE=XXXX
export MS_SECRET=yFo=XXXX
export MS_ENDPOINT=XXXX
export DATABASE_ACCOUNT_URI=XXXX
export DATABASE_MASTER_KEY=XXXX
export DATABASE_NAME=XXXX
export FLASK_APP=XXXX
export AZURE_APP_CONFIGURATION_CONNECTION_STRING=XXXX
export FLASK_DEBUG=XXXX
export REQUESTS_CA_BUNDLE=XXXX

Please, contact the project development team for the content of the variables mentioned above.

Initial data collection process.

Using the Data Migration Tool with Cosmos DB

In order to obtain the initial data from our local database, we made use of the Azure DocumentDB Data Migration Tool.

And follow the steps in the Get To Work section on the next page.

Once we finished with the steps mentioned in Get to Work, we obtained a series of .json files, which were joined into one called seed_database.json, this .json file is structured as follows:

{
    "projects": [Project],
    "project_types": [Project_Type],
    "activities": [Activity],
    "customers": [Customer],
    "time_entries":[Time_Entry],
}

To make use of this file please contact directly with the development team of the Time Tracker project.

Making use of the JSON Seed Database file.

Once the Time Tracker team has provided you the seed_database.json file, the first thing to do is to paste it into the cosmosdb-emulator folder in the backend of the project.

Then we will modify the init_emulator_db.py file located in the same folder and add the following:

from azure.cosmos import exceptions, CosmosClient, PartitionKey
import os, sys, json

## This two lines are added
with open('/usr/src/app/cosmosdb-emulator/seed_database.json') as database_file:
    seed_database=json.load(database_file)
#

sys.path.append("/usr/src/app")

# More code in the file...

And we will also modify the following lines:

# More code in the file...

print('- Project')
from time_tracker_api.projects.projects_model import container_definition as project_definition

##These lines were modified.
project_container=database.create_container_if_not_exists(**project_definition)
for project in seed_database['projects']:
    project_container.create_item(body=project)

# More code in the file...

Where it should be noted that project_container, project and seed_database['projects'] will change depending on the information being entered into the database. As you can see below.

# More code in the file...

print('- Project type')
from time_tracker_api.project_types.project_types_model import container_definition as project_type_definition
project_type_container=database.create_container_if_not_exists(**project_type_definition)
for project_type in seed_database['project_types']:
    project_type_container.create_item(body=project_type)

# More code in the file...

As explained above, the data for which the names must be changed are as follows:

- Projects: project_container|project|seed_database['projects']
- Project Types: project_type_container|project_type|seed_database['project_types']
- Activities: activity_container|activity|seed_database['activities']
- Customers: customer_container|customer|seed_database['customers']
- Time Entries: time_entry_container|time_entry|seed_database['time_entries']

And finally the following line is added:

# More code in the file...

database_file.close()

print("Done!")

Running in docker compose

Once we have installed Docker, Docker Compose and configured the CosmosDB database, we execute the following command in the terminal or console (we must verify if we are inside the backend of the project):

docker-compose up

Possible errors in the execution of the command.

In some cases the execution of this command will require super user permissions and we must execute the same command preceding sudo, as shown below:

sudo docker-compose up

Or in other occasions it is possible that the Docker service is not up, then we proceed to execute the following commands one by one:

First

sudo systemctl enable docker

Second

sudo systemctl start docker

Then

sudo docker-compose up

Now we have our own local database and we can use it however we want! Awesome!