Skip to content

Cannlytics

version License: MIT contributions welcome

Cannlytics is simple, easy-to-use, end-to-end cannabis analytics software designed to make your data and information accessible. Cannlytics makes cannabis analysis simple and easy through data accessibility. We believe that everyone in the cannabis industry should be able to access rich, valuable data quickly and easily and that you will be better off for it. This documentation covers the Cannlytics architecture and how to build, develop, and publish the Cannlytics platform. You can view the platform live at https://console.cannlytics.com and the documentation at https://docs.cannlytics.com.

Introduction

The cannlytics package is the core module implementing cannabis analytics logic. The cannlytics module handles database interactions, file management, authentication and authorization, traceability, data importing and exporting, and the logic for all workflows, such as certificate creation, item transfers, and publishing results. The api is the interface between the user application and the cannabis analytics logic of cannlytics. The console is the user application where user's can interface with the infrastructure, such as the database, and utilize the cannabis analytics logic. The docs provide information about the project and the website provides people with information about cannabis analytics.

Installation

Cannlytics is an open box and transparent. You do not have to guess about the software used or how your logic is implemented. Our philosophy is that open source and free solutions are the best (free as in free speech, not as in free beer). In brief, installation entails:

  1. Cloning the repository.
  2. Setting your Firebase account credentials.
  3. Installing project dependencies and development tools.

1. Cloning the repository

The best place to begin is to clone the repository and get a lay of the architecture.

git clone https://github.com/cannlytics/cannlytics.git

2. Setting your account credentials

When you are ready to begin development or publish the Cannlytics web app, then you will need to setup your credentials. You will need to create a Firebase account and start a project before you begin. We recommend choosing a project name that is in kebab-case so that you can safely use the project name for many namespaces throughout the project, for example your-lims.

2.1. First, create an .env file at the project's root.

2.2. Next, create a Django secret key and save it your .env file as follows.

# tools/quickstart.py
from django.utils.crypto import get_random_string

# Generate a secret key for your project.
chars = 'abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)'
generated_secret_key = get_random_string(50, chars)
print(generated_secret_key)
# .env
SECRET_KEY=xyz

2.3 Next, add a Firebase web app. We recommend using the same namespace you chose for your project, for example your-lims, and setting up [Firebase Hosting] with your app. Once you have created a web app, navigate to your Firebase project settings, find your Firebase app Config, and set your Firebase configuration in your .env file.

# .env
FIREBASE_API_KEY=xyz
FIREBASE_AUTH_DOMAIN=your-lims.firebaseapp.com
FIREBASE_DATABASE_URL=https://your-lims.firebaseio.com
FIREBASE_PROJECT_ID=your-lims
FIREBASE_STORAGE_BUCKET=your-lims.appspot.com
FIREBASE_MESSAGING_SENDER_ID=123
FIREBASE_APP_ID=123
FIREBASE_MEASUREMENT_ID=G-abc

2.4. If you wish to leverage Cannlytics' email capabilities, then set EMAIL_HOST_USER and EMAIL_HOST_PASSWORD environment variables in your .env file. It is recommended that you create an app password if you are using Gmail.

# .env
EMAIL_HOST_USER=admin@your-company.com
EMAIL_HOST_PASSWORD=your-app-password

2.5. Finally, to facilitate communication between your app and Firebase, create and download a service account and save the path to your service account as a GOOGLE_APPLICATION_CREDENTIALS environment variable. For your security, this configuration file needs to be kept in a safe place.

# .env
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service/account.json

You will need to grant your service key Secret Manager Admin permissions in Cloud IAM Admin.

2.6. Finish by creating a .firebasesrc in the root directory with your [Firebase Hosting] references. For example

{
  "projects": {
    "default": "your-lims"
  },
  "targets": {
    "your-project": {
      "hosting": {
        "docs": [
          "your-lims-docs"
        ],
        "dev": [
          "your-lims-dev"
        ],
        "production": [
          "your-lims"
        ]
      }
    }
  }
}

3. Installing project dependencies and development tools

Cannlytics is built and depends on the following software and services, so you will need to install or setup each service. We recommend using the latest stable version of each piece of software whenever possible.

Architecture

