Configuration and project structure

Organise config as classes, read secrets from the environment, keep machine-specific files in the instance folder, and make development and production differ only where they must.

Config objects

# app/config.py
import os
from datetime import timedelta

class Config:
    SECRET_KEY = os.environ.get("SECRET_KEY")      # None -> sessions break loudly
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL")
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    MAX_CONTENT_LENGTH = 5 * 1024 * 1024
    PERMANENT_SESSION_LIFETIME = timedelta(hours=8)

class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///" + os.path.join(os.getcwd(), "dev.db")

class TestingConfig(Config):
    TESTING = True
    DEBUG = False
    SECRET_KEY = "test-only-not-a-secret"
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"    # or a dedicated test database
    WTF_CSRF_ENABLED = False

class ProductionConfig(Config):
    DEBUG = False
    SESSION_COOKIE_SECURE = True
    PREFERRED_URL_SCHEME = "https"

CONFIGS = {
    "development": DevelopmentConfig,
    "testing": TestingConfig,
    "production": ProductionConfig,
}

# app/__init__.py
import os
from .config import CONFIGS

def create_app(config_object=None):
    app = Flask(__name__, instance_relative_config=True)
    name = config_object or os.environ.get("FLASK_CONFIG", "development")
    app.config.from_object(CONFIGS[name] if isinstance(name, str) else name)
    app.config.from_pyfile("config.py", silent=True)     # instance/config.py wins
    return app

# tests pass a class directly
app = create_app("testing")

Environment variables and the instance folder

# app/config.py — fail fast, in one place
import os

def required(name):
    try:
        return os.environ[name]
    except KeyError:
        raise RuntimeError(f"Missing required environment variable: {name}")

class ProductionConfig(Config):
    DEBUG = False
    SECRET_KEY = required("SECRET_KEY")
    SQLALCHEMY_DATABASE_URI = required("DATABASE_URL")

# local development: load a git-ignored .env before the app reads config
from dotenv import load_dotenv
load_dotenv()          # in run.py or wsgi.py, never in production images

# typed values: strings from the environment are always strings
DEBUG = os.environ.get("DEBUG", "").lower() in {"1", "true", "yes"}
MAX_CONTENT_LENGTH = int(os.environ.get("MAX_UPLOAD_MB", "5")) * 1024 * 1024

• app.instance_path points at a directory outside the package where local, machine-specific files live: config.py with local overrides, an upload folder, a SQLite file. It is not copied into the installed package and not committed.
• Later sources win: from_object then from_pyfile means the instance file overrides the class. Use that ordering deliberately so a developer can point at a local database without editing tracked code.
• Give a secret no default in production. A missing SECRET_KEY that silently falls back to a string in the source means every deployment shares signing keys, and an attacker who reads the repository can forge session cookies.
• Never commit a .env file. Provide a .env.example with placeholder values so a new checkout knows what to set.

Development, test and production

# tests/conftest.py
import pytest
from app import create_app
from app.extensions import db

@pytest.fixture
def app():
    application = create_app("testing")
    with application.app_context():
        db.create_all()
        yield application
        db.session.remove()
        db.drop_all()

@pytest.fixture
def client(app):
    return app.test_client()

export FLASK_CONFIG=production
export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
export DATABASE_URL="postgresql+psycopg://app:pw@db:5432/app"
flask --app app:create_app run

FAQ

Related

Blueprints and the application factory Deployment: gunicorn, nginx and Docker

Last refreshed 2026-09-18.