add README

README.md

@@ -0,0 +1,62 @@
+# pyceo
+work in progress
+
+## Development
+First, make sure that you have installed the
+[syscom dev environment](https://git.uwaterloo.ca/csc/syscom-dev-environment).
+This will setup all of the services needed for ceo to work. You should clone
+this repo in one of the dev environment containers.
+
+Next, install and activate a virtualenv:
+```sh
+python3 -m venv venv
+. venv/bin/activate
+pip install -r requirements.txt
+pip install -r dev-requirements.txt
+```
+
+### Running the application
+ceod is essentially a distributed application, with instances on different
+hosts offering different services. For example, the ceod instance on mail
+offers a service to subscribe people to mailing lists, and
+the ceod instance on phosphoric-acid offers a service to create new members.
+Therefore, you will need to run ceod on multiple hosts. Currently, those are
+phosphoric-acid, mail and caffeine (in the dev environment, caffeine is
+replaced by coffee).
+
+To run ceod on a single host:
+```sh
+export FLASK_APP=ceod.api
+export FLASK_ENV=development
+flask run -h 0.0.0.0 -p 9987
+```
+
+Sometimes changes you make in the source code don't show up while Flask
+is running. Stop the flask app (Ctrl-C), run `clear_cache.sh`, then
+restart the app.
+
+### Interacting with the application
+The client part of ceo hasn't been written yet, so we'll use curl to
+interact with ceod for now.
+
+ceod uses [SPNEGO](https://en.wikipedia.org/wiki/SPNEGO) for authentication,
+and TLS for confidentiality and integrity. In development mode, TLS can be
+disabled.
+First, make sure that your version of curl has been compiled with SPNEGO
+support:
+```sh
+curl -V
+```
+Your should see 'SPNEGO' in the 'Features' section.
+
+Here's an example of using curl with SPNEGO:
+```sh
+# Get a Kerberos TGT first
+kinit
+curl --negotiate -u : --service-name ceod http://mail:9987/api/mailman/csc-general/ctdalek
+```
+
+Not all endpoints are SPNEGO-protected, e.g. to get info for a member:
+```sh
+curl http://phosphoric-acid:9987/api/members/ctdalek
+```

clear_cache.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+find ceo* -type d -name __pycache__ -execdir rm -r '{}' \;

dev-requirements.txt

@@ -0,0 +1,3 @@
+flake8==3.9.2
+setuptools==40.8.0
+wheel==0.36.2

requirements.txt

@@ -0,0 +1,9 @@
+Flask==2.0.1
+Flask-Kerberos==1.0.4
+gssapi==1.6.14
+Jinja2==3.0.1
+python-ldap==3.3.1
+requests==2.26.0
+requests-gssapi==1.2.3
+zope.component==5.0.1
+zope.interface==5.4.0