📝 Update release notes

[skip ci]

.copier/update_dotenv.py

@@ -9,9 +9,20 @@ answers_path = Path(__file__).parent / ".copier-answers.yml"
 answers = json.loads(answers_path.read_text())
 env_path = root_path / ".env"
 env_content = env_path.read_text()
+# Keep deployment provider settings from replacing local development defaults.
+env_answer_keys = {
+    "emails_from_email",
+    "first_superuser",
+    "first_superuser_password",
+    "postgres_password",
+    "project_name",
+    "secret_key",
+}
 lines = []
 for line in env_content.splitlines():
     for key, value in answers.items():
+        if key not in env_answer_keys:
+            continue
         upper_key = key.upper()
         if line.startswith(f"{upper_key}="):
             if " " in value:

.env

@@ -1,40 +1,20 @@
-# Domain
-# This would be set to the production domain with an env var on deployment
-# used by Traefik to transmit traffic and acquire TLS certificates
-DOMAIN=localhost
-# To test the local Traefik config
-# DOMAIN=localhost.tiangolo.com
-
-# Public frontend URL, used by the backend to generate links in emails.
-# Deployments derive this from DOMAIN in compose.deploy.yml.
-FRONTEND_HOST=http://localhost:5173
-
-# Environment: local, staging, production
+# Enable local-only development behavior
 ENVIRONMENT=local
 
 PROJECT_NAME="Full Stack FastAPI Project"
 
-# Backend
-# Additional allowed CORS origins, separated by commas
-BACKEND_CORS_ORIGINS=
 SECRET_KEY=changethis
 FIRST_SUPERUSER=admin@example.com
 FIRST_SUPERUSER_PASSWORD=changethis
 
 # Emails
-SMTP_HOST=
-SMTP_USER=
-SMTP_PASSWORD=
+SMTP_HOST=localhost
 EMAILS_FROM_EMAIL=info@example.com
-SMTP_TLS=True
-SMTP_SSL=False
-SMTP_PORT=587
+SMTP_TLS=False
+SMTP_PORT=1025
 
 # Postgres
 POSTGRES_SERVER=localhost
-POSTGRES_PORT=5432
 POSTGRES_DB=app
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=changethis
-
-SENTRY_DSN=

.github/workflows/deploy-production.yml

@@ -17,7 +17,6 @@ jobs:
       - self-hosted
       - production
     env:
-      ENVIRONMENT: production
       DOMAIN: ${{ secrets.DOMAIN }}
       SECRET_KEY: ${{ secrets.SECRET_KEY }}
       FIRST_SUPERUSER: ${{ secrets.FIRST_SUPERUSER }}

.github/workflows/deploy-staging.yml

@@ -17,7 +17,6 @@ jobs:
       - self-hosted
       - staging
     env:
-      ENVIRONMENT: staging
       DOMAIN: ${{ secrets.DOMAIN }}
       SECRET_KEY: ${{ secrets.SECRET_KEY }}
       FIRST_SUPERUSER: ${{ secrets.FIRST_SUPERUSER }}

.pre-commit-config.yaml

@@ -64,7 +64,7 @@ repos:
         entry: bash ./scripts/generate-client.sh
         pass_filenames: false
         language: unsupported
-        files: ^backend/.*$|^scripts/generate-client\.sh$
+        files: ^backend/app/.*\.py$|^backend/pyproject\.toml$|^uv\.lock$|^frontend/openapi-ts\.config\.ts$|^scripts/generate-client\.sh$
 
       - id: add-release-date
         language: unsupported

README.md

