docker-flask-example

An example Flask + Docker app

You could use this example app as a base for your new project or as a guide to Dockerize your existing Flask app.

The example app is minimal but it wires up a number of things you might use in a real world Flask app, but at the same time it's not loaded up with a million personal opinions.

For the Docker bits, everything included is an accumulation of Docker best practices based on building and deploying dozens of assorted Dockerized web apps since late 2014.

This app is using Flask 3.1.3 and Python 3.14.7. The screenshot shows X.X.X since they get updated regularly:

Table of contents

• Tech stack
• Notable opinions and extensions
• Running this app
• Files of interest
  • .env
  • run
• Running a script to automate renaming the project
• Updating dependencies
• See a way to improve something?
• Additional resources
  • Learn more about Docker and Flask
  • Deploy to production
• About the author

Tech stack

If you don't like some of these choices that's no problem, you can swap them out for something else on your own.

Back-end

• PostgreSQL
• SQLAlchemy
• Redis
• Celery

Front-end

• esbuild
• TailwindCSS
• Heroicons

But what about JavaScript?!

Picking a JS library is a very app specific decision because it depends on which library you like and it also depends on if your app is going to be mostly Jinja templates with sprinkles of JS or an API back-end.

This isn't an exhaustive list but here's a few reasonable choices depending on how you're building your app:

On the bright side with esbuild being set up you can use any (or none) of these solutions very easily. You could follow a specific library's installation guides to get up and running in no time.

Personally I'm going to be using Hotwire Turbo + Stimulus in most newer projects.

Notable opinions and extensions

Flask is a very unopinionated framework but I find in most apps I'm adding the same things over and over. Here's a few (but not all) note worthy additions and changes.

• Packages and extensions:
  • gunicorn for an app server in both development and production
  • Flask-DB to help manage, migrate and seed your database
  • Flask-Static-Digest to md5 tag and gzip your static files (and add optional CDN support)
  • Flask-Secrets to quickly generate secure random tokens you can use for various things
  • Flask-DebugToolbar to show useful information for debugging
• Linting, formatting and testing:
  • ruff is used to lint and format the code base
  • pytest and pytest-cov for writing tests and reporting test coverage
• Blueprints:
  • Add page blueprint to render a / page
  • Add up blueprint to provide a few health check pages
• Config:
  • Log to STDOUT so that Docker can consume and deal with log output
  • Extract a bunch of configuration settings into environment variables
  • config/settings.py and the .env file handles configuration in all environments
• Front-end assets:
  • assets/ contains all your CSS, JS, images, fonts, etc. and is managed by esbuild
  • Custom 502.html and maintenance.html pages
  • Generate favicons using modern best practices
• Flask defaults that are changed:
  • public/ is the static directory where Flask will serve static files from
  • static_url_path is set to "" to remove the /static URL prefix for static files
  • ProxyFix middleware is enabled (check hello/app.py)

Besides the Flask app itself:

• uv is used for package management instead of pip3 (builds on my machine are ~10x faster!)
• Docker support has been added which would be any files having *docker* in its name
• GitHub Actions have been set up

Running this app

You'll need to have Docker installed. It's available on Windows, macOS and most distros of Linux. If you're new to Docker and want to learn it in detail check out the additional resources links near the bottom of this README.

You'll also need to enable Docker Compose v2 support if you're using Docker Desktop. On native Linux without Docker Desktop you can install it as a plugin to Docker. It's been generally available for a while now and is stable. This project uses specific Docker Compose v2 features that only work with Docker Compose v2 2.20.2+.

If you're using Windows, it will be expected that you're following along inside of WSL or WSL 2. That's because we're going to be running shell commands. You can always modify these commands for PowerShell if you want.

Clone this repo anywhere you want and move into the directory:

git clone https://github.com/nickjj/docker-flask-example helloflask
cd helloflask

Copy an example .env file because the real one is git ignored:

cp .env.example .env

Build everything:

