2021-03-06 15:28:15 +00:00
|
|
|
Thanks for taking the time to contribute! 🎉👍
|
|
|
|
|
|
|
|
The project uses Flask and requires Python3.7+.
|
2021-03-06 14:55:18 +00:00
|
|
|
|
|
|
|
### Run code locally
|
|
|
|
|
|
|
|
The project uses
|
|
|
|
- Python 3.7+ and [poetry](https://python-poetry.org/) to manage dependencies
|
|
|
|
- Node v10 for front-end.
|
|
|
|
|
|
|
|
First, install all dependencies by running the following command.
|
|
|
|
Feel free to use `virtualenv` or similar tools to isolate development environment.
|
|
|
|
|
|
|
|
```bash
|
|
|
|
poetry install
|
|
|
|
```
|
|
|
|
|
|
|
|
On Mac, sometimes you might need to install some other packages like
|
|
|
|
|
|
|
|
```bash
|
|
|
|
brew install pkg-config libffi openssl postgresql
|
|
|
|
```
|
|
|
|
|
|
|
|
You also need to install `gpg`, on Mac it can be done with:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
brew install gnupg
|
|
|
|
```
|
|
|
|
|
|
|
|
Then make sure all tests pass
|
|
|
|
|
|
|
|
```bash
|
|
|
|
pytest
|
|
|
|
```
|
|
|
|
|
|
|
|
Install npm packages
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cd static && npm install
|
|
|
|
```
|
|
|
|
|
|
|
|
To run the code locally, please create a local setting file based on `example.env`:
|
|
|
|
|
|
|
|
```
|
|
|
|
cp example.env .env
|
|
|
|
```
|
|
|
|
|
2021-03-06 15:28:15 +00:00
|
|
|
To run the server:
|
2021-03-06 14:55:18 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
python3 server.py
|
|
|
|
```
|
|
|
|
|
|
|
|
then open http://localhost:7777, you should be able to login with the following account
|
|
|
|
|
|
|
|
```
|
|
|
|
john@wick.com / password
|
|
|
|
```
|
|
|
|
|
2021-03-06 15:28:15 +00:00
|
|
|
You might need to change the `.env` file for developing certain features. This file is ignored by git.
|
|
|
|
|
2021-03-06 14:55:18 +00:00
|
|
|
### Database migration
|
|
|
|
|
|
|
|
The database migration is handled by `alembic`
|
|
|
|
|
|
|
|
Whenever the model changes, a new migration has to be created.
|
|
|
|
|
|
|
|
If you have Docker installed, you can create the migration by the following script:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
sh new_migration.sh
|
|
|
|
```
|
|
|
|
|
|
|
|
Make sure to review the migration script before committing it.
|
|
|
|
Sometimes (very rarely though), the automatically generated script can be incorrect.
|
|
|
|
|
|
|
|
We cannot use the local database to generate migration script as the local database doesn't use migration.
|
|
|
|
It is created via `db.create_all()` (cf `fake_data()` method). This is convenient for development and
|
|
|
|
unit tests as we don't have to wait for the migration.
|
|
|
|
|
|
|
|
### Code structure
|
|
|
|
|
|
|
|
The repo consists of the three following entry points:
|
|
|
|
|
|
|
|
- wsgi.py and server.py: the webapp.
|
|
|
|
- email_handler.py: the email handler.
|
|
|
|
- cron.py: the cronjob.
|
|
|
|
|
|
|
|
Here are the small sum-ups of the directory structures and their roles:
|
|
|
|
|
|
|
|
- app/: main Flask app. It is structured into different packages representing different features like oauth, api, dashboard, etc.
|
|
|
|
- local_data/: contains files to facilitate the local development. They are replaced during the deployment.
|
|
|
|
- migrations/: generated by flask-migrate. Edit these files will be only edited when you spot (very rare) errors on the database migration files.
|
|
|
|
- static/: files available at `/static` url.
|
|
|
|
- templates/: contains both html and email templates.
|
|
|
|
- tests/: tests. We don't really distinguish unit, functional or integration test. A test is simply here to make sure a feature works correctly.
|
|
|
|
|
|
|
|
The code is formatted using https://github.com/psf/black, to format the code, simply run
|
|
|
|
|
|
|
|
```
|
|
|
|
black .
|
|
|
|
```
|
|
|
|
|
|
|
|
### Test sending email
|
|
|
|
|
|
|
|
[swaks](http://www.jetmore.org/john/code/swaks/) is used for sending test emails to the `email_handler`.
|
|
|
|
|
2021-03-06 15:28:15 +00:00
|
|
|
[mailcatcher](https://github.com/sj26/mailcatcher) or [MailHog](https://github.com/mailhog/MailHog) can be used as a MTA to receive emails.
|
2021-03-06 14:55:18 +00:00
|
|
|
|
2021-03-06 15:28:15 +00:00
|
|
|
Here's how set up the email handler:
|
2021-03-06 14:55:18 +00:00
|
|
|
|
2021-03-06 15:28:15 +00:00
|
|
|
1) run mailcatcher or MailHog
|
2021-03-06 14:55:18 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
mailcatcher
|
|
|
|
```
|
|
|
|
|
|
|
|
2) Make sure to set the following variables in the `.env` file
|
|
|
|
|
|
|
|
```
|
2021-03-06 15:28:15 +00:00
|
|
|
# comment out this variable
|
|
|
|
# NOT_SEND_EMAIL=true
|
|
|
|
|
|
|
|
# So the emails will be sent to mailcatcher/MailHog
|
2021-03-06 14:55:18 +00:00
|
|
|
POSTFIX_SERVER=localhost
|
|
|
|
POSTFIX_PORT=1025
|
|
|
|
```
|
|
|
|
|
|
|
|
3) Run email_handler
|
|
|
|
|
|
|
|
```bash
|
|
|
|
python email_handler.py
|
|
|
|
```
|
|
|
|
|
|
|
|
4) Send a test email
|
|
|
|
|
|
|
|
```bash
|
2021-03-06 15:28:15 +00:00
|
|
|
swaks --to e1@sl.local --from hey@google.com --server 127.0.0.1:20381
|
2021-03-06 14:55:18 +00:00
|
|
|
```
|
|
|
|
|
2021-03-06 15:30:41 +00:00
|
|
|
Now open http://localhost:1080/ (or http://localhost:1080/ for MailHog), you should see the forwarded email.
|