capsul-flask/README.md

# capsulflask

Python Flask web application for capsul.org


## how to run locally

Ensure you have the pre-requisites for the psycopg2 Postgres database adapter package

```
sudo apt-get install python3-dev libpq-dev
pg_config --version
```

Create python virtual environment and install packages

```
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip wheel
pip install -r requirements.txt
```

Run an instance of Postgres (I used docker for this, you can use whatever you want, point is its listening on localhost:5432)

```
docker run --rm -it -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres
```

Modify the default email settings

```
nano capsulflask/__init__.py
```

Run the app 

```
FLASK_APP=capsulflask flask run
```

Run the app in gunicorn locally
```
pip install gunicorn
.venv/bin/gunicorn --bind 127.0.0.1:5000 capsulflask:app
```

## postgres database schema management

capsulflask has a concept of a schema version. When the application starts, it will query the database for a table named
`schemaversion` that has one row and one column (`version`). If the `version` it finds is not equal to the `desiredSchemaVersion` variable set in `db.py`, it will run  migration scripts from the `schema_migrations` folder one by one until the `schemaversion` table shows the correct version.

For example, the script named `02_up_xyz.sql` should contain code that migrates the database from schema version 1 to schema version 2. Likewise, the script `02_down_xyz.sql` should contain code that migrates from schema version 2 back to schema version 1.

**IMPORTANT: if you need to make changes to the schema, make a NEW schema version. DO NOT EDIT the existing schema versions.**

In general, for safety, schema version upgrades should not delete data. Schema version downgrades will simply throw an error and exit for now.