@@ -17,7 +17,7 @@
   - 🤖 An automatically generated frontend client.
   - 🧪 [Playwright](https://playwright.dev) for End-to-End testing.
   - 🦇 Dark mode support.
-- 🐋 [Docker Compose](https://www.docker.com) for development and production.
+- 🐋 [Docker Compose](https://www.docker.com) for local services and deployment.
 - 🔒 Secure password hashing by default.
 - 🔑 JWT (JSON Web Token) authentication.
 - 📫 Email based password recovery.
@@ -199,12 +199,8 @@ The input variables, with their default values (some auto generated) are:
 - `secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above.
 - `first_superuser`: (default: `"admin@example.com"`) The email of the first superuser (in .env).
 - `first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env).
-- `smtp_host`: (default: "") The SMTP server host to send emails, you can set it later in .env.
-- `smtp_user`: (default: "") The SMTP server user to send emails, you can set it later in .env.
-- `smtp_password`: (default: "") The SMTP server password to send emails, you can set it later in .env.
 - `emails_from_email`: (default: `"info@example.com"`) The email account to send emails from, you can set it later in .env.
 - `postgres_password`: (default: `"changethis"`) The password for the PostgreSQL database, stored in .env, you can generate one with the method above.
-- `sentry_dsn`: (default: "") The DSN for Sentry, if you are using it, you can set it later in .env.
 
 ## Backend Development
 
@@ -222,7 +218,7 @@ Deployment docs: [deployment.md](./deployment.md).
 
 General development docs: [development.md](./development.md).
 
-This includes using Docker Compose, custom local domains, `.env` configurations, etc.
+This includes the local FastAPI and Vite workflow, Docker Compose services, custom local domains, `.env` configuration, and more.
 
 ## Release Notes
 

backend/README.md

@@ -5,9 +5,25 @@
 * [Docker](https://www.docker.com/).
 * [uv](https://docs.astral.sh/uv/) for Python package and environment management.
 
-## Docker Compose
+## Local Development
 
-Start the local development environment with Docker Compose following the guide in [../development.md](../development.md).
+Run the backend locally and connect it to PostgreSQL in Docker Compose.
+
+From the project root, start PostgreSQL and Mailcatcher:
+
+```console
+$ docker compose up -d db mailcatcher
+```
+
+Then, from `./backend/`, install the dependencies, prepare the database, and start the development server:
+
+```console
+$ uv sync
+$ uv run bash scripts/prestart.sh
+$ uv run fastapi dev
+```
+
+The API is available at `http://localhost:8000`, with automatic interactive docs at `http://localhost:8000/docs`.
 
 ## General Workflow
 
@@ -35,66 +51,32 @@ There are already configurations in place to run the backend through the VS Code
 
 The setup is also already configured so you can run the tests through the VS Code Python tests tab.
 
-## Docker Compose Override
+## Full Stack with Docker Compose
 
-During development, you can change Docker Compose settings that will only affect the local development environment in the file `compose.override.yml`.
-
-The changes to that file only affect the local development environment, not the production environment. So, you can add "temporary" changes that help the development workflow.
-
-For example, the directory with the backend code is synchronized in the Docker container, copying the code you change live to the directory inside the container. That allows you to test your changes right away, without having to build the Docker image again. It should only be done during development, for production, you should build the Docker image with a recent version of the backend code. But during development, it allows you to iterate very fast.
-
-There is also a command override that runs `fastapi run --reload` instead of the default `fastapi run`. It starts a single server process (instead of multiple, as would be for production) and reloads the process whenever the code changes. Have in mind that if you have a syntax error and save the Python file, it will break and exit, and the container will stop. After that, you can restart the container by fixing the error and running again:
+To run the backend and built frontend in Docker Compose:
 
 ```console
 $ docker compose watch
 ```
 
-There is also a commented out `command` override, you can uncomment it and comment the default one. It makes the backend container run a process that does "nothing", but keeps the container alive. That allows you to get inside your running container and execute commands inside, for example a Python interpreter to test installed dependencies, or start the development server that reloads when it detects changes.
+The application is available at `http://localhost:8000`.
 
-To get inside the container with a `bash` session you can start the stack with:
+### Docker Compose Override
 
-```console
-$ docker compose watch
-```
+The `compose.override.yml` file contains local settings for published ports, source synchronization, automatic image rebuilds, and backend reloads. Docker Compose applies it automatically when you run `docker compose` without an explicit file list.
 
-and then in another terminal, `exec` inside the running container:
+To open a shell in the backend container:
 
 ```console
 $ docker compose exec backend bash
 ```
 
-You should see an output like:
-
-```console
-root@7f2607af31c3:/app#
-```
-
-that means that you are in a `bash` session inside your container, as a `root` user, under the `/app` directory, this directory has another directory called "app" inside, that's where your code lives inside the container: `/app/app`.
-
-There you can use the `fastapi run --reload` command to run the debug live reloading server.
-
-```console
-$ fastapi run --reload app/main.py
-```
-
-...it will look like:
-
-```console
-root@7f2607af31c3:/app# fastapi run --reload app/main.py
-```
-
-and then hit enter. That runs the live reloading server that auto reloads when it detects code changes.
-
-Nevertheless, if it doesn't detect a change but a syntax error, it will just stop with an error. But as the container is still alive and you are in a Bash session, you can quickly restart it after fixing the error, running the same command ("up arrow" and "Enter").
-
-...this previous detail is what makes it useful to have the container alive doing nothing and then, in a Bash session, make it run the live reload server.
-
 ## Backend tests
 
-To test the backend run:
+To test the backend from the `backend` directory, run:
 
 ```console
-$ bash ./scripts/test.sh
+$ uv run bash ./scripts/test.sh
 ```
 
 The tests run with Pytest, modify and add tests to `./backend/tests/`.
@@ -123,22 +105,14 @@ When the tests are run, a file `htmlcov/index.html` is generated, you can open i
 
 ## Migrations
 
-As during local development your app directory is mounted as a volume inside the container, you can also run the migrations with `alembic` commands inside the container and the migration code will be in your app directory (instead of being only inside the container). So you can add it to your git repository.
-
-Make sure you create a "revision" of your models and that you "upgrade" your database with that revision every time you change them. As this is what will update the tables in your database. Otherwise, your application will have errors.
-
-* Start an interactive session in the backend container:
-
-```console
-$ docker compose exec backend bash
-```
+Make sure you create a revision of your models and upgrade the database with that revision every time you change them. From the `backend` directory, use `uv` to run Alembic against the PostgreSQL container:
 
 * Alembic is already configured to import your SQLModel models from `./backend/app/models.py`.
 
-* After changing a model (for example, adding a column), inside the container, create a revision, e.g.:
+* After changing a model (for example, adding a column), create a revision:
 
 ```console
-$ alembic revision --autogenerate -m "Add column last_name to User model"
+$ uv run alembic revision --autogenerate -m "Add column last_name to User model"
 ```
 
 * Commit to the git repository the files generated in the alembic directory.
@@ -146,7 +120,7 @@ $ alembic revision --autogenerate -m "Add column last_name to User model"
 * After creating the revision, run the migration in the database (this is what will actually change the database):
 
 ```console
-$ alembic upgrade head
+$ uv run alembic upgrade head
 ```
 
 If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/core/db.py` that end in:

backend/app/core/config.py

@@ -34,7 +34,7 @@ class Settings(BaseSettings):
     # 60 minutes * 24 hours * 8 days = 8 days
     ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 8
     FRONTEND_HOST: str = "http://localhost:5173"
-    ENVIRONMENT: Literal["local", "staging", "production"] = "local"
+    ENVIRONMENT: Literal["local"] | None = None
 
     BACKEND_CORS_ORIGINS: Annotated[
         list[AnyUrl] | str, BeforeValidator(parse_cors)

compose.deploy.yml

@@ -38,7 +38,7 @@ services:
     restart: always
     labels:
       # Route HTTPS traffic for the Adminer subdomain
-      - traefik.http.routers.adminer-https.rule=Host(`adminer.${DOMAIN?Variable not set}`)
+      - traefik.http.routers.adminer-https.rule=Host(`adminer.${DOMAIN:?Variable not set}`)
       - traefik.http.routers.adminer-https.entrypoints=https
       - traefik.http.routers.adminer-https.tls=true
       # Use the Let's Encrypt resolver
@@ -46,15 +46,15 @@ services:
 
   prestart:
     environment:
-      FRONTEND_HOST: https://${DOMAIN?Variable not set}
+      FRONTEND_HOST: https://${DOMAIN:?Variable not set}
 
   backend:
     restart: always
     environment:
-      FRONTEND_HOST: https://${DOMAIN?Variable not set}
+      FRONTEND_HOST: https://${DOMAIN:?Variable not set}
     labels:
       # Route HTTPS traffic for this domain
-      - traefik.http.routers.backend-https.rule=Host(`${DOMAIN?Variable not set}`)
+      - traefik.http.routers.backend-https.rule=Host(`${DOMAIN:?Variable not set}`)
       - traefik.http.routers.backend-https.entrypoints=https
       - traefik.http.routers.backend-https.tls=true
       # Use the Let's Encrypt resolver

compose.override.yml

@@ -68,10 +68,14 @@ services:
     volumes:
       - ./backend/htmlcov:/app/backend/htmlcov
     environment:
+      ENVIRONMENT: "local"
       SMTP_HOST: "mailcatcher"
       SMTP_PORT: "1025"
       SMTP_TLS: "false"
-      EMAILS_FROM_EMAIL: "noreply@example.com"
+
+  prestart:
+    environment:
+      ENVIRONMENT: "local"
 
   mailcatcher:
     image: schickling/mailcatcher
@@ -89,15 +93,15 @@ services:
     depends_on:
       - backend
       - mailcatcher
-    env_file:
-      - .env
     environment:
+      - FIRST_SUPERUSER=${FIRST_SUPERUSER:?Variable not set}
+      - FIRST_SUPERUSER_PASSWORD=${FIRST_SUPERUSER_PASSWORD:?Variable not set}
       - PLAYWRIGHT_BASE_URL=http://backend:8000
       - VITE_API_URL=http://backend:8000
       - MAILCATCHER_HOST=http://mailcatcher:1080
       # For the reports when run locally
       - PLAYWRIGHT_HTML_HOST=0.0.0.0
-      - CI=${CI}
+      - CI=${CI:-}
     volumes:
       - ./frontend/blob-report:/app/frontend/blob-report
       - ./frontend/test-results:/app/frontend/test-results

compose.yml

@@ -27,12 +27,10 @@ services:
       timeout: 10s
     volumes:
       - app-db-data:/var/lib/postgresql
-    env_file:
-      - .env
     environment:
-      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD?Variable not set}
-      - POSTGRES_USER=${POSTGRES_USER?Variable not set}
-      - POSTGRES_DB=${POSTGRES_DB?Variable not set}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?Variable not set}
+      - POSTGRES_USER=${POSTGRES_USER:?Variable not set}
+      - POSTGRES_DB=${POSTGRES_DB:?Variable not set}
 
   adminer:
     image: adminer
@@ -44,7 +42,7 @@ services:
       # Enable Traefik for this service
       - traefik.enable=true
       # Route HTTP traffic for the Adminer subdomain
-      - traefik.http.routers.adminer-http.rule=Host(`adminer.${DOMAIN?Variable not set}`)
+      - traefik.http.routers.adminer-http.rule=Host(`adminer.${DOMAIN:-localhost}`)
       - traefik.http.routers.adminer-http.entrypoints=http
       # Define the port inside of the Docker service to use
       - traefik.http.services.adminer.loadbalancer.server.port=8080
@@ -59,26 +57,20 @@ services:
         condition: service_completed_successfully
     # The YAML anchor lets the prestart service reuse this environment mapping.
     environment: &backend-environment
-      FRONTEND_HOST: ${FRONTEND_HOST?Variable not set}
-      ENVIRONMENT: ${ENVIRONMENT}
-      PROJECT_NAME: ${PROJECT_NAME?Variable not set}
-      BACKEND_CORS_ORIGINS: ${BACKEND_CORS_ORIGINS}
-      SECRET_KEY: ${SECRET_KEY?Variable not set}
-      FIRST_SUPERUSER: ${FIRST_SUPERUSER?Variable not set}
-      FIRST_SUPERUSER_PASSWORD: ${FIRST_SUPERUSER_PASSWORD?Variable not set}
+      PROJECT_NAME: ${PROJECT_NAME:?Variable not set}
+      BACKEND_CORS_ORIGINS: ${BACKEND_CORS_ORIGINS:-}
+      SECRET_KEY: ${SECRET_KEY:?Variable not set}
+      FIRST_SUPERUSER: ${FIRST_SUPERUSER:?Variable not set}
+      FIRST_SUPERUSER_PASSWORD: ${FIRST_SUPERUSER_PASSWORD:?Variable not set}
       SMTP_HOST: ${SMTP_HOST}
-      SMTP_USER: ${SMTP_USER}
-      SMTP_PASSWORD: ${SMTP_PASSWORD}
+      SMTP_USER: ${SMTP_USER:-}
+      SMTP_PASSWORD: ${SMTP_PASSWORD:-}
       EMAILS_FROM_EMAIL: ${EMAILS_FROM_EMAIL}
-      SMTP_TLS: ${SMTP_TLS}
-      SMTP_SSL: ${SMTP_SSL}
-      SMTP_PORT: ${SMTP_PORT}
       POSTGRES_SERVER: db
-      POSTGRES_PORT: ${POSTGRES_PORT}
-      POSTGRES_DB: ${POSTGRES_DB}
-      POSTGRES_USER: ${POSTGRES_USER?Variable not set}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD?Variable not set}
-      SENTRY_DSN: ${SENTRY_DSN}
+      POSTGRES_DB: ${POSTGRES_DB:?Variable not set}
+      POSTGRES_USER: ${POSTGRES_USER:?Variable not set}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Variable not set}
+      SENTRY_DSN: ${SENTRY_DSN:-}
 
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/utils/health-check/"]
@@ -97,7 +89,7 @@ services:
       - traefik.http.services.backend.loadbalancer.server.port=8000
 
       # Route HTTP traffic for this domain
-      - traefik.http.routers.backend-http.rule=Host(`${DOMAIN?Variable not set}`)
+      - traefik.http.routers.backend-http.rule=Host(`${DOMAIN:-localhost}`)
       - traefik.http.routers.backend-http.entrypoints=http
 
   prestart:

copier.yml

@@ -21,21 +21,6 @@ first_superuser_password:
   help: The password of the first superuser (in .env)
   default: changethis
 
-smtp_host:
-  type: str
-  help: The SMTP server host to send emails, you can set it later in .env
-  default: ""
-
-smtp_user:
-  type: str
-  help: The SMTP server user to send emails, you can set it later in .env
-  default: ""
-
-smtp_password:
-  type: str
-  help: The SMTP server password to send emails, you can set it later in .env
-  default: ""
-
 emails_from_email:
   type: str
   help: The email account to send emails from, you can set it later in .env
@@ -49,11 +34,6 @@ postgres_password:
     python -c "import secrets; print(secrets.token_urlsafe(32))"'
   default: changethis
 
-sentry_dsn:
-  type: str
-  help: The DSN for Sentry, if you are using it, you can set it later in .env
-  default: ""
-
 _exclude:
   # Global
   - .vscode

deployment.md

@@ -46,13 +46,7 @@ Copy the content and use that as password / secret key. And run that again to ge
 
 ### Required Environment Variables
 
-Set the `ENVIRONMENT`, by default `local` (for development), but when deploying to a server you would put something like `staging` or `production`:
-
-```bash
-export ENVIRONMENT=production
-```
-
-Set the `DOMAIN`, by default `localhost` (for development), but when deploying you would use your own domain, for example:
+Set the `DOMAIN` to your own domain, for example:
 
 ```bash
 export DOMAIN=fastapi-project.example.com
@@ -60,24 +54,22 @@ export DOMAIN=fastapi-project.example.com
 
 The deployment Docker Compose configuration also uses `DOMAIN` to set the public frontend URL used in links generated by the backend.
 
-Set the `POSTGRES_PASSWORD` to something different than `changethis`:
+Set the `POSTGRES_PASSWORD` to a secure value:
 
 ```bash
-export POSTGRES_PASSWORD="changethis"
+export POSTGRES_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 
-Set the `SECRET_KEY`, used to sign tokens:
+Set the `SECRET_KEY`, used to sign tokens, to a secure value:
 
 ```bash
-export SECRET_KEY="changethis"
+export SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 
-Note: you can use the Python command above to generate a secure secret key.
-
-Set the `FIRST_SUPERUSER_PASSWORD` to something different than `changethis`:
+Set the `FIRST_SUPERUSER_PASSWORD` to a secure value:
 
 ```bash
-export FIRST_SUPERUSER_PASSWORD="changethis"
+export FIRST_SUPERUSER_PASSWORD="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
 ```
 
 You can set several other environment variables:
@@ -89,8 +81,6 @@ You can set several other environment variables:
 * `SMTP_USER`: The SMTP server user to send emails.
 * `SMTP_PASSWORD`: The SMTP server password to send emails.
 * `EMAILS_FROM_EMAIL`: The email account to send emails from.
-* `POSTGRES_SERVER`: The hostname of the PostgreSQL server. You can leave the default of `db`, provided by the same Docker Compose. You normally wouldn't need to change this unless you are using a third-party provider.
-* `POSTGRES_PORT`: The port of the PostgreSQL server. You can leave the default. You normally wouldn't need to change this unless you are using a third-party provider.
 * `POSTGRES_USER`: The Postgres user, you can leave the default.
 * `POSTGRES_DB`: The database name to use for this application. You can leave the default of `app`.
 * `SENTRY_DSN`: The DSN for Sentry, if you are using it.
@@ -202,16 +192,22 @@ To configure them, go to your repository's **Settings** > **Environments** and c
 
 For each GitHub Environment (`staging` and `production`), configure the required secrets as [environment secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-an-environment). Environment secrets are preferred over [repository secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-a-repository) because they are scoped to the specific environment, reducing exposure and aligning with any protection rules you configure.
 
-The current Github Actions workflows expect these secrets:
+The deployment workflows require these secrets:
 
 * `DOMAIN`
-* `EMAILS_FROM_EMAIL`
 * `FIRST_SUPERUSER`
 * `FIRST_SUPERUSER_PASSWORD`
 * `POSTGRES_PASSWORD`
 * `SECRET_KEY`
-* `LATEST_CHANGES`
-* `SMOKESHOW_AUTH_KEY`
+
+To enable emails, configure these additional secrets with the values from your email provider:
+
+* `SMTP_HOST`
+* `SMTP_USER`
+* `SMTP_PASSWORD`
+* `EMAILS_FROM_EMAIL`
+
+To enable Sentry, configure the `SENTRY_DSN` secret.
 
 ## GitHub Action Deployment Workflows
 

development.md

@@ -1,14 +1,66 @@
 # FastAPI Project - Development
 
-## Docker Compose
+## Local Development
 
-* Start the local stack with Docker Compose:
+For local development, run PostgreSQL and Mailcatcher with Docker Compose, and run the FastAPI and Vite development servers locally.
+
+Start the supporting services:
+
+```bash
+docker compose up -d db mailcatcher
+```
+
+Then, from the `backend` directory, install the dependencies and prepare the database:
+
+```bash
+uv sync
+uv run bash scripts/prestart.sh
+```
+
+Start the FastAPI development server:
+
+```bash
+uv run fastapi dev
+```
+
+In another terminal, from the project root, install the frontend dependencies and start the Vite development server:
+
+```bash
+bun install
+bun run dev
+```
+
+Now you can open these URLs:
+
+Frontend development server: <http://localhost:5173>
+
+Backend API: <http://localhost:8000>
+
+Automatic interactive API documentation with Swagger UI: <http://localhost:8000/docs>
+
+Mailcatcher: <http://localhost:1080>
+
+The frontend development server uses the backend at `http://localhost:8000`, as configured in `frontend/.env`.
+
+### Frontend Served by FastAPI
+
+Build the frontend from the `frontend` directory:
+
+```bash
+bun run build
+```
+
+The build is written to `backend/app/frontend` and served by FastAPI at <http://localhost:8000>. Rebuild the frontend after making frontend changes.
+
+## Full Stack with Docker Compose
+
+To run the backend and built frontend in Docker Compose:
 
 ```bash
 docker compose watch
 ```
 
-* Now you can open your browser and interact with these URLs:
+Now you can open these URLs:
 
 Application, with the frontend and API served by FastAPI: <http://localhost:8000>
 
@@ -18,58 +70,15 @@ Adminer, database web administration: <http://localhost:8080>
 
 Traefik UI, to see how the routes are being handled by the proxy: <http://localhost:8090>
 
-**Note**: The first time you start your stack, it might take a minute for it to be ready. While the backend waits for the database to be ready and configures everything. You can check the logs to monitor it.
+Mailcatcher: <http://localhost:1080>
 
-To check the logs, run (in another terminal):
+Stop a locally running FastAPI server before starting the Compose backend because both use port `8000`.
 
-```bash
-docker compose logs
-```
-
-To check the logs of a specific service, add the name of the service, e.g.:
-
-```bash
-docker compose logs backend
-```
+**Note**: The first time you start the stack, it might take a minute to be ready while the backend waits for the database and configures everything. To monitor it, use `docker compose logs`, or `docker compose logs backend` for the backend service.
 
 ## Mailcatcher
 
-Mailcatcher is a simple SMTP server that catches all emails sent by the backend during local development. Instead of sending real emails, they are captured and displayed in a web interface.
-
-This is useful for:
-
-* Testing email functionality during development
-* Verifying email content and formatting
-* Debugging email-related functionality without sending real emails
-
-The backend is automatically configured to use Mailcatcher when running with Docker Compose locally (SMTP on port 1025). All captured emails can be viewed at <http://localhost:1080>.
-
-## Local Development
-
-The Docker Compose files are configured so that each supporting service is available in a different port in `localhost`.
-
-FastAPI serves the built frontend and the API as one application at `http://localhost:8000`. The API routes live under `/api`.
-
-For frontend development with live reload, you can still run the local Vite development server separately.
-
-Start the local frontend development server with:
-
-```bash
-bun run dev
-```
-
-Or you could stop the `backend` Docker Compose service:
-
-```bash
-docker compose stop backend
-```
-
-And then you can run the local development server for the backend:
-
-```bash
-cd backend
-fastapi dev app/main.py
-```
+Mailcatcher captures emails sent during local development instead of delivering them. The local backend connects to it at `localhost:1025`, and the Compose backend connects to the `mailcatcher` service. Captured emails are available at <http://localhost:1080>.
 
 ## Docker Compose in `localhost.tiangolo.com`
 
@@ -107,7 +116,7 @@ And there's also a `compose.override.yml` with overrides for development, for ex
 
 The `compose.deploy.yml` file contains the deployment-specific settings, including HTTPS and automatic certificate handling. It is explicitly combined with `compose.yml` when deploying the application.
 
-These Docker Compose files use the `.env` file containing configurations to be injected as environment variables in the containers.
+The backend reads local settings from the `.env` file. Docker Compose also uses it for variable interpolation and passes the settings each container needs.
 
 They also use some additional configurations taken from environment variables set in the scripts before calling the `docker compose` command.
 
@@ -119,11 +128,11 @@ docker compose watch
 
 ## The .env file
 
-The `.env` file is the one that contains all your configurations, generated keys and passwords, etc.
+The `.env` file contains the shared local defaults, generated keys, passwords, and other configuration. Its hostnames use `localhost` for processes running on your machine. Docker Compose overrides hostnames such as the database and SMTP server with their Compose service names.
 
 Depending on your workflow, you could want to exclude it from Git, for example if your project is public. In that case, you would have to make sure to set up a way for your CI tools to obtain it while building or deploying your project.
 
-One way to do it could be to add each environment variable to your CI/CD system, and updating the `compose.yml` file to read that specific env var instead of reading the `.env` file.
+One way to do it could be to add each environment variable to your CI/CD system.
 
 ## Pre-commits and code linting
 

frontend/README.md

@@ -15,7 +15,9 @@ bun run dev
 
 * Then open your browser at http://localhost:5173/.
 
-Notice that this live server is not running inside Docker, it's for local development, and that is the recommended workflow. Once you are happy with your frontend, you can build the backend Docker image and start it, to test the production-like setup where FastAPI serves the built frontend at `http://localhost:8000`.
+Run the backend locally with `uv run fastapi dev` and PostgreSQL in Docker Compose. See [../development.md](../development.md) for the complete setup.
+
+To serve the frontend with FastAPI, run `bun run build` from the `frontend` directory and open `http://localhost:8000`. To run the full stack with Docker Compose, use `docker compose watch`.
 
 Check the file `package.json` to see other available options.
 
@@ -33,14 +35,6 @@ If you are developing an API-only app and want to remove the frontend, you can d
 
 Done, you have a frontend-less (api-only) app. 🤓
 
----
-
-If you want, you can also remove the `FRONTEND_HOST` environment variable from:
-
-* `.env`
-
-But it would be only to clean them up, leaving them won't really have any effect either way.
-
 ## Generate Client
 
 ### Automatically
@@ -56,9 +50,9 @@ bash ./scripts/generate-client.sh
 
 ### Manually
 
-* Start the Docker Compose stack.
+* Make sure the backend is running.
 
-* Download the OpenAPI JSON file from `http://localhost/api/v1/openapi.json` and copy it to a new file `openapi.json` at the root of the `frontend` directory.
+* Download the OpenAPI JSON file from `http://localhost:8000/api/v1/openapi.json` and copy it to a new file `openapi.json` at the root of the `frontend` directory.
 
 * To generate the frontend client, run:
 

release-notes.md

@@ -9,6 +9,11 @@
 
 ### Refactors
 
+* ♻️ Require non-empty Compose configuration. PR [#2418](https://github.com/fastapi/full-stack-fastapi-template/pull/2418) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Simplify optional environment configuration. PR [#2417](https://github.com/fastapi/full-stack-fastapi-template/pull/2417) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Simplify Copier environment configuration. PR [#2416](https://github.com/fastapi/full-stack-fastapi-template/pull/2416) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Simplify environment defaults. PR [#2415](https://github.com/fastapi/full-stack-fastapi-template/pull/2415) by [@tiangolo](https://github.com/tiangolo).
+* ♻️ Simplify local development workflow. PR [#2414](https://github.com/fastapi/full-stack-fastapi-template/pull/2414) by [@tiangolo](https://github.com/tiangolo).
 * ♻️ Simplify environment configuration. PR [#2413](https://github.com/fastapi/full-stack-fastapi-template/pull/2413) by [@tiangolo](https://github.com/tiangolo).
 * ♻️ Simplify Traefik deployment, make it part of the stack. PR [#2412](https://github.com/fastapi/full-stack-fastapi-template/pull/2412) by [@tiangolo](https://github.com/tiangolo).
 * ♻️ Serve frontend from FastAPI. PR [#2393](https://github.com/fastapi/full-stack-fastapi-template/pull/2393) by [@tiangolo](https://github.com/tiangolo).
@@ -25,6 +30,7 @@
 
 ### Docs
 
+* 📝 Clarify environment configuration. PR [#2419](https://github.com/fastapi/full-stack-fastapi-template/pull/2419) by [@tiangolo](https://github.com/tiangolo).
 * 📝 Improve README screenshot alt text. PR [#2359](https://github.com/fastapi/full-stack-fastapi-template/pull/2359) by [@Bmowville](https://github.com/Bmowville).
 * ✏️ Fix typo in the comment for DOMAIN in the .env file. PR [#2305](https://github.com/fastapi/full-stack-fastapi-template/pull/2305) by [@serhiiur](https://github.com/serhiiur).
 * 📝 Update security policy. PR [#2297](https://github.com/fastapi/full-stack-fastapi-template/pull/2297) by [@tiangolo](https://github.com/tiangolo).