The first time you run this it's going to take 5-10 minutes depending on your internet connection speed and computer's hardware specs. That's because it's going to download a few Docker images and build the Python + Yarn dependencies.

docker compose up --build

Now that everything is built and running we can treat it like any other Flask app.

Did you receive an error about a port being in use? Chances are it's because something on your machine is already running on port 8000. Check out the docs in the .env file for the DOCKER_WEB_PORT_FORWARD variable to fix this.

Setup the initial database:

# You can run this from a 2nd terminal. It will create both a development and
# test database with the proper user / password credentials.
./run flask db reset --with-testdb

We'll go over that ./run script in a bit!

Check it out in a browser:

Visit in your favorite browser.

Linting the code base:

# You should get no output (that means everything is operational).
./run lint

Formatting the code base:

# You should see that everything is unchanged (it's all already formatted).
./run format

There's also a ./run quality command to run the above commands together.

Running the test suite:

# You should see all passing tests. Warnings are typically ok.
./run test

Stopping everything:

# Stop the containers and remove a few Docker related resources associated to this project.
docker compose down

You can start things up again with docker compose up and unlike the first time it should only take seconds.

Files of interest

I recommend checking out most files and searching the code base for TODO:, but please review the .env and run files before diving into the rest of the code and customizing it. Also, you should hold off on changing anything until we cover how to customize this example app's name with an automated script (coming up next in the docs).

.env

This file is ignored from version control so it will never be committed. There's a number of environment variables defined here that control certain options and behavior of the application. Everything is documented there.

Feel free to add new variables as needed. This is where you should put all of your secrets as well as configuration that might change depending on your environment (specific dev boxes, CI, production, etc.).

run

You can run ./run to get a list of commands and each command has documentation in the run file itself.

It's a shell script that has a number of functions defined to help you interact with this project. It's basically a Makefile except with less limitations. For example as a shell script it allows us to pass any arguments to another program.

This comes in handy to run various Docker commands because sometimes these commands can be a bit long to type. Feel free to add as many convenience functions as you want. This file's purpose is to make your experience better!

If you get tired of typing ./run you can always create a shell alias with alias run=./run in your ~/.bash_aliases or equivalent file. Then you'll be able to run run instead of ./run.

✨ Running a script to automate renaming the project

The app is named hello right now but chances are your app will be a different name. Since the app is already created we'll need to do a find / replace on a few variants of the string "hello" and update a few Docker related resources.

And by we I mean I created a zero dependency shell script that does all of the heavy lifting for you. All you have to do is run the script below.

Run the rename-project script included in this repo:

# The script takes 2 arguments.
#
# The first one is the lower case version of your app's name, such as myapp or
# my_app depending on your preference.
#
# The second one is used for your app's module name. For example if you used
# myapp or my_app for the first argument you would want to use MyApp here.
bin/rename-project myapp MyApp

The bin/rename-project script is going to:

• Remove any Docker resources for your current project
• Perform a number of find / replace actions
• Optionally initialize a new git repo for you

Afterwards you can delete this script because its only purpose is to assist in helping you change this project's name without depending on any complicated project generator tools or 3rd party dependencies.

If you're not comfy running the script or it doesn't work for whatever reasons you can check it out and perform the actions manually. It's mostly running a find / replace across files and then renaming a few directories and files.

Start and setup the project:

This won't take as long as before because Docker can re-use most things. We'll also need to setup our database since a new one will be created for us by Docker.

docker compose up --build

# Then in a 2nd terminal once it's up and ready.
./run flask db reset --with-testdb

Sanity check to make sure the tests still pass:

It's always a good idea to make sure things are in a working state before adding custom changes.

# You can run this from the same terminal as before.
./run quality
./run test

If everything passes now you can optionally git add -A && git commit -m "Initial commit" and start customizing your app. Alternatively you can wait until you develop more of your app before committing anything. It's up to you!

Tying up a few loose ends:

You'll probably want to create a fresh `CHANGELOG.md