Bookish

1. Fork this repo

   • Click Fork in the top-right of the page - this will create a copy of this repo in your own GitHub account

2. Clone (download) the repo

   • Go to your newly-created fork of the repo (on GitHub).
   • Click Clone or download (the green button on the right).
   • Make sure the page says Clone with SSH (rather than Clone with HTTPS).
   • Open your git client (e.g. GitKraken) and use this link to clone the repo.
     Your trainer will able to help you with this.

3. "Cloning the repo" will create a folder on your computer with the files from this repo.
   Open this folder in Visual Studio Code.

4. Open a command-prompt in this same folder.
   Your trainer can show you how to do this, if you need any help.

5. Run this command to set up the necessary dependencies:
   poetry install

6. Follow the instructions in the section Setting up Postgres below to ensure that the database is ready for use. (You'll notice that your .env file contains POSTGRES config variables. The instructions below setup a user to match that config, with the right permissions to create the database when the app runs.)

7. Run this command to run your code:
   poetry run flask run

Setting up Postgres

Before you run the app you will need to make sure you've got Postgres installed and a database set up by following the instructions below.

Install Postgres

1. Download and install the PostgreSQL server software if you haven't already.

2. Open the Windows Start menu and search for "pgAdmin". When you start "pgAdmin" for the first time, you'll be asked to set a master password.

Set up Bookish user

1. Inside your PostgreSQL server in pgAdmin, right-click on Login/Group Roles and create a new Login/Group Role with the name bookish (in the General tab), the password bookish (in the Definition tab) and the ability to log in and create databases (in the Privileges tab).

2. Click Save to create the user.

Set up Bookish database

1. Inside your PostgreSQL server in pgAdmin, right-click on Databases and create a new Database with the name bookish and the owner bookish (both in the General tab).

2. Click Save to create the database.

Main dependencies

• The overall application framework is Flask, with routing setup in app/__init.py and page templates under templates/.

• SQL Alchemy is the ORM (Object-Relational Mapper) that provides object-based interaction with the database.

• Migrations (database schema changes) are implemented with Alembic - see below.

Migrations

Your migrations will run automatically at run-time to update your database with tables and data.

Creating new tables in your database

If you add a new model in the models directory, it's likely you'll want this to create a table in your database too! If you follow the steps below, your table should be created automatically on app start up (i.e. when you run poetry run flask run):

1. Add your model to models, for example models/example.py would include class Example(db.Model): ... which would in turn create the table example.
   • It's important to note here that your new class must extend db.Model
2. Add your new file to the imports in migrations/env.py on line 35.

Migration troubleshooting

There are known limitations to Alembic's autogenerated migrations, so if you're having trouble make sure you check the docs linked above as a first stop.