This application showcases a fully responsive PWA website with some useful features that many applications require e.g. user authentication, logging, privacy statements, SEO ready etc.
It's built entirely in Python and Flask. It runs easily on AWS: guidance on installing on AWS Elastic Beanstalk is provided.
It will also run on other cloud providers.
It's been designed as a template so you can take a copy of this repo and customize to your requirements.
I started to build a Flask based responsive website. I spent a lot of time searching for the best way to run a fully responsive PWA website built in Flask running on AWS. I could not find a complete working example to use as a starting point. I've decided to create this repo to showcase the way I did this so others can benefit from my learning.
I also spent a lot of time building some of the "compliance/hygiene" type pages like Contact Us, Privacy Policy etc. that every website requires. I thought it would be useful to have a working Flask application that has these plumbed in and ready for customization. This means less time on those type of features and more on the value-add product differentiators you really want to be working on.
Another motivation is I believe in using SaaS services and not re-inventing the wheel especially when it comes to super-sensitive topics like User Authentication and Sign-Up. There is no need to be building yet-another-authentication piece of code when you can trust companies like Auth0 to do this. Far better to plug into SaaS offerings like Auth0 that provide commodity services so you can once again focus on the value-adds.
Furthermore, it's not only features that you need to care about. It's also SEO, tracking product analytics etc. This is why I've also added the use of Google Analytics tracking and various tags/best practice to assist with SEO so people actually find your site.
And finally...... good engineering practices are a must. CI/CD and code quality are critical. Why spend ages trying to construct a pipeline that builds, tests and deploys the application when you can re-use an existing one. Learn how to use tools such as CircleCI, SonarCloud and Snyk to help improve your application. This sample app shows some of these tools in use.
The application is fully working.
Check it out by generating a copy of the repo and run it locally.
Note that whilst this app runs on AWS, this application will work on other cloud platforms of your choice. It has Docker and docker-compose files available that can be utilised to run on other platforms.
It's built in Python leveraging the Flask framework. I've been using Python 3.7.7.
It requires a database backend. I've tested it under MySQL. Database access is performed via SQLAlchemy so theoretically other databases should work providing the relevant driver is installed.
The front-end uses the Bootstrap framework in order to provide a responsive UI. It works on mobile browsers as well as traditional Chrome, Safari and Brave on the desktop. FontAwesome is also used to provide icons.
The Auth0 website is used for authentication. I use the Python Authlib package to assist with the authentication.
Google Analytics tracking is supported in all of the HTML pages.
It is a fully PWA compliant application so can be readily installed on Android and iOS devices. Lighthouse in the Chrome DevTools has been used to test the compliance of the application.
The requirements.txt file contains the dependent python packages to be installed.
This app contains the following features:
- Use of Bootstrap and FontAwesome to produce a fully responsive, good-looking website.
- A homepage and navbar built from Bootstrap
- Static pages required by many sites (FAQ, disclaimer, cookie policy, privacy policy)
- Displays a use of cookies banner that must be clicked to acknowledge the use of cookies
- Contact Us page showcasing how to use AWS S3 to store the user submitted data
- Sign-up/Log-in/Log-out using Auth0 as the authentication provider
- A fully responsive PWA application that runs as well on the desktop as it does on a mobile device
- Database access via SQLAlchemy so agnostic to underlying database used
- Incorporates Google analytics tracking
- Use of a Content Distribution Network (CDN) to serve the static content
- Pages contain the metadata required by search engines
- Metadata files required for PWA applications (manifest.json, service-worker.js, offline.html)
- Robust server-side error logging
- Showcases the use of CircleCI for a full CI/CD pipeline that runs automated tests and will deploy to AWS
It's a standard Flask app with a database backend. To install and run locally:
It's been tested with Python 3.7.7. It should work with any versions of Python >= 3.7.
This repo has been marked as a template. This means you can easily create your own copy as a starting point.
Click generate to generate your own copy of this repo.
Once you've generated your own copy of the repo, you will need to clone this repo onto your local machine.
Inside the directory where you wish to store the code enter:
git clone=<yourrepo>
Change directories into the directory containing your copy of the source code.
You need to create a virtual environment inside this directory.
python -m venv .venv
now activate this virtual environment
source ./.venv/bin/activate
install the requirements into this virtual environment
pip install -r requirements.txt
Two initial environment variables are required to launch the app
export FLASK_APP=my_app
export FLASK_CONFIG=development
The logging configuration file log_config.yaml contains the default configuration for the logger.
It logs messages to a log file called my_app.log at /tmp/my_app.log. This may not be suitable for your environment so change the value in this file.
A database is required. It will default to sqlite which is installed by default on many OS's.
If you have a database, update the environment variable that stores the connection string. Otherwise, it will default to a local sqlite one which is fine for development.
export DEV_DATABASE_URL=<YOUR DATABASE CONNECTION STRING>
If you have a database, use SQLALchemy and Alembic to set-up this database with the required tables.
flask db upgrade
You can now run the app
flask run
You should see a statement on the command line indicating the app is now ready at localhost:5000
Open up a browser to http://localhost:5000. Click around. Not all functionality will be working just yet as you need to register with some providers
The app uses Auth0 as its user authentication provider. You need to register for a free account with Auth0. Follow the guidance here to not only set-up your free account but also configure your tenant.
The wiki article Authentication describes the Auth0 setup in further details along with an explanation of how the app has been coded to use Auth0.
The important data required, once you have registered and have a tenant, is the CLIENT_ID, SECRET, DOMAIN. Flask needs these set-up as environment variables. Execute the following
export AUTH0_CLIENT_ID=<YOUR_CLIENT_ID>
export AUTH0_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
export AUTH0_CLIENT_DOMAIN=<YOUR_DOMAIN>
If you restart the application with flask run, the sign-up, log-in and log-out links will now work.
If you have a web-domain and wish to use Google Analytics for this Flask app, then you will need to register with Google. Follow the guidance on the Google Analytics site.
Once you've done this, set-up the relevant environment variable
export GA_CODE=<YOUR_GOOGLE_TAG>
To fully use the contact-us page, you will need an AWS S3 bucket. Once you have one set-up, the following environment variables:
export CONTACT_US_FORMAT=S3
export S3_BUCKET=<NAME_OF_BUCKET
If you'd like to use a CDN to serve the static content then register and set-this up. Once you have the URL for the CDN then you need to let Flask know.
export CDN_DOMAIN=<YOUR_CDN_DOMAIN>
You will need to ensure all of the content (files and subfolders) inside the static folder is deployed to your CDN so it is accessible as https://<YOUR_CDN_DOMAIN/static/...
If you've followed the previous steps then you will have a fully running Flask instance demonstrating some essential features.
- The Flask app will be using Auth0 to manage user authentication and sign-ups.
- It will serve the static content from the CDN so end users get better page load times.
- Google Analytics will be tracking usage of your site so you can start to see visitor numbers, pages accessed etc.
- You're all set for customer engagement via the Contact Us page.
- It is a PWA so can easily be used and installed on mobile devices without requiring the relevant app store
- Basic, compliance type features are readily available which you can customize for your own use.
You can use the Dockerfile and docker-compose file to launch the Flask app in a container connected to MySQl running in a container.
Make sure Docker is installed and running locally and then enter:
docker-compose build
followed by
docker-compose up
Follow the instructions in the previous section for setting up Auth0, Google Analytics, AWS S3 bucket and your CDN.
The environment variables will need to be set-up locally within your shell as the docker-compose command passes the local environment variables to the container. See docker-compose.
This application will readily run in AWS and, as a bonus, on the free tier. I've used:
- Elastic Beanstalk to run the Flask application
- The Flask applications connects to RMS with a MySQL database
- S3 to store the Contact Us queries as json files
- Route 53 to route requests to a load-balancer in front of Elastic Beanstalk
- Cloudfront as a CDN to serve the application's static files (images, css, js) from a dedicated S3 Bucket
CircleCI is used to automatically deploy the application to Elastic Beanstalk and the static files to S3.
Running on AWS describes the AWS set-up required to run the Flask app on the AWS Elastic Beanstalk PaaS.
It can be deployed to other cloud providers as it is a simple Flask app.
The tests folder contains all of the application tests. These use the pytest framework. They test the database, views, business logic and the UI.
Selenium is used in headless mode to test the UI. Chromedriver will need to be installed.
Prior to running the tests, you will need to ensure the TEST_DATABASE_URL environment variable is set. You could either test against a simple sqllite database in which case set the variable as follows
export TEST_DATABASE_URL=sqlite:///test_app.db
or if you have a MySQL or other database available then enter
export TEST_DATABASE_URL=<connection string>
or if you run docker-compose up --build to run the app then you can connect to the mysql database server running in the container as
export TEST_DATABASE_URL=mysql+pymysql://root:hello@localhost:3308/test?charset=utf8mb4
To run the tests execute Make test on the command line.
The Lighthouse component of Google Chrome Dev Tools has been heavily used to ensure the application is SEO ready and fully PWA compliant.
I've leveraged CircleCI for Continuous Integration and Continuous Deployment. Tests are automatically run the against a MySQL database. Builds on master are automatically deployed when all tests pass successfully.
Check out the config file and the CircleCI overview for further details on using CircleCI.
Take a look at the project wiki for further guidance on using this template as a starting point for your own Flask based applications.
Take this code as is and alter to better suit your needs.
- You can add new imagery and styles. Alter the files in the static folder
- Change the templates
- Change the code
- Update the meta data in the base template to better support your site
Feedback and contributions are welcome. Checkout the code of conduct and contributor guidelines.
- The issue tracker contains the proposed enhancements and bug fixes.
This is licensed under a MIT licence.