fastapi-fullstack 0.2.17__tar.gz → 0.2.18__tar.gz

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fullstack
-Version: 0.2.17
+Version: 0.2.18
 Summary: Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability.
 Project-URL: Homepage, https://github.com/vstorm-co/full-stack-ai-agent-template
 Project-URL: Documentation, https://github.com/vstorm-co/full-stack-ai-agent-template#readme
@@ -298,7 +298,9 @@ For frontend deployment to **Vercel**:
 cd frontend && npx vercel --prod
 ```
 
-In the Vercel dashboard set `BACKEND_URL`, `BACKEND_WS_URL`, `NEXT_PUBLIC_AUTH_ENABLED=true`.
+In the Vercel dashboard set `BACKEND_URL` (server-side), plus `NEXT_PUBLIC_API_URL`,
+`NEXT_PUBLIC_WS_URL` (`wss://…`) and `NEXT_PUBLIC_SITE_URL` — the `NEXT_PUBLIC_*` ones are
+inlined at build time, so they need a redeploy to take effect.
 
 </details>
 

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/README.md

@@ -249,7 +249,9 @@ For frontend deployment to **Vercel**:
 cd frontend && npx vercel --prod
 ```
 
-In the Vercel dashboard set `BACKEND_URL`, `BACKEND_WS_URL`, `NEXT_PUBLIC_AUTH_ENABLED=true`.
+In the Vercel dashboard set `BACKEND_URL` (server-side), plus `NEXT_PUBLIC_API_URL`,
+`NEXT_PUBLIC_WS_URL` (`wss://…`) and `NEXT_PUBLIC_SITE_URL` — the `NEXT_PUBLIC_*` ones are
+inlined at build time, so they need a redeploy to take effect.
 
 </details>
 

fastapi_fullstack-0.2.18/UPGRADES.yaml

@@ -0,0 +1,25 @@
+# Structural metadata for `fastapi-fullstack upgrade` (renames, removals, manual steps).
+# See docs/guides/version-upgrade.md — "For template maintainers". One block per release.
+#
+# Schema (all keys optional except `version`):
+#
+# - version: "0.2.15"
+#   renames:
+#     - from: "backend/app/core/config.py"
+#       to:   "backend/app/core/settings.py"
+#   variable_renames:
+#     - from: "use_pgvector"
+#       to:   "vector_store"
+#       value_map: { "true": "pgvector" }
+#   removed:
+#     - "backend/app/legacy_auth.py"
+#   breaking:
+#     - "JWT secret env var renamed SECRET_KEY → AUTH_SECRET_KEY."
+#   manual_steps:
+#     - "Run `alembic upgrade head` (new billing tables)."
+
+- version: "0.2.18"
+  manual_steps:
+    - "Rebuild the frontend image: `docker compose -f docker-compose.prod.yml build --no-cache frontend`. NEXT_PUBLIC_* is inlined into the browser bundle at build time and now comes from compose build args, so an image built before this upgrade still has the old ws://localhost URL baked in."
+    - "Serving the frontend over plain http:// with no TLS? Set COOKIE_SECURE=false on the frontend service. The auth cookies are Secure in production and a browser discards a Secure cookie sent over http://, which makes login appear to succeed while every request after it returns 401."
+    - "BACKEND_WS_URL and NEXT_PUBLIC_AUTH_ENABLED were never read by any code and are gone from the env examples. If your deployment sets them, the browser-facing WebSocket origin is NEXT_PUBLIC_WS_URL (build-time)."

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-fullstack"
-version = "0.2.17"
+version = "0.2.18"
 description = "Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability."
 readme = "README.md"
 requires-python = ">=3.11"

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/hooks/post_gen_project.py

@@ -623,19 +623,26 @@ else:
                 "# Backend API URL (server-side only - not exposed to browser)",
                 "BACKEND_URL=http://localhost:{{ cookiecutter.backend_port }}",
                 "",
