Environment Variables

Set up the .env file

Database (and other) settings can be read from environment variables or from a .env file in the project root. See the .env.example file for how to use, in fact you can just copy this file to .env and edit the settings as required.

Set the Base URL

The Base URL is the hostname and path to the ROOT of the API on your hosting system. Knowing this allows the API to build paths in responses and internally.

BASE_URL=https://api.my-server.com

Set the API Root Prefix (Optional)

If you want to add a prefix to all the routes, you can set it here. This is useful if you are running multiple APIs on the same server and want to avoid route conflicts, or for versioning.

API_ROOT=/api/v1

This will prefix all routes with /api/v1, so /users becomes /api/v1/users and so on. If this is not set, the API will use the root / as the prefix. Do not add a trailing / to the prefix, though if present it will be stripped anyway.

Disable the Root Route

By default, the root route / is enabled and returns an HTML page with a welcome message if accessed through a browser or a JSON response if accessed directly. If you want to disable this, set the below variable to False.

NO_ROOT_ROUTE=True

If the variable is not set, or set to False, the root route will be enabled as usual. If set to True, the root route will return a 404 error and a JSON message.

Configure the database Settings

Edit the below part of the .env file to configure your database. If this is incorrect, the API will clear all routes and only display an error.

DB_USER=dbuser
DB_PASSWORD=my_secret_passw0rd
DB_ADDRESS=localhost
DB_PORT=5432
DB_NAME=my_database_name

For testing, also set the name of the test database:

TEST_DB_NAME=my_test_database_name

Change the SECRET_KEY

Do not leave this as default, generate a new unique key for each of your projects! This key is used to sign the JWT tokens and should be kept secret, and be unique for each project.

Through the CLI

You can do this by running the below command in the root of the project:

api-admin keys -s

This will generate a new key and optionally update the .env file with the new value. If you choose not to do the update automatically, you can copy the key from the console output and paste it into the .env file.

SECRET_KEY=d0d83c7ac2f3e4dfa205dc3c51b4952ad57fa8a842c8417168dc46bc07fbc1f8

Manually

If you prefer to do this manually, you can generate a new key using the below commands:

To generate a good secret key you can use the below command on Linux or Mac:

$ openssl rand -base64 32
xtFhsNhbGOJG//TAtDNtoTxV/hVDvssC79ApNm0gs7w=

or a one-liner using Python:

$ python -c 'import secrets; print(secrets.token_hex(32))'
d0d83c7ac2f3e4dfa205dc3c51b4952ad57fa8a842c8417168dc46bc07fbc1f8

Then replace the default value in the .env file as so:

SECRET_KEY=d0d83c7ac2f3e4dfa205dc3c51b4952ad57fa8a842c8417168dc46bc07fbc1f8

Token Expiry Setting

This is how long (in minutes) before the access (Bearer) Token expires and needs to be refreshed. Default is 120 minutes.

ACCESS_TOKEN_EXPIRE_MINUTES=120

Check CORS Settings

Cross-Origin Resource Sharing (CORS) is an HTTP-header based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources.

For a PUBLIC API (unless its going through an API gateway!), set CORS_ORIGINS=*, otherwise list the domains (and ports) required. If you use an API gateway of some nature, that will probably need to be listed.

CORS_ORIGINS=*

If the database is not configured or cannot be reached, the Application will disable all routes, print an error to the console, and return a a 500 status code with a clear JSON message for all routes. This saves the ugly default "Internal Server Error" from being displayed.

Change the Email Server settings

The API will currently only send an email when a new user registers (though we will make more use of this in future), so you need to have valid email account details entered into the .env file.

For development and testing, I can recommend using Mailtrap to avoid filling up your mailbox with development spam (note that the Unit/Integration tests will automatically disable the mail functionality for this reason).

MailTrap offers a free Email capture service with a virtual web-based Inbox. Its great for developing and manually testing code that includes email sending, I can't recommend it highly enough.

Once you have the email settings, replace the default values in the .env file:

MAIL_USERNAME=emailuser
MAIL_PASSWORD=letmein
MAIL_FROM=[email protected]
MAIL_PORT=587
MAIL_SERVER=smtp.mailserver.com
MAIL_FROM_NAME="FastAPI Template"

Example full .env file

Below is a full .env file. This can also be found in the root of the API as .env.example.

# The Base API Url. This is where your API wil be served from, and can be read
# in the application code. It has no effect on the running of the applciation
# but is an easy way to build a path for API responses. Defaults to
# http://localhost:8000
BASE_URL=http://localhost:8000

# The root path for the API. This is the path that the API will be served from,
#defaults to '' (empty string). If you want to serve the API from a subpath,
# change this to the subpath, eg: /api/v1
# API_ROOT=/api/v1

# Set to True to disable the root route, and return a 404 for the root path. If
# not set, defaults to False.
NO_ROOT_ROUTE=False

# Database Settings These must be changed to match your setup, and the database
# must already exist.
DB_USER=dbuser
DB_PASSWORD=my_secret_passw0rd
DB_ADDRESS=localhost
DB_PORT=5432
DB_NAME=my_database_name

# Database settings to use for testing. These must be changed to match your
# setup. Note that User/Pass and Server/Port are the same as above, but the
# database name should be different to avoid conflicts. This database needs to
# already exist.
TEST_DB_NAME=my_database_name_tests

# generate your own super secret key here, used by the JWT functions.
# 32 characters or longer, definately change the below!!
SECRET_KEY=change_me_to_something_secret

# How long the access token is valid for, in minutes. Defaults to 120 (2 hours)
ACCESS_TOKEN_EXPIRE_MINUTES=120

# List of origins that can access this API, separated by a comma, eg:
# CORS_ORIGINS=http://localhost,https://www.gnramsay.com
# If you want all origins to access (the default), use * or comment out:
CORS_ORIGINS=*

# Email Settings specific to your email provider
MAIL_USERNAME=test_username
MAIL_PASSWORD=s3cr3tma1lp@ssw0rd
MAIL_FROM=[email protected]
MAIL_PORT=587
MAIL_SERVER=mail.server.com
MAIL_FROM_NAME="FastAPI Template"

# Admin Pages Settings
ADMIN_PAGES_ENABLED=True
ADMIN_PAGES_ROUTE=/admin
ADMIN_PAGES_TITLE="API Administration"
ADMIN_PAGES_ENCRYPTION_KEY=change_me_to_a_secret_fernet_key (optional)
ADMIN_PAGES_TIMEOUT=86400

# Common Email Settings
MAIL_STARTTLS=True
MAIL_SSL_TLS=False
MAIL_USE_CREDENTIALS=True
MAIL_VALIDATE_CERTS=True