About

FRED (Flask + REact + Docker): An End-to-End Boilerplate for Full Stack Development

Demo: harrywang.me/fred

Tools and packages used in this project:

• Flask: a micro web framework written in Python
• React: a JavaScript library for building user interfaces
• Docker: a set of platform as a service products that uses OS-level virtualization to deliver software in packages called containers
• Postgres: a free and open-source relational database management system
• SQLAlchemy: an open-source SQL toolkit and object-relational mapper for Python
• Flask-RESTX: a Flask extension for building REST APIs
• PyTest: a Python testing framework
• Jest: a JavaScript testing framework
• Python Linting and Formatting: flake8, black, isort
• JS Linting and Formatting: ESLint and Prettier
• JSON Web Tokens (JWT) via flask-bcrypt and pyjwt
• Bulma: a free, open source, and modern CSS framework
• Fresh: a beautiful Bulma template by CSSNinja
• Illustrations from UnDraw.co
• Images from Unsplash
• Heroku: a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud.
• CircleCI: a continuous integration and delivery platform
• AWS

Data: I use the data scraped from http://quotes.toscrape.com/. Check out my tutorial A Minimalist End-to-End Scrapy Tutorial if you are interested in learning web scraping.

Special Thanks: many parts of this repo are based on the open-source code and related courses offered by Michael Herman from testdriven.io - highly recommended! Please show your support by buying the courses - I am not affiliated with testdriven.io - just really enjoyed the courses :).

Team

• Harry Wang
• Jinggang Zhuo

Prerequisites

I recommend the following materials, which can greatly help you understand the code in this repo.

• Flask and SQLAlchemy: The Flask Mega-Tutorial by Miguel Grinberg
• React: Intro to React and Step-by-Step Guide
• Docker and Docker Compose: Getting started with Docker and Get started with Docker Compose

Setup

You need to install the followings:

• Python 3
• Node.js
• Docker

Run

1. Clone the repo: git clone https://github.com/harrywang/fred.git
2. Switch to fred folder and run docker-compose up -d --build
3. Setup database and load data:

$ docker-compose exec backend python manage.py reset_db
$ docker-compose exec backend python manage.py load_data

4. Visit http://localhost:3007 to check the app (you can register a new user or use the sample testing user account username: test, email: [email protected], password: test)

5. Visit http://127.0.0.1:5001/docs/ to check API docs.

Other useful commands:

$ docker-compose stop # stop containers
$ docker-compose down # stop and remove containers
$ docker-compose down -v # stop and remove containers and volumes

If something does not work, you can try to use:

$ docker-compose down -v
$ docker-compose up -d --build

Other docker commands:

$ docker image ls # check images
$ docker system prune -a --volumes # delete everything

Tests

Run backend tests:

$ docker-compose exec backend python -m pytest "app/tests" -p no:warnings
$ docker-compose exec backend pytest "app/tests" -p no:warnings --cov="app"
$ docker-compose exec backend pytest "app/tests" -p no:warnings --cov="app" --cov-branch
$ docker-compose exec backend python -m pytest "app/tests" -p no:warnings --cov="app" --cov-branch --cov-report html
$ docker-compose exec backend python -m pytest "app/tests" -p no:warnings --cov="app" --cov-report html
$ docker-compose exec backend flake8 app
$ docker-compose exec backend black app
$ docker-compose exec backend /bin/sh -c "isort app/**/*.py"

Run frontend tests:

$ docker-compose exec frontend npm test
$ docker-compose exec frontend npm run prettier:check
$ docker-compose exec frontend npm run prettier:write
$ docker-compose exec frontend npm run lint

Access the database via psql:

$ docker-compose exec db psql -U postgres
# \c app_dev
# select * from user;
# select * from author;
# \q

SSH to containers:

$ docker-compose exec backend /bin/sh
$ docker-compose exec backend-db /bin/sh

Development Workflow

Some notes:

• If you add new API endpoints - don't forget to add them to services/nginx/default.conf

CircleCI

• add .circleci/config.yml
• add Docker Hub environment variables on CircleCI.com:

- Note that you have to use machine executor for docker-compose to work (set `machine: true`) - You have to change add `CI=true` to `package.json` such as `"test": "CI=true react-scripts test --env=jsdom"` to turn off the watch mode. Otherwise, CI testing step will never complete.

Deployment

REACT_APP_BACKEND_SERVICE_URL could be confusing and let me explain why it is necessary.

• First, all AJAX calls are using this variable (check App.js), such as:

axios.get(`${process.env.REACT_APP_BACKEND_SERVICE_URL}/users`)

• When we do local development, I hardcode this environment variable in docker-compose.yml: REACT_APP_BACKEND_SERVICE_URL=http://localhost:5001 file, we have the backend running at port 5000 and mapping 5001 to 5000 in the same file.

• When we build the production image for deployment, we have ENV REACT_APP_BACKEND_SERVICE_URL $REACT_APP_BACKEND_SERVICE_URL in the Dockerfile.deploy file - this ensures that we don't hardcode this and let the image pick up the value from the service provider (such as Heroku) when it starts - NOTE: whatever you set the value locally does not matter to the production image!!! As you can see in the deployment instruction, we actually don't set this environment variable in Heroku, which means the AJAX calls are sent to the default port 80.

• Having this variable then gives you the flexibility to use any port during testing, e.g., we set it to port 8007 when testing the production image locally.

• Check out the Heroku deployment instruction

• Check out the AWS deployment instruction