Flask application to manage Labor Status Forms

Requirements

Python 3.7+

Packages (Ubuntu)

• python3-dev
• python3-pip
• python3-venv
• unixodbc-dev
• libffi-dev
• mysql-server

Getting Started With LSF in a devcontainer

1. If on Windows 10, make sure your Windows install is in developer mode so that core.symlinks will be set properly: https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development (requires admin privileges)
2. Set up an SSH agent with your GitHub SSH key. https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
3. Open repository directory in VSCode (either clone with VSCode or install git yourself and clone with git clone git@github.com:BCStudentSoftwareDevTeam/lsf.git)
4. Follow prompts to install Dev Container extension and open project in dev container
5. If everything completes without error, flask run! Otherwise, try rebuilding the container again.

Getting Started With LSF Manually (Linux or Mac OS)

1. Pull down the repo: git clone
2. Run source setup.sh
3. Ensure mysql is running. You may need to do sudo systemctl start mysqlor sudo /etc/init.d/mysql start.
4. If you have non-default root and application database credentials, match your MySQL configuration to the application config. You can either:
   • Update MySQL to use the database, username, and password in app/config/default.yml. OR
   • Copy the db configuration lines from app/config/default.yml and paste them into app/config/local-override.yml. Edit them to create custom database, username, and password configurations. They will need to match what is in your MySQL service.
5. In the database directory, run ./reset_database.sh
6. Run the app with flask run in the root directory

Using the Production database and real Tracy data

1. Set up your computer to access SQL Server databases: http://ssdt-documentation.berea.edu/en/database.
2. Ensure your database connection is working by running python db_test.py.
3. Check your secret_config.yml and make sure you have the necessary config items (check example_secret_config.yml)
4. Reset your database from the backup ./reset_database.sh from-backup.
5. Change your environment to staging. Before starting the application, run export FLASK_ENV=staging

Updating pip dependencies (imports)

1. Run pip freeze > requirements.txt to export all imports to a file. This file is used by setup.sh when the next user runs source setup.sh

Updating models

Use Peewee Migrator to update models: https://pypi.org/project/peewee-migrations/

1. Install: pip install peewee-migrations (included in setup.sh, so you shouldn't need this)
2. pem init
3. Add models to watch: e.g., pem add app.models.user.User
4. Watch the model for changes: pem watch
5. When done changing models, run the migrator to modify the db: 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 DBs in phpmyadmin and adding them again. Delete any lsf/TRACY migrations files or folders. Note: ** Do NOT delete .JSON OR .SH files**

Troubleshooting

1. If you can't clone the repository, make sure your SSH public key is added to your bitbucket profile.
2. Make sure that you are running source setup.sh and ./reset\_database.sh, in that order, without errors. Errors there should be resolved first.

Email Configuration

There are a couple of options to test email handling. By default, all emails will be logged to the slack channel #labor-emails in the bereacs workspace.

If you want to test with actual emails, use an email other than outlook to test email handler. This setup is specific to gmail, but should work with any other email that allows you to make app passwords

1. Set up two factor authentication on your Gmail (Security Settings)
2. Create an App Password through your Gmail. This 16 character password can only be viewed once, so make sure to save it. (NOTE: You won't have the option to create an app password unless step one is completed)
3. Inside of your secret_config.yaml file set the MAIL_USERNAME and MAIL_DEFAULT_SENDER as your Gmail, set the MAIL_PASSWORD as your new app password as, and set ALWAYS_SEND_MAIL as True. If you want emails to go to their real recipients, remove MAIL_OVERRIDE_ALL from your config or set it to "".
4. For testing purposes, change the email of the student and supervisor to match another email that can receive your test emails (or you can use MAIL_OVERRIDE_ALL to send everything to the address specified.