174 lines
5.9 KiB
Raw Normal View History

2021-07-24 17:35:09 -04:00
# pyceo
2021-08-19 22:29:25 -04:00
[![Build Status](](
2021-08-19 22:24:55 -04:00
2021-08-19 21:41:50 -04:00
CEO (**C**SC **E**lectronic **O**ffice) is the tool used by CSC to manage
club accounts and memberships. See []( for an
overview of its architecture.
2021-07-24 17:35:09 -04:00
## Development
First, make sure that you have installed the
[syscom dev environment](
This will setup all of the services needed for ceo to work. You should clone
2021-08-19 21:41:50 -04:00
this repo in the phosphoric-acid container under ctdalek's home directory; you
will then be able to access it from any container thanks to NFS.
2021-07-24 17:35:09 -04:00
2021-08-19 21:41:50 -04:00
### Environment setup
Once you have the dev environment setup, there are a few more steps you'll
need to do for ceo.
#### Kerberos principals
First, you'll need `ceod/<hostname>` principals for each of phosphoric-acid,
coffee and mail. (coffee is taking over the role of caffeine for the DB
endpoints). For example, in the phosphoric-acid container:
kadmin -p sysadmin/admin
<password is krb5>
addprinc -randkey ceod/phosphoric-acid.csclub.internal
ktadd ceod/phosphoric-acid.csclub.internal
Do this for coffee and mail as well. You need to actually be in the
appropriate container when running these commands, since the credentials
are being added to the local keytab.
On phosphoric-acid, you will additionally need to create a principal
called `ceod/admin` (remember to addprinc **and** ktadd).
#### Database
**Note**: The instructions below apply to the dev environment only; in
production, the DB superusers should be restricted to the host where
the DB is running.
Attach to the coffee container, run `mysql`, and run the following:
(In prod, the superuser should have '@localhost' appended to its name.)
Now open /etc/mysql/mariadb.conf.d/50-server.cnf and comment out the following line:
bind-address =
Then restart MariaDB:
systemctl restart mariadb
Install PostgreSQL in the container:
apt install -y postgresql
Modify the superuser `postgres` for password authentication and restrict new users:
su postgres
ALTER USER postgres WITH PASSWORD 'postgres';
GRANT ALL ON SCHEMA public TO postgres;
Create a new `pg_hba.conf`:
cd /etc/postgresql/<version>/<branch>/
mv pg_hba.conf pg_hba.conf.old
# new pg_hba.conf
local all postgres peer
host all postgres md5
local all all peer
host all all localhost md5
local sameuser all peer
host sameuser all md5
**Warning**: in prod, the postgres user should only be allowed to connect locally,
so the relevant snippet in pg_hba.conf should look something like
local all postgres md5
host all postgres localhost md5
host all postgres reject
host all postgres ::/0 reject
Add the following to postgresql.conf:
listen_addresses = '*'
Now restart PostgreSQL:
systemctl restart postgresql
**In prod**, users can login remotely but superusers (`postgres` and `mysql`) are only
allowed to login from the database host.
2021-08-19 21:41:50 -04:00
2021-08-22 01:44:41 -04:00
#### Mailman
You should create the following mailing lists from the mail container:
/opt/mailman3/bin/mailman create syscom@csclub.internal
/opt/mailman3/bin/mailman create syscom-alerts@csclub.internal
/opt/mailman3/bin/mailman create exec@csclub.internal
/opt/mailman3/bin/mailman create ceo@csclub.internal
for instructions on how to access the Mailman UI from your browser.
If you want to actually see the archived messages, you'll
need to tweak the settings for each list from the UI so that non-member
messages get accepted (by default they get held).
2021-08-19 21:41:50 -04:00
#### Dependencies
2021-07-24 17:35:09 -04:00
Next, install and activate a virtualenv:
sudo apt install libkrb5-dev libpq-dev python3-dev
2021-07-24 17:35:09 -04:00
python3 -m venv venv
. venv/bin/activate
pip install -r requirements.txt
pip install -r dev-requirements.txt
## Running the application
2021-08-19 21:41:50 -04:00
ceod is a distributed application, with instances on different hosts offering
different services.
2021-07-24 17:35:09 -04:00
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).
2021-08-19 21:41:50 -04:00
To run ceod on a single host (as root, since the app needs to read the keytab):
2021-07-24 17:35:09 -04:00
export FLASK_APP=ceod.api
export FLASK_ENV=development
flask run -h -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 ``, then
restart the app.
## Interacting with the application
2021-07-24 17:35:09 -04:00
The client part of ceo hasn't been written yet, so we'll use curl to
interact with ceod for now.
ceod uses [SPNEGO]( for authentication,
and TLS for confidentiality and integrity. In development mode, TLS can be
2021-07-24 17:35:09 -04:00
First, make sure that your version of curl has been compiled with SPNEGO
curl -V
Your should see 'SPNEGO' in the 'Features' section.
Here's an example of making a request to an endpoint which writes to LDAP:
2021-07-24 17:35:09 -04:00
# Get a Kerberos TGT first
# Make the request
2021-08-25 22:26:56 -04:00
curl --negotiate -u : --service-name ceod --delegation always \
-d '{"uid":"test_1","cn":"Test One","program":"Math","terms":["s2021"]}' \
-X POST http://phosphoric-acid:9987/api/members
2021-07-24 17:35:09 -04:00