Before engaging with our community, you are expected to understand and abide by our code of conduct.
Required local packages (Ubuntu)
NOTE: You must install MySQL and know the root password to continue.
git clone <URL>
.sudo systemctl start mysql
.
UTE
.app/config/default.yaml
to match your application parameters.app/config/local_override.yaml
for any local environment variables, such as username/passwords for the database. source install.sh
. flask run
in the root directory.cd
to the database
directory. source reset_database.sh
.flask run
. Test should be added in tests/code/
, logically grouped into files named test_EXAMPLE.py
. You can run tests individually with pytest
, or run the entire suite with tests/run_tests.sh
. The most common usage will be to run the non-ui tests continually by running tests/monitor.sh no-ui
from the root directory of the repo. Where possible, use TDD and write your test before the code that makes it pass. Follow the Fail - Implement - Pass cycle.
pip freeze > requirements.txt
. This file is used by setup.sh when the next user runs source setup.sh
to ensure they have the correct Python dependencies.
NOTE: watchdog
gets added by doing this step. Remove it after running the freeze command, as it breaks the setup.sh scriptThe application relies on a few databases:
The main database uses MySQL as the database engine, and Peewee ORM to abstract the database in code. If the main database schema needs to change, you must update the models inside app/models
. Then, use Peewee Migrator to update the models in the MySQL database automagically: https://pypi.org/project/peewee-migrations/
pip install peewee-migrations
(included in the virtual environment on install, so you shouldn't need to do this)pem init
pem add app.models.user.User
)pem watch
pem migrate
NOTE: You don't need to watch the files before you begin making changes. The watch will compare the db to your model file and make any changes that are inconsistent.
Additional helpful commands:
List active migrations: pem list
Show SQL generated by changes to the model: pem show
If encountering issues, try dropping your databases and adding them again. NOTE: This will remove any data in the database, so do NOT do this in a production environment.
Delete any lsf/TRACY migrations files or folders. Note: Do NOT delete .JSON OR .SH files
Unlike the main database, which uses MySQL, the Tracy database can use either MySQL (if you are installing the database yourself, i.e., USE_TRACY: 0
in a config file) or Microsoft's SQL Server (if the database is being provided by the folks at Tracy, i.e., USE_TRACY: 1
in a config file). To facilitate easier development, a Tracy class was created to access the database, regardless of the provider, leveraging SQAlchemy. It is recommended that any changes needed to the Tracy database are made to the models inside app/models/Tracy
AND in the Tracy class inside app/logic/tracy.py
.
NOTE: Peewee is used to abstract the main database, and SQAlchemy is used to abstract the Tracy database (regardless of the provider).
The application currently supports Shibboleth as the auth provider. To use it, set USE_SHIBBOLETH: 1
in local_override.yaml
. If set to 0, a local auth provider will be used (i.e., Flask login).
FIXME: Flask login is not yet implemented as a local provider.
Banner records are required at some institutions. To turn on this feature, set USE_BANNER: 1
and provide the appropriate credentials in local_override.yaml
.
There are a couple of options to test email handling. By default, all emails are suppressed by the flag USE_EMAILER: 0
in default.yaml
. Setting this to 1 and providing credentials for an SMTP provider will enable emails to be sent.
If you want to test with actual emails, use an email other than outlook to test the email handler. This setup is specific to Gmail, but should work with any other email that allows you to make app passwords. These settings are stored in default.yaml
and can be overridden in local_override.yaml
.
local_override.yaml
file set the MAIL_USERNAME and MAIL_DEFAULT_SENDER as your Gmail, set the MAIL_PASSWORD as your new app password, and set USE_EMAILER: 1
. If you want emails to go to their real recipients, remove MAIL_OVERRIDE_ALL from your config or set it to "".python db_test.py
../reset_database.sh from-backup
.staging
. Before starting the application, run export FLASK_ENV=staging
(FIXME: should this be ENV=staging
?)source install.sh
. source setup.sh
and ./reset\_database.sh
, in that order, without errors. Errors there should be resolved first.