Packet is used by CSH to facilitate the freshmen packet portion of our introductory member evaluation process. This is the second major iteration of packet on the web. The first version was Tal packet.
Requires Python 3.9 or newer.
To get the server working you'll just need the Python dependencies and some secrets. There will be some UI issues due to missing assets though. To solve that you'll want to set up the front end dependencies or download a copy of the current assets from prod.
Alternatively, you can set up a Docker container using Dockerfile
. This is what's used in prod so it's the most
reliable method.
Use pip3 install -r requirements.txt
to install the required python dependencies. A
venv is highly
recommended. To add new dependencies, add them to requirements.in
and run pip-compile requirements.in
to update
the main file.
If 1 or more of the packages fail to install the likely issue is missing header files for the libraries with native C
components. See the contents of Dockerfile
for the Linux packages that you'll need. On windows it's a bit more of a
pain. Try using WSL or finding a pre-compiled wheel from a
trustworthy source.
To build any of the frontend dependencies you're going to need node, npm, and yarn.
Make sure your system is also capable of building with Sass. To download all node dependencies run.
yarn install
Following the install, you should be able to run gulp
gulp production
If it doesn't work for some reason, you may have to globally install gulp through npm
npm install -g gulp
docker run --name packet-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres
After the container starts up, you should be able to connect with the connection string postgresql://postgres:mysecretpassword@localhost:5432/postgres
, which is the default connection string in config.env.py
.
Once the container is up, run the following to set up the database tables.
flask db upgrade
Packet supports 2 primary configuration methods:
config.env.py
for the expected names and default values.config.py
file in the root directory of the project and set variables to override the
values in config.env.py
.Both methods can be used at the same time, though Pyfile config will take priority over environment variables.
Required configuration values:
SQLALCHEMY_DATABASE_URI
- Must be set to a valid SQLAlchemy DB URI.
A dev database for the project is hosted by CSH. Contact a current maintainer of packet for the details.LDAP_BIND_DN
- Must point to a valid CSH account on LDAP. Use the form
uid={username},cn=users,cn=accounts,dc=csh,dc=rit,dc=edu
.LDAP_BIND_PASS
- The password for that CSH account.SECRET_KEY
- Use a sufficiently long random string here. The flask create-secret
command can generate a good one
for you.OIDC_CLIENT_SECRET
- Required to use CSH auth. Contact a current maintainer of packet for the details.To switch between OIDC realms you'll need to set the modify the following values:
OIDC_CLIENT_SECRET
- Unique to each realm. Again, contact a current maintainer of packet for the details.OIDC_ISSUER
- The OIDC issuer URL.REALM
- Set to "csh"
or "intro"
depending on the realm you want.By default OIDC_ISSUER
and REALM
are configured for the CSH members realm.
To run packet using the flask dev server use this command:
python3 wsgi.py
The Flask debug mode flag can be set using via the config system explained above.
Alternative you can run it through gunicorn using this command:
gunicorn -b :8000 packet:app --access-logfile -
Packet makes use of the Flask CLI for exposing functionality to devs and admins. This is primarily designed to be used locally with the target DB set via the server's config values.
To use the CLI just set the project up as normal and then run the flask
command in the project's root directory.
It'll automatically load up the app and show you a list of available commands. For more details on a particular command
use the help flag like this:
flask {command} --help
WARNING: Be sure to double check which DB you're pointed at when using one of the admin or DB commands.
All DB commands are from the Flask-Migrate
library and are used to configure DB migrations through Alembic. See their
docs here for details.
This project is configured to use Pylint and mypy. Commits will be pylinted and typechecked by GitHub actions and if the score drops your build will fail blocking you from merging. To make your life easier just run it before making a PR.
To run pylint and mypy use these commands:
pylint packet/routes packet
mypy --disable-error-code import --disable-error-code name-defined --disallow-untyped-defs --exclude routes packet
All python files should have a top-level docstring explaining the contents of the file and complex functions should have docstrings explaining any non-obvious portions. Functions should have type annotations.