Step by Step Installation

Regular Setup

This option should be secondary to the Docker setup.

Pre-requisites:

• Python 3.x
• pip 9.0

If your developing with Windows, ¯\(ツ)/¯ Check out the Windows setup Doc

Step-by-Step Instructions

If you prefer to go through step-by-step instructions to understand what's going on, you're at the right place!

Clone the Repository and cd into it

$ git clone https://github.com/tko22/flask-boilerplate.git
$ cd flask-boilerplate

I would use docker to start a postgres database instead of downloading it on your computer. To do this install Docker and then create a volume and run the postgres 10 container.

docker run -e POSTGRES_USER=testusr -e POSTGRES_PASSWORD=password -e POSTGRES_DB=testdb -p 5432:5432 -v flask-app-db:/var/lib/postgresql/data postgres:10

Then, do a docker ps to see whether your database is running.

We will be using pipenv, the officially recommended Python packaging tool from Python. If prefer to use pip instead of pipenv, look below for instructions. Pipenv is very similar to npm and yarn in Javascript and it automatically creates/manages a virtualenv while adding/removing packages from your Pipfile. It also manages and autoloads environment variables and in general, helps developers setup a working environment.

First, install pipenv. If you are on MacOS, use homebrew:

brew install pipenv

If you're using Linux or Windows, I'd just use pip:

pip install --user pipenv

Then, install all the dependencies listed by the Pipfile and those listed under [dev-packages]:

pipenv install
pipenv install --dev
pipenv run python manage.py recreate_db

That's it! All your dependencies will be installed in your virtualenv. Virtualenv is a tool to create isolated Python environments, which will prevent dependency conflicts with your python projects.

To start your virtualenv, run:

pipenv shell

Now, any python command you run will be ran inside this virtual environment. You should get something that looks like this:

(flask-boilerplate-_rcP-Rlt) bash-3.2 $

To deactivate, type exit:

(flask-boilerplate-_rcP-Rlt) bash-3.2 $ exit

For more instructions, see the official documentation for pipenv.

Running Development Server

To run the server, make sure you are in the root directory. Then, startup the virtual environment and run the server:

$ pipenv shell  # startup virtual environment
(flask-boilerplate-_rcP-Rlt) bash-3.2$ python manage.py runserver

If you are using pipenv, you may also run commands without being inside your virtual environment:

$ pipenv run python manage.py runserver # pipenv run [command]

The API should be at http://127.0.0.1:5000/ for you to experience its beauty

Using postgres natively

If you prefer to do so, although I'd discourage this...

To install Postgres with Homebrew(postgresapp also works). If you are using linux, use your linux distributon's package manager to install postgres:

$ brew install postgresql
$ brew link postgresql

This should start your postgres server:

$ brew services start postgresql

To stop:

$ brew services stop postgresql

On a separate CLI, check whether you can access the database. Your postgres server must be on in order for this to work:

$ createdb
$ psql -h localhost
# \q

After installing Postgres, create a user(with name 'testusr' and password 'password') and a database called 'testdb' then grant privileges. We will do this in your CLI:

$ psql
# create user testusr with password 'password';
# create database testdb owner testusr encoding 'utf-8';
# GRANT ALL PRIVILEGES ON DATABASE testdb TO testusr;

Note: Please replace the user name and password and database name to what you want in your own application. You must change those configurations in config.py and in .env