Fenceless Grazing System API Server

This is the repository for the API server component of the Fenceless Grazing System. This server is written in Python using the Flask microframework, and uses the SQLAlchemy ORM to interact with the SQLite database.

Getting the Dependencies

The API server depends on several packages to operate properly, which will likely not be installed by default on your system. There are two ways to get the required dependencies: using Python's virtualenv (standard in the Python ecosystem), or using Nix (only if you are into that kind of thing).

Getting the Dependencies with virtualenv

First, create a virtual environment (this only has to be done once):

virtualenv venv

Once the virtual environment has been created, activate it using the following command:

source venv/bin/activate

This effectively creates an independent Python environment, into which you can install packages without affecting your entire system. You can now install the packages from the requirements.txt file:

pip install -r requirements.txt

With this, you should have all the necessary dependencies.

Getting the Dependencies with Nix

Below is the Nix expression I use daily to work on this application:

with import <nixpkgs> {};

mkShell {
    buildInputs = [ (python3.withPackages (ps: with ps; [ flask flask_sqlalchemy pyjwt bcrypt geopy pip ])) ];
}

Note that some packages (geopy in particular) are currently unstable; the expressions from stable Nixpkgs may not provide a working derivation. When using the nixpkgs-unstable, I have no such issues.

Setting Up

The application requires the DB_LOC environment variable to be set to indicate the location of the database that the server should use:

export DB_LOC=database.sqlite

Additionally, Flask uses the FLASK_APP environment variable to determine the entry point of a web application

# Here, fgs represents the fgs/ directory in the repository's root.
export FLASK_APP=fgs

Finally, on first run, you need to create the tables in the application's database. This can be done as follows:

flask shell
# Imports, among other things, the db variable, which is the handle for the SQLAlchemy ORM.
from fgs import *

# SQLAlchemy needs to be aware of the various tables in our database
from fgs.model import *

# Creates all tables
db.create_all()

# It also helps to set up a user and a couple of collars:
user = User(username='user', password='password')
collar1 = Collar(name='Sample Collar', active=True)
collar2 = Collar(name='Another Collar', active=True)

# To add the newly created objects to the database, use
# db.session.add and db.session.commit
db.session.add(user)
db.session.add(collar1)
db.session.add(collar2)
db.session.commit()

# You can now press Ctrl-D to exit the Flask shell. 

Once the database has been created, you can start the server with:

flask run

Next Steps

Once the server is up and running, consider setting up the app, which is able interact with this API server. Additionally, check out the cow description language if you want to generate mock data for the API server's database.