-                "# WebSocket URL for real-time features",
-                "BACKEND_WS_URL=ws://localhost:{{ cookiecutter.backend_port }}",
+                "# Send the auth cookies with the Secure flag. Unset follows NODE_ENV,",
+                "# so production means Secure — and a browser discards a Secure cookie",
+                "# served over plain http://, which logs you in and then 401s every",
+                "# request after it. Only set false for http:// on a trusted network.",
+                "# COOKIE_SECURE=false",
+                "",
+                "# WebSocket URL for the chat stream. Read by the BROWSER, so it must",
+                "# be an address the browser can reach — and NEXT_PUBLIC_* is inlined",
+                "# at build time, so in Docker it has to be passed as a build arg.",
+                "NEXT_PUBLIC_WS_URL=ws://localhost:{{ cookiecutter.backend_port }}",
+                "",
+                "# Public API URL, exposed to the browser (OAuth redirects, API docs",
+                "# links). Same build-time rule as NEXT_PUBLIC_WS_URL above.",
+                "NEXT_PUBLIC_API_URL=http://localhost:{{ cookiecutter.backend_port }}",
                 "",
                 "# Canonical site URL — used for SEO metadata, OG tags, sitemap.xml,",
                 "# robots.txt, schema.org organization. Override in production with",
                 "# the real https origin.",
                 "NEXT_PUBLIC_SITE_URL=http://localhost:{{ cookiecutter.frontend_port }}",
             ]
-            env_lines.extend([
-                "",
-                "# Authentication (always enabled)",
-                "NEXT_PUBLIC_AUTH_ENABLED=true",
-            ])
             if enable_oauth:
                 # Build the comma-separated provider list the OAuth buttons read.
                 # Currently only Google has full backend wiring; expand here when
