Add README

README.md

@@ -0,0 +1,113 @@
+# 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):
+
+```Bash
+virtualenv venv
+```
+
+Once the virtual environment has been created, activate it using the
+following command:
+
+```Bash
+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:
+
+```Bash
+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:
+
+```Nix
+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:
+
+```Bash
+export DB_LOC=database.sqlite
+```
+
+Additionally, Flask uses the `FLASK_APP` environment variable to determine the entry point
+of a web application
+
+```Bash
+# 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:
+
+```Python
+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:
+
+```Bash
+flask run
+```
+
+## Next Steps
+Once the server is up and running, consider setting up the
+[app](https://dev.danilafe.com/CS-46X/app), which is able
+interact with this API server. Additionally, check out the
+[cow description language](https://dev.danilafe.com/CS-46X/cdl)
+if you want to generate mock data for the API server's database.