cleolabs/python repository overview

⁠cleo-backend

Cleo Backend and Dashboard

This is the web part of Lucy application.

It is composed of API used by mobile application, Dashboard used to manage all of the objects present in the system, Activation forms for users wanting to register in the system and Expert Portal - expert accessible stuff, currently it's only invoice review page.

⁠Requirements

• Python 3.7.1
• Pipenv
• Geospatial libraries (to be used with GeoDjango contrib module)
• Docker (if not installing Postgres and Redis)
• PostgreSQL 10 (if not using Docker)
• Redis 4 (if not using Docker)
• Xcode
• Aptible CLI

⁠Installation guide

⁠Install Geospatial libraries.

GeoDjango requires GEOS, PROJ.4 and GDAL system libraries. On macOS they can be installed with homebrew using this command:

$ brew install gdal

It will install GDAL and all other required libraries.

⁠Install Python.

On macOS system the easiest way to do it is to use homebrew package manager:

$ brew install python

This command will install latest Python version. cleo-backend is tested against Python 3.7.1 and we make effort to keep it updated to support latest version of Python.

Next step is to install all the required packages. This project is using Pipenv to manage dependencies.

$ pip3 install pipenv
$ pipenv install

Pipenv automatically creates virtual environment using Python version specified in Pipfile and installs all dependencies.

Possible issues with openssl during compilation

If you encounter the following error during pipenv install

ld: library not found for -lssl

It means the compiler could not find the openssl library. You can set the compiler and linker flags before running pipenv install:

export LDFLAGS="-L/usr/local/opt/openssl/lib"
export CPPFLAGS="-I/usr/local/opt/openssl/include"

To run a command from virtual environment preceed the command with pipenv run. E.g. to display virtual env Python version, use:

$ pipenv run python --version

If you don't want to type pipenv run everytime, you can start a shell with virtual env loaded:

$ pipenv shell

⁠Install PostgreSQL and Redis.

The easiest and fastest way is to use docker. If you have docker installed just go to the cleo-backend directory and use docker-compose to start and stop services:

$ docker-compose up

It will download and start all the services required by cleo-backend app.

If you want to install Postgres and Redis locally, go here⁠.

⁠Xcode and Apple Developer Account

1. Go into the App Store and install Xcode from there.
2. Log into https://developer.apple.com/ with your Apple ID. This creates an Apple Developer Account for you.
3. Follow the instructions here https://www.igeeksblog.com/how-to-create-free-apple-developer-account/ to add your developer account to Xcode.
4. Give Cleo Engineering Lead your Apple developer account to add to the Apple development team.

⁠Install Aptible CLI

Ensure you have an Aptible account and your email has been confirmed.

$ brew cask install aptible

⁠Getting started

⁠Configuration.

ENV variables are used for configuration and in development mode dotenv is used. Application comes with .env.example file you can use as a base.

$ cp .env.example .env

If you used docker to start services your configuration is ready to go, if not you might need to adjust connection configuration to database and redis.

⁠If running Postgres locally (not through docker-compose up):

Create database user admin:

$ psql -c "CREATE USER admin WITH PASSWORD 'admin'; ALTER ROLE admin SUPERUSER;"

⁠Create database.

Unfortunately Django doesn't provide any tool to automatically create database so you will have to do it manually. The prefered name of the database is lucy as this is what .env.example file comes with, but you can use whatever you want.

$ createdb -h localhost --username admin lucy

Then follow the instructions here⁠ to update your local DB with staging data

Create superuser (used to log in on the Dashboard):

$ pipenv run python3 manage.py createsuperuser

Now you're ready to start the app:

$ pipenv run python3 manage.py runserver

⁠Useful commands

• pipenv run - run command from virtual environment
• pipenv shell - start shell with virtual environment loaded
• pipenv install - install packages specified in Pipfile
• pipenv lock - create or update lockfile
• pipenv graph - display dependency graph
• python3 manage.py runserver - start development server
• docker-compose up - start all services in foreground mode, if you pass -d flag it will run in background
• docker-compose stop - stop all services, data will be preserved
• docker-compose down - stop all services and remove data

⁠Quirks and other things to be aware of

Django's static assets support leaves a lot to be desired.

Common issue you can run into, is when changes introduced by you to stylesheets are not reflected in browser. When this happens it's a problem with browser's cache. You have to hard refresh (shift+cmd+r) the browser so it reloads all the static assets and not use cached versions.

It happens only in development mode. In production all styleshhets are compiled into one and fingerprinted, so every change generates totally new file.

⁠CircleCI

Cleo backend requires custom libraries such as Geospatial support to work correctly. For that reason we provide custom docker image for CircleCI continous integration.

The Dcokerfile to build this image is located in:

.circleci/images/Dockerfile

You will require to build new version of this image whenever Python or other libraries are upgraded. To do that go to that dir and execute:

docker build . -t cleolabs/python:3.7.1

And push it to Docker repository:

docker push cleolabs/python:3.7.1