@@ -644,9 +651,6 @@ else:
                 if "{{ cookiecutter.enable_oauth_google }}" == "True":
                     providers.append("google")
                 env_lines.extend([
-                    "",
-                    "# Public API URL for OAuth redirects (exposed to browser)",
-                    "NEXT_PUBLIC_API_URL=http://localhost:{{ cookiecutter.backend_port }}",
                     "",
                     "# OAuth providers shown on /login + /register (comma-separated).",
                     "# Drives the <OAuthButtons> component — must include only providers",
@@ -670,8 +674,10 @@ else:
             if "{{ cookiecutter.enable_brand_from_config }}" == "True":
                 env_lines.extend([
                     "",
-                    "# Runtime brand override (white-label)",
-                    "# Set NEXT_PUBLIC_BRAND_COLOR to one of: blue, green, red, violet, orange",
+                    "# Brand override (white-label). NEXT_PUBLIC_* is inlined at build",
+                    "# time, so changing these needs a rebuild — in Docker they are",
+                    "# passed as build args (see docker-compose.frontend.yml).",
+                    "# NEXT_PUBLIC_BRAND_COLOR: blue, green, red, violet or orange",
                     "NEXT_PUBLIC_BRAND_COLOR={{ cookiecutter.brand_color }}",
                     "NEXT_PUBLIC_BRAND_LOGO_URL=",
                 ])

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/ENV_VARS.md

@@ -174,6 +174,19 @@ group is for and which are required vs optional.
 | `S3_REGION` | optional | `us-east-1` | AWS region |
 {%- endif %}
 
+{%- if cookiecutter.use_frontend %}
+
+## Frontend (`frontend/.env.local`)
+
+Separate from the backend `.env` above — `frontend/README.md` has the full table.
+The two that decide whether a deployment works at all:
+
+| Variable | Read by | Description |
+|---|---|---|
+| `NEXT_PUBLIC_WS_URL` | browser | WebSocket origin for chat. Inlined at **build** time, so it needs a rebuild to change, and it must be an address the browser can reach — not a Docker service name |
+| `COOKIE_SECURE` | server | `Secure` flag on the auth cookies. Unset follows `NODE_ENV`. A browser drops a `Secure` cookie served over plain `http://`, which makes every request after login return 401 — set `false` only for `http://` on a trusted network |
+{%- endif %}
+
 ## Validation
 
 ```bash

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/Makefile

@@ -387,10 +387,9 @@ vercel-deploy:
 	@echo "✅ Frontend deployed to Vercel!"
 	@echo "   Set environment variables in Vercel dashboard:"
 	@echo "   BACKEND_URL=https://api.your-domain.com"
-	@echo "   BACKEND_WS_URL=wss://api.your-domain.com"
-{%- if cookiecutter.use_jwt %}
-	@echo "   NEXT_PUBLIC_AUTH_ENABLED=true"
-{%- endif %}
+	@echo "   NEXT_PUBLIC_API_URL=https://api.your-domain.com"
+	@echo "   NEXT_PUBLIC_WS_URL=wss://api.your-domain.com"
+	@echo "   NEXT_PUBLIC_SITE_URL=https://your-domain.com"
 {%- if cookiecutter.enable_rag %}
 	@echo "   NEXT_PUBLIC_RAG_ENABLED=true"
 {%- endif %}

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/README.md

@@ -318,7 +318,7 @@ bun run lint
 bun run build
 ```
 
-The frontend talks to the backend through Next.js API route handlers in `src/app/api/*` (server-side proxy that forwards auth cookies to the FastAPI backend). Direct calls to `localhost:{{ cookiecutter.backend_port }}` from the browser are deliberately avoided.
+The frontend talks to the backend through Next.js API route handlers in `src/app/api/*` (server-side proxy that forwards auth cookies to the FastAPI backend), so HTTP traffic never leaves the frontend origin. The one exception is the chat WebSocket: the browser opens it straight against the backend at `NEXT_PUBLIC_WS_URL`, so that origin must be reachable from the browser and the backend port (or a proxy route to it) has to be exposed.
 
 i18n (PL + EN) ships out of the box via `next-intl`. Add a new locale by extending `messages/<lang>.json` and `src/i18n.ts`.
 {%- endif %}
@@ -335,13 +335,18 @@ cd frontend && npx vercel --prod
 
 Set in the Vercel dashboard:
 
-- `BACKEND_URL` = `https://api.your-domain.com`
-- `BACKEND_WS_URL` = `wss://api.your-domain.com`
-- `NEXT_PUBLIC_AUTH_ENABLED` = `true`
+- `BACKEND_URL` = `https://api.your-domain.com` (server-side only)
+- `NEXT_PUBLIC_API_URL` = `https://api.your-domain.com`
+- `NEXT_PUBLIC_WS_URL` = `wss://api.your-domain.com`
+- `NEXT_PUBLIC_SITE_URL` = `https://your-domain.com`
 {%- if cookiecutter.enable_rag %}
 - `NEXT_PUBLIC_RAG_ENABLED` = `true`
 {%- endif %}
 
+`NEXT_PUBLIC_*` values are inlined into the browser bundle at build time, so
+changing one needs a redeploy, and each must be an address the **browser** can
+reach.
+
 ### Backend → your server
 
 ```bash

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/backend/app/agents/deepagents_assistant.py

@@ -25,11 +25,10 @@ Configuration via settings:
 """
 
 import logging
-from collections.abc import Callable
 from typing import Any, TypedDict
 
 from deepagents import create_deep_agent
-from deepagents.backends import StateBackend
+from deepagents.backends import BackendProtocol, StateBackend
 from langchain_core.language_models import BaseChatModel
 from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
 {%- if cookiecutter.enable_rag or cookiecutter.enable_web_search or cookiecutter.web_fetch_tool or cookiecutter.enable_charts %}
@@ -307,13 +306,17 @@ class DeepAgentsAssistant:
         self._graph = None
         self._checkpointer = MemorySaver()
 
-    def _create_backend(self) -> Callable:
+    def _create_backend(self) -> BackendProtocol:
         """Create the file-storage backend.
 
+        `create_deep_agent` takes a backend instance, and StateBackend reads the
+        current run's state out of the LangGraph config itself, so it needs no
+        constructor argument.
+
         Returns:
-            BackendFactory (callable) for StateBackend (in-memory, ephemeral).
+            StateBackend (in-memory file state, ephemeral, no external deps).
         """
-        return lambda rt: StateBackend(rt)
+        return StateBackend()
 
     def _create_model(self) -> BaseChatModel:
         """Create the LLM model for DeepAgents."""

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/backend/app/clients/redis.py

@@ -39,10 +39,18 @@ class RedisClient:
             self.client = None
 
     async def get(self, key: str) -> str | None:
-        """Get a value by key."""
+        """Get a value by key.
+
+        `connect()` sets decode_responses=True, so the value comes back decoded —
+        but redis-py's annotation cannot express that and still admits `bytes`.
+        Decode explicitly rather than asserting the flag through a type: ignore.
+        """
         if not self.client:
             raise RuntimeError("Redis client not connected")
-        return await self.client.get(key)  # type: ignore[no-any-return]
+        value: str | bytes | None = await self.client.get(key)
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+        return value
 
     async def set(
         self,

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/backend/pyproject.toml

@@ -75,7 +75,13 @@ dependencies = [
     "aiosmtplib>=3.0.0",
 {%- endif %}
 {%- if cookiecutter.enable_pagination %}
-    "fastapi-pagination>=0.12.31",
+    # 0.15.16 is broken against every FastAPI without the private _get_body_field
+    # helpers (i.e. anything below 0.140.5, which includes the pin above): its
+    # ImportError fallback binds the public get_body_field but still sets
+    # _get_body_field_new_signature = True, so add_pagination() calls it with a
+    # body_params kwarg it does not accept and the app dies on import. Lift the
+    # cap once upstream fixes the fallback or the FastAPI pin moves past 0.140.5.
+    "fastapi-pagination>=0.12.31,<0.15.16",
 {%- endif %}
 {%- if cookiecutter.enable_sentry %}
     "sentry-sdk[fastapi]>=2.53.0",
@@ -154,7 +160,11 @@ dependencies = [
     "langgraph-checkpoint>=4.0.0",
 {%- endif %}
 {%- if cookiecutter.use_deepagents %}
-    "deepagents>=0.1.0",
+    # Capped: the backend API is still moving between minors (0.7 dropped the
+    # runtime argument from StateBackend and switched create_deep_agent to take
+    # an instance instead of a factory), so an unbounded pin breaks generation
+    # on release day.
+    "deepagents>=0.7.1,<0.8",
 {%- if cookiecutter.use_openai %}
     "langchain-openai>=1.1.0",
 {%- endif %}

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/docker-compose.dev.yml

@@ -162,7 +162,7 @@ services:
     restart: unless-stopped
 
   milvus:
-    image: milvusdb/milvus:v2.6.21
+    image: milvusdb/milvus:v2.6.22
     container_name: {{ cookiecutter.project_slug }}_milvus
     command: ["milvus", "run", "standalone"]
     ports:

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/docker-compose.frontend.yml

@@ -11,26 +11,32 @@ services:
       context: ./frontend
       dockerfile: Dockerfile
       args:
-        # NEXT_PUBLIC_* are baked into the browser bundle at build time. The
-        # browser runs on the host, so it reaches the backend on localhost.
-        - NEXT_PUBLIC_API_URL=http://localhost:{{ cookiecutter.backend_port }}
-        - NEXT_PUBLIC_WS_URL=ws://localhost:{{ cookiecutter.backend_port }}
-        - NEXT_PUBLIC_SITE_URL=http://localhost:{{ cookiecutter.frontend_port }}
+        # NEXT_PUBLIC_* are baked into the browser bundle at build time, so a
+        # runtime `environment:` entry cannot change them — after editing these
+        # you must rebuild: docker compose -f docker-compose.frontend.yml build
+        # --no-cache frontend. They must point at an address the BROWSER can
+        # reach; the defaults assume the browser runs on the Docker host. When
+        # you open the app from another machine, set PUBLIC_HOST to this host's
+        # address (e.g. PUBLIC_HOST=10.0.0.5) or override each URL directly.
+        - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-http://${PUBLIC_HOST:-localhost}:{{ cookiecutter.backend_port }}}
+        - NEXT_PUBLIC_WS_URL=${NEXT_PUBLIC_WS_URL:-ws://${PUBLIC_HOST:-localhost}:{{ cookiecutter.backend_port }}}
+        - NEXT_PUBLIC_SITE_URL=${NEXT_PUBLIC_SITE_URL:-http://${PUBLIC_HOST:-localhost}:{{ cookiecutter.frontend_port }}}
         - NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB=50
 {%- if cookiecutter.enable_oauth %}
         - NEXT_PUBLIC_OAUTH_PROVIDERS={% if cookiecutter.enable_oauth_google %}google{% endif %}
 {%- endif %}
         - NEXT_PUBLIC_RAG_ENABLED={% if cookiecutter.enable_rag %}true{% else %}false{% endif %}
+{%- if cookiecutter.enable_brand_from_config %}
+        - NEXT_PUBLIC_BRAND_COLOR=${NEXT_PUBLIC_BRAND_COLOR:-{{ cookiecutter.brand_color }}}
+        - NEXT_PUBLIC_BRAND_LOGO_URL=${NEXT_PUBLIC_BRAND_LOGO_URL:-}
+{%- endif %}
     container_name: {{ cookiecutter.project_slug }}_frontend
     ports:
       - "{{ cookiecutter.frontend_port }}:{{ cookiecutter.frontend_port }}"
     environment:
       - NODE_ENV=development
-      - BACKEND_URL=http://host.docker.internal:{{ cookiecutter.backend_port }}
-      - BACKEND_WS_URL=ws://host.docker.internal:{{ cookiecutter.backend_port }}
-{%- if cookiecutter.enable_rag %}
-      - NEXT_PUBLIC_RAG_ENABLED=true
-{%- endif %}
+      # Server-side only: resolved inside this container, never by the browser.
+      - BACKEND_URL=${BACKEND_URL:-http://host.docker.internal:{{ cookiecutter.backend_port }}}
     extra_hosts:
       - "host.docker.internal:host-gateway"
     restart: unless-stopped

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/docker-compose.prod.yml

@@ -313,7 +313,7 @@ services:
           memory: 256M
 
   milvus:
-    image: milvusdb/milvus:v2.6.21
+    image: milvusdb/milvus:v2.6.22
     container_name: {{ cookiecutter.project_slug }}_milvus
     command: ["milvus", "run", "standalone"]
     # NO external ports - only accessible within backend-internal network
@@ -655,11 +655,44 @@ services:
     build:
       context: ./frontend
       dockerfile: Dockerfile
+      # NEXT_PUBLIC_* are inlined into the browser bundle at build time, so they
+      # must be build args — an `environment:` entry cannot override them, and
+      # changing one needs a rebuild (docker compose -f docker-compose.prod.yml
+      # build --no-cache frontend). Every value here has to be reachable from
+      # the BROWSER, not from inside the compose network.
+      args:
+{%- if cookiecutter.include_traefik_labels or cookiecutter.include_nginx_service %}
+        # The proxy terminates TLS and serves the backend on api.DOMAIN.
+        - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-https://api.${DOMAIN:-localhost}}
+        - NEXT_PUBLIC_WS_URL=${NEXT_PUBLIC_WS_URL:-wss://api.${DOMAIN:-localhost}}
+        - NEXT_PUBLIC_SITE_URL=${NEXT_PUBLIC_SITE_URL:-https://${DOMAIN:-localhost}}
+{%- else %}
+        # No proxy in front, so the browser talks to the published ports.
+        # Set PUBLIC_HOST to this host's address — the localhost default only
+        # works when the browser runs on the Docker host itself.
+        - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL:-http://${PUBLIC_HOST:-localhost}:{{ cookiecutter.backend_port }}}
+        - NEXT_PUBLIC_WS_URL=${NEXT_PUBLIC_WS_URL:-ws://${PUBLIC_HOST:-localhost}:{{ cookiecutter.backend_port }}}
+        - NEXT_PUBLIC_SITE_URL=${NEXT_PUBLIC_SITE_URL:-http://${PUBLIC_HOST:-localhost}:{{ cookiecutter.frontend_port }}}
+{%- endif %}
+        - NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB=${NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB:-50}
+{%- if cookiecutter.enable_oauth %}
+        - NEXT_PUBLIC_OAUTH_PROVIDERS={% if cookiecutter.enable_oauth_google %}google{% endif %}
+{%- endif %}
+        - NEXT_PUBLIC_RAG_ENABLED={% if cookiecutter.enable_rag %}true{% else %}false{% endif %}
+{%- if cookiecutter.enable_brand_from_config %}
+        - NEXT_PUBLIC_BRAND_COLOR=${NEXT_PUBLIC_BRAND_COLOR:-{{ cookiecutter.brand_color }}}
+        - NEXT_PUBLIC_BRAND_LOGO_URL=${NEXT_PUBLIC_BRAND_LOGO_URL:-}
+{%- endif %}
     container_name: {{ cookiecutter.project_slug }}_frontend
     environment:
       - NODE_ENV=production
+      # Server-side only: resolved inside the compose network by the Next server.
       - BACKEND_URL=http://app:{{ cookiecutter.backend_port }}
-      - BACKEND_WS_URL=ws://app:{{ cookiecutter.backend_port }}
+      # The auth cookies are Secure in production, and a browser discards a
+      # Secure cookie that arrives over plain HTTP — login then "works" while
+      # every request after it is 401. Serve this over TLS, or set
+      # COOKIE_SECURE=false if it really is http:// on a trusted network.
+      - COOKIE_SECURE=${COOKIE_SECURE:-true}
 {%- if cookiecutter.include_traefik_labels %}
     networks:
       - traefik-public

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/docker-compose.yml

@@ -164,7 +164,7 @@ services:
     restart: unless-stopped
 
   milvus:
-    image: milvusdb/milvus:v2.6.21
+    image: milvusdb/milvus:v2.6.22
     container_name: {{ cookiecutter.project_slug }}_milvus
     command: ["milvus", "run", "standalone"]
     ports:

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/docs/deploy.md

@@ -32,10 +32,45 @@ curl http://localhost:{{ cookiecutter.backend_port }}/api/v1/health
 {% if cookiecutter.use_frontend %}# Frontend: http://localhost:{{ cookiecutter.frontend_port }}{% endif %}
 ```
 
+{% if cookiecutter.use_frontend %}
+### Serving from a host that isn't localhost
+
+The defaults assume the browser runs on the Docker host. Opening the app from
+another machine (a LAN IP, a staging box, a tunnel) needs two things set, and
+both fail in a way that looks like something else:
+
+```bash
+# In the .env next to docker-compose.prod.yml
+PUBLIC_HOST=10.0.0.5     # an address the BROWSER can reach
+COOKIE_SECURE=false      # ONLY if you serve over plain http:// (see below)
+```
+
+```bash
+# NEXT_PUBLIC_* is inlined into the bundle, so this needs a real rebuild
+docker compose -f docker-compose.prod.yml build --no-cache frontend
+docker compose -f docker-compose.prod.yml up -d frontend
+```
+
+1. **`NEXT_PUBLIC_*` is baked in at build time.** Next.js inlines those values
+   into the JavaScript the browser downloads, so a runtime env var cannot change
+   them — `docker-compose.prod.yml` passes them as `build:` args instead. Miss
+   this and the chat socket dials `ws://localhost:{{ cookiecutter.backend_port }}` from
+   the visitor's own machine and the input stays disabled ("Offline").
+2. **The auth cookies are `Secure` in production, and a browser silently drops a
+   `Secure` cookie that arrives over `http://`.** Login looks like it worked (the
+   user comes back in the response body) and then every request carrying no
+   cookie answers 401, `/api/auth/me` included, so the token never refreshes.
+   TLS is the real fix; `COOKIE_SECURE=false` is the escape hatch for a trusted
+   network.
+
+Reaching the backend matters too: the chat socket is opened by the browser
+directly against `NEXT_PUBLIC_WS_URL`, so either publish the backend port or
+route `/api/v1/ws` through your proxy with the `Upgrade` headers set.
+{% endif %}
 ### Reverse proxy
 
 {%- if cookiecutter.use_nginx %}
-Nginx config in `nginx/` proxies `/` → frontend, `/api` → backend, `/ws` → backend WebSocket. Update `server_name` and TLS cert paths in `nginx/conf.d/app.conf`.
+Nginx config in `nginx/nginx.conf` proxies `/` → frontend, `/` on `api.DOMAIN` → backend, and `/api/v1/ws` → backend WebSocket. Update `server_name` and the TLS cert paths there.
 {%- elif cookiecutter.use_traefik %}
 Traefik labels in `docker-compose.yml` route based on `Host()`. Set `DOMAIN` env var, then point your DNS at the host. ACME / Let's Encrypt configured via labels — uncomment in `docker-compose.yml` and set `ACME_EMAIL`.
 {%- else %}
@@ -108,7 +143,9 @@ cd frontend
 vercel
 ```
 
-Set `BACKEND_URL` and `NEXT_PUBLIC_API_URL` env vars in Vercel dashboard pointing to your backend host.
+Set `BACKEND_URL`, `NEXT_PUBLIC_API_URL`, `NEXT_PUBLIC_WS_URL` (`wss://…`) and
+`NEXT_PUBLIC_SITE_URL` in the Vercel dashboard, pointing at your backend host,
+then redeploy — the `NEXT_PUBLIC_*` ones are only picked up by a fresh build.
 {% else %}
 Not applicable — this project doesn't generate a frontend.
 {% endif %}

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/docs/permissions.md

@@ -51,7 +51,7 @@ These are defined in `app/api/deps.py` and used throughout the route layer:
 
 | Endpoint | Method | Admin | User | Notes |
 |----------|--------|-------|------|-------|
-| `/agent/ws/agent` | WS | Y | Y | WebSocket chat with AI agent |
+| `/ws/agent` | WS | Y | Y | WebSocket chat with AI agent |
 
 ### Conversations
 

fastapi_fullstack-0.2.18/template/{{cookiecutter.project_slug}}/frontend/.env.example

@@ -0,0 +1,31 @@
+# Backend API URL (server-side only - not exposed to browser)
+BACKEND_URL=http://localhost:{{ cookiecutter.backend_port }}
+
+# Send the auth cookies with the Secure flag. Unset follows NODE_ENV, so
+# production means Secure — and a browser silently discards a Secure cookie
+# served over plain http://, which logs you in and then 401s every request
+# after it. Only set this to false for an http:// deployment on a trusted
+# network; the real fix is to serve the app over TLS.
+# COOKIE_SECURE=false
+
+# WebSocket URL for the chat stream. Read by the BROWSER, so it must be an
+# address the browser can reach (not a Docker service name), and because
+# NEXT_PUBLIC_* is inlined at build time it has to be set before `bun run
+# build` — in Docker that means a build arg, see docker-compose.frontend.yml.
+NEXT_PUBLIC_WS_URL=ws://localhost:{{ cookiecutter.backend_port }}
+
+# Public API URL, exposed to the browser (OAuth redirects, links to the API
+# docs). Same build-time rule as NEXT_PUBLIC_WS_URL above.
+NEXT_PUBLIC_API_URL=http://localhost:{{ cookiecutter.backend_port }}
+{%- if cookiecutter.enable_rag %}
+
+# RAG (Retrieval Augmented Generation)
+NEXT_PUBLIC_RAG_ENABLED=true
+{%- endif %}
+{%- if cookiecutter.enable_logfire %}
+
+# Logfire/OpenTelemetry (server-side instrumentation)
+# Get your write token from: https://logfire.pydantic.dev
+OTEL_EXPORTER_OTLP_ENDPOINT=https://logfire-api.pydantic.dev
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=your-logfire-write-token
+{%- endif %}

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/frontend/Dockerfile

@@ -36,6 +36,12 @@ ENV NEXT_PUBLIC_OAUTH_PROVIDERS=$NEXT_PUBLIC_OAUTH_PROVIDERS
 {%- endif %}
 ARG NEXT_PUBLIC_RAG_ENABLED=false
 ENV NEXT_PUBLIC_RAG_ENABLED=$NEXT_PUBLIC_RAG_ENABLED
+{%- if cookiecutter.enable_brand_from_config %}
+ARG NEXT_PUBLIC_BRAND_COLOR={{ cookiecutter.brand_color }}
+ENV NEXT_PUBLIC_BRAND_COLOR=$NEXT_PUBLIC_BRAND_COLOR
+ARG NEXT_PUBLIC_BRAND_LOGO_URL=
+ENV NEXT_PUBLIC_BRAND_LOGO_URL=$NEXT_PUBLIC_BRAND_LOGO_URL
+{%- endif %}
 
 # Build the application
 ENV NEXT_TELEMETRY_DISABLED=1

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/frontend/README.md

@@ -21,18 +21,30 @@ Or run it in Docker from the project root: `make dev-frontend`.
 
 Copy `.env.example` to `.env.local` and adjust as needed:
 
-| Variable | Description |
-|----------|-------------|
-| `BACKEND_URL` | Backend HTTP base URL (server-side calls / proxying) |
-| `BACKEND_WS_URL` | Backend WebSocket URL for the chat stream |
-| `NEXT_PUBLIC_AUTH_ENABLED` | Toggle auth UI (`true` when JWT/OAuth is enabled) |
+| Variable | Read by | Description |
+|----------|---------|-------------|
+| `BACKEND_URL` | server | Backend HTTP base URL used by the route handlers in `src/app/api/*` |
+| `COOKIE_SECURE` | server | `Secure` flag on the auth cookies. Unset follows `NODE_ENV`; set `false` only for an `http://` deployment on a trusted network |
+| `NEXT_PUBLIC_WS_URL` | browser | Backend WebSocket origin for the chat stream (e.g. `wss://api.example.com`) |
+| `NEXT_PUBLIC_API_URL` | browser | Public API URL (OAuth redirects, links to the API docs) |
+| `NEXT_PUBLIC_SITE_URL` | browser | Canonical site origin for SEO metadata, OG tags, `sitemap.xml` |
 {%- if cookiecutter.enable_oauth %}
-| `NEXT_PUBLIC_API_URL` | Public API URL used by OAuth redirects |
+| `NEXT_PUBLIC_OAUTH_PROVIDERS` | browser | Comma-separated providers shown on `/login` + `/register` |
 {%- endif %}
 {%- if cookiecutter.enable_rag %}
-| `NEXT_PUBLIC_RAG_ENABLED` | Show knowledge-base / RAG UI |
+| `NEXT_PUBLIC_RAG_ENABLED` | browser | Show knowledge-base / RAG UI |
 {%- endif %}
 
+Two rules that cause most of the deployment confusion:
+
+- **`NEXT_PUBLIC_*` is inlined into the browser bundle at build time.** Setting one
+  at runtime does nothing — you have to set it before `bun run build`, which in
+  Docker means a `build:` arg (see `docker-compose.frontend.yml`) followed by a
+  rebuild. Everything else in the table is read at runtime.
+- **`NEXT_PUBLIC_*` values must be reachable from the browser**, so never a Docker
+  service name. `BACKEND_URL` is the opposite: it is resolved inside the
+  container, so a service name is exactly right there.
+
 ## Scripts
 
 ```bash
@@ -71,5 +83,8 @@ Add a locale by extending `i18n.ts` and providing its message catalog.
 npx vercel --prod
 ```
 
-In the Vercel dashboard set `BACKEND_URL`, `BACKEND_WS_URL`, and
-`NEXT_PUBLIC_AUTH_ENABLED=true`. See the project root `docs/deploy.md` for details.
+In the Vercel dashboard set `BACKEND_URL=https://api.your-domain.com`,
+`NEXT_PUBLIC_API_URL=https://api.your-domain.com`, `NEXT_PUBLIC_WS_URL=wss://api.your-domain.com`
+and `NEXT_PUBLIC_SITE_URL=https://your-domain.com`, then redeploy — the
+`NEXT_PUBLIC_*` ones only take effect on a fresh build. See the project root
+`docs/deploy.md` for details.

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/frontend/src/app/api/auth/login/route.ts

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { setAuthCookies } from "@/lib/auth-cookies";
 import { backendFetch, BackendApiError } from "@/lib/server-api";
 import type { LoginResponse } from "@/types";
 
@@ -31,20 +32,9 @@ export async function POST(request: NextRequest) {
       message: "Login successful",
     });
 
-    response.cookies.set("access_token", data.access_token, {
-      httpOnly: true,
-      secure: process.env.NODE_ENV === "production",
-      sameSite: "lax",
-      maxAge: 60 * 15, // 15 minutes
-      path: "/",
-    });
-
-    response.cookies.set("refresh_token", data.refresh_token, {
-      httpOnly: true,
-      secure: process.env.NODE_ENV === "production",
-      sameSite: "lax",
-      maxAge: 60 * 60 * 24 * 7, // 7 days
-      path: "/",
+    setAuthCookies(response, {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
     });
 
     return response;

{fastapi_fullstack-0.2.17 → fastapi_fullstack-0.2.18}/template/{{cookiecutter.project_slug}}/frontend/src/app/api/auth/logout/route.ts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from "next/server";
 
+import { clearAuthCookies } from "@/lib/auth-cookies";
 import { backendFetch, BackendApiError } from "@/lib/server-api";
 
 export async function POST(request: NextRequest) {
@@ -22,20 +23,7 @@ export async function POST(request: NextRequest) {
 
   const response = NextResponse.json({ message: "Logged out successfully" });
 
-  response.cookies.set("access_token", "", {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === "production",
-    sameSite: "lax",
-    maxAge: 0,
-    path: "/",
-  });
-  response.cookies.set("refresh_token", "", {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === "production",
-    sameSite: "lax",
-    maxAge: 0,
-    path: "/",
-  });
+  clearAuthCookies(response);
 
   return response;
 }