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
- Installation
- Architecture
- Development
- Testing
- Publishing
- Contributing
- Resources
- License
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.
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:
- Cloning the repository.
- Setting your Firebase account credentials.
- Installing project dependencies and development tools.
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
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"
]
}
}
}
}
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.
- Python
- Django
- Docker
- Firebase
- Firebase Tools
- Google Cloud Platform
- Google Cloud SDK
- Node.js
- Javascript, HTML, CSS
- Gimp
- Inkscape
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.
Cannlytics generally follows a model-template-view (MTV) architectural pattern, where:
- The model is Django, the engine that sends requests to views.
- The views are Python functions that describe the data to be presented.
- The templates are Django HTML files that describe how the data is presented.
Cannlytics favors a domain-style code structure for apps and material that will be edited frequently and a ducks-style code structure for concepts within the apps. Ducks π¦ can inherit properties if needed and are encouraged to be individualized and self-contained as possible. The architecture of the Cannlytics app is as follows.
βββ .admin
β βββ tokens
β βββ your-firebase-service-account.json
βββ .firebase
β βββ firestore.indexes # Available database queries.
β βββ firestore.rules # Database access control and data validation.
| βββ storage.rules # File storage access control and validation.
βββ api
β βββ {endpoint}
β | βββ {endpoint}.py # Implementation of specific API endpoints.
β βββ urls.py # Defined API endpoints.
| βββ views.py # Implementation of general API endpoints.
βββ cannlytics
β βββ lims # All LIMS logic.
β βββ traceability
β | βββ leaf # Leaf Data Systems API module.
| | βββ metrc # Metrc API module.
β βββ utils # General utility functions.
β βββ firebase.py # Firebase module.
| βββ models.py # Main data entities.
βββ console
β βββ assets
β | βββ css # Core style, minified and bundled.
β | βββ js # JavaScript bundled into a `cannlytics` module.
β βββ core # Required Django configuration.
β βββ static/console # Static files, like images.
β βββ templates/console # User interface templates.
β βββ settings.py # Django configuration.
β βββ state.py # Static text for certain pages and sections.
β βββ urls.py # Console navigation.
β βββ utils.py # General console utility functions.
| βββ views.py # Implementation of user interfaces and their context.
βββ docs
β βββ src # The documentation text.
β βββ theme # The style of the documentation.
| βββ Dockerfile # Documentation container configuration.
βββ node_modules
βββ public
| βββ static # Files hosted with Firebase hosting.
βββ tests # Tests for all features and functionality.
βββ tools # Development tools.
βββ website # A company website.
βββ .env # Your secrets.
βββ .firebasesrc # Firebase hosting sources.
βββ db.sqlite3 # Unused SQL database.
βββ Dockerfile # Docker container configuration.
βββ firebase.json # Firebase configuration file.
βββ LICENSE
βββ manage.py # Django utility script.
βββ mkdocs.yaml # Documentation configuration.
βββ package.json # Node.js dependencies and scripts.
βββ README.md
βββ requirements.txt # Python requirements.
βββ webpack.config.js # JavaScript and CSS bundle configuration.
Development can happen in many avenues. Frequent, small scope pull requests are encouraged. Any contribution, even if it needs future polishing, helps build the project and advance the field of cannabis analytics. In general;
- Create a fork of the repository.
- Work on a solution for your most-pressing problem.
- Create a pull request for your changes to be reviewed and merged into the project upon approval or for you to receive feedback on how your changes can be approved.
The simplest way to run the app is to open a command line from the project's root directory and run:
python manage.py runserver
You can also leverage django-livereload-server for hot-reloading while you develop.
npm run start
Below is a diagram that depicts how Cannlytics leverages [Firebase Authentication] to authorize user requests.
Original image: How to authenticate users on Google App Engine using Firebase
Hot-reloading is an important tool of development. You can use django-livereload-server
, which uses both python-livereload and django-livereload, for smooth reloading. You can install django-live-reload-server with:
pip install django-livereload-server
You can start hot-reloading by starting the livereload
server:
python manage.py livereload
In another console, you start the Django development server as usual:
python manage.py runserver
You can build the static assets, JavaScript and CSS, utilizing Webpack. The JavaScript bundle is a JavaScript module and is callable from the user interface with the cannlytics
namespace. You can run the build for development with:
webpack-dev-server --env production=False
or
npm run webpack
It is an inconvenience to run multiple consoles, but a major convenience to have smooth hot-reloading. So, npm-run-all
is used to run multiple servers in the same console for smooth development. When you are setup, you can run the project for development simply with:
npm run start
Cannlytics operates with a NoSQL database, [Firestore] by default. You can conceptualize every entity as a JSON object called a document. A group of documents is a collection. Every document is required to be a member of a collection.
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
.
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 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 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 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:
All text material is either stored in JSON in state.py
or written in Markdown in docs
directories.
Resources:
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 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
andlivereload
, so you need to be careful when and where you install Python requirements. If you run into adjango-livereload-server
import error, first check thatPRODUCTION = False
in yourconsole/settings.py
and then follow these instructions to uninstalllivereload
and reinstalldjango-livereload-server
.
When you are ready, you can build the documentation:
npm run build-docs
And publish the documentation:
npm run publish-docs
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
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:
- 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
- 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}
- 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
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.
- Charles Rice charles@ufosoftwarellc.com
- Carlos Krefft carlos@krefft.org
- Keegan Skeate keegan@cannlytics.com
Cannlytics Copyright (Β©) 2020-2021 Cannlytics and Cannlytics Contributors.
Made with 𧑠and your good will.