Cannlytics is built with [Python] and leverages the [Django] framework. Cannlytics utilizes [Firebase] for user authentication with [Firebase Authentication], a [Firestore] NoSQL database for real-time data management, [Firebase Storage] for file storage, and hosted with [Firebase Hosting]. Cannlytics uses a number of Google Cloud backend services, including:

  • Cloud Build to containerize the app.
  • Cloud Registry to upload the app to storage.
  • Cloud Run to run the app as a stateless container.
  • Cloud Storage for file storage.
  • Cloud Secret Manager for storing configurations and keeping secrets secret.

    File Storage

    Cannlytics utilizes [Firebase Storage] ( a.k.a Google Cloud Storage) for most storage solutions. For help with storing static files, see serving static files on App Engine. You can gather all supporting files, located in each app's static directory, into the public/static directory with:

    python manage.py collectstatic --noinput
    

    or

    npm run collectstatic
    

    You can configure static files to be served from [Firebase Storage] instead of from [Firebase Hosting] in console/settings.py.

    Email

    If you are sending email with Gmail, then you can follow these steps.

    • Navigate to Gmail, click your profile, and click manage your google account.
    • Navigate to the security tab.
    • Enable 2-step verification and then click on App passwords.
    • Select Mail for app and enter a custom name for device.
    • Click generate and Gmail will generate an app password. Copy this app password to a text file and save it where it is secure and will not be uploaded to a public repository, for example save the password in the .admin directory.

    After you have created your app password, set your Gmail email and app password as environment variables, EMAIL_HOST_USER and EMAIL_HOST_PASSWORD respectively.

    echo EMAIL_HOST_USER=\"youremail@gmail.com\" >> .env
    echo EMAIL_HOST_PASSWORD=\"your-app-password\" >> .env
    gcloud secrets versions add cannlytics_settings --data-file .env
    

    Views

    Views are Python functions that describe the data to be presented. Django describes views in the following quote.

    "Your view can read records from a database, or not. It can use a template system such as Django's – or a third-party Python template system – or not. It can generate a PDF file, output XML, create a ZIP file on the fly, anything you want, using whatever Python libraries you want."

    Templates

    Templates are Django HTML files that describe how the data is presented. Default Django templates can be found in your Anaconda/Python directory in Lib\site-packages\django\contrib\admin\templates\admin.

    Style

    Style distinguishes one site from another. You are free and encouraged to modify the style to create a site that is uniquely yours. See style.md for a guide on the personal website's style. Bootstrap is used for styling templates. You can install Bootstrap with:

    npm install bootstrap
    npm install style-loader --save
    

    The main Cannlytics colors are:

    • Cannlytics Orange: #ff5733
    • Cannlytics Light Orange: #ffa600
    • Cannlytics Dark Orange: #e53a23
    • Cannlytics Green: #45B649
    • Cannlytics Light Green: #96e6a1
    • Cannlytics Dark Green: #3f7f34
    • Cannlytics Darkest Green: #104607

    The main Cannlytics fonts are:

    Useful open source icon sets include:

    Text Material

    All text material is either stored in JSON in state.py or written in Markdown in docs directories.

    Resources:

    Building and running the project with Docker

    First, create a docker.env file in the project's root directory using the variables found in .env.example. You can build the application in a Docker container image with:

    # build docker image
    docker build -t cannlytics .
    

    You can register the container with:

    # docker push to container registry. 
    docker push cannlytics 
    

    You can run the application container locally with:

    # run docker
    docker run -dp 8080:8080 --env-file docker.env cannlytics
    

    Finally, you can quickly run the container, or multiple containers, with:

    # bring up containers
    docker-compose up -d
    
    # bring down
    docker-compose down
    
    # logs
    docker-compose logs
    

    Documentation

    Documentation for the project is written in Markdown. Building the documentation locally requires installing Material for MkDocs and Docker. The configuration for the documentation is contained within mkdocs.yml. You can serve the documentation locally by first pulling and building the Material for MKDocs image:

    docker pull squidfunk/mkdocs-material
    docker build -t squidfunk/mkdocs-material docs
    

    Once setup, you can preview the documentation as you write:

    docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
    

    or

    npm run docs
    

    Note that there is a namespace conflict between django-livereload-server and livereload, so you need to be careful when and where you install Python requirements. If you run into a django-livereload-server import error, first check that PRODUCTION = False in your console/settings.py and then follow these instructions to uninstall livereload and reinstall django-livereload-server.

    When you are ready, you can build the documentation:

    npm run build-docs
    

    And publish the documentation:

    npm run publish-docs
    

    Testing

    You can check for errors detectable by Django with:

    python manage.py check
    

    You can run tests for a specific app with.

    python manage.py test your_app_name
    

    You can also build the platform in a docker container for your specific purposes:

    docker build . --tag gcr.io/your-lims/cannlytics
    gcloud auth configure-docker
    docker push gcr.io/your-lims/cannlytics
    

    Publishing

    See the publishing guide for complete instructions on how to publish Cannlytics for production. The guide is based on the Running Django on Cloud Run guide. After setup, publishing is done with one command:

    npm run publish
    

    If you need to change accounts or projects, then you can use:

    gcloud config set account `ACCOUNT`
    gcloud config set project `PROJECT ID`
    

    The build process contains three steps:

    1. Containerize the app and upload it to Container Registry.

    Build your container image using Cloud Build by running the following command from the directory containing the Dockerfile:

    gcloud builds submit --tag gcr.io/your-lims/cannlytics
    
    1. Deploy the container image to Cloud Run.
    gcloud beta run deploy your-lims --image gcr.io/your-lims/cannlytics --region us-central1 --allow-unauthenticated --service-account=${GCS_SA}
    
    1. Direct hosting requests to the containerized app.

    This step provides access to this containerized app from a [Firebase Hosting] URL, so the app can generate dynamic content for the Firebase-hosted site.

    firebase deploy --only hosting:production
    

    Contributing

    Contributions are always welcome! You are encouraged to submit issues, functionality, and features that you want to be addressed. See the contributing guide to get started. Anyone is welcome to contribute anything. Email dev@cannlytics.com for a quick onboarding. Currently, the Cannlytics Console would love:

    • Art;
    • More code;
    • More documentation;
    • Ideas.

    Contributors

    License

    Cannlytics Copyright (©) 2020-2021 Cannlytics and Cannlytics Contributors.

    MIT License

    Made with 🧡 and your good will.