build(docker)!: add dev compose + watch; harden prod compose; Next.js standalone runtime

- Makefile
  - Added `compose-watch` using `docker-compose.dev.yml` with `--watch --build`
  - Added `compose-watch-down` to stop dev stack and remove orphans
  - `compose-down` now uses `--remove-orphans` (safer than `-v`)
  - `run-db` starts Postgres from `docker-compose.dev.yml`

- Backend image
  - Set `PYTHONPATH=/app`; copy `pyproject.toml` to expose app version
  - Switch CMD to `.venv/bin/uvicorn` for hermetic runtime
  - Keep non-root user; tidy ownership and entrypoint usage

- Alembic & settings
  - Default DSN in `alembic.ini` simplified
  - Drop manual `sys.path.append` (rely on `PYTHONPATH`)
  - Add `db_echo` to `Settings`; engine `echo` reads `DB_ECHO`

- Entrypoint
  - Robust Alembic loop with retries; gate via `RUN_MIGRATIONS=1`

- Compose
  - New `docker-compose.dev.yml` with mounts and hot-reload (backend & frontend)
  - Production `docker-compose.yml`:
    - DB network set `internal: true`; Postgres port no longer published
    - Backend uses fixed container port 5432 in DSN
    - Frontend builds from `runner` target

- Frontend
  - Dockerfile: pnpm multi-stage (`deps` → `builder` → `runner`), non-root user
  - Next.js `output: 'standalone'`; remove console in prod; ESM export of config
  - Tailwind config path now `tailwind.config.ts`
  - `/api/version`: load from `~/package.json`
  - `FileUpload`: move `cursor-pointer` to the Button

BREAKING CHANGE: Default `docker-compose.yml` is production-oriented. Postgres is no longer exposed
to the host and the DB network is internal. Use `docker-compose.dev.yml` (e.g., `make compose-watch`
or `make run-db`) for local development with hot reload. Update any host-based DB tooling to connect
via the dev compose file or through the container network.

Author: github-actions

Makefile

@@ -19,6 +19,9 @@ help:
 	@echo "  alembic-up      Apply migrations (upgrade head)"
 	@echo "  compose-up      docker compose up --build"
 	@echo "  compose-down    docker compose down -v"
+	@echo "  compose-watch   docker compose up --watch --build (dev)"
+	@echo "  compose-down-watch docker compose down --remove-orphans (dev)"
+	@echo "  run-db          Start Postgres database (docker compose up -d postgres
 	@echo "  frontend-install Install frontend deps with pnpm"
 	@echo "  frontend-dev     Run Next.js dev server"
 	@echo "  frontend-build   Build Next.js production bundle"
@@ -51,7 +54,6 @@ run-backend: uv-setup uv-update
 	[ -f "$$HOME/.local/bin/env" ] && . "$$HOME/.local/bin/env" || true; export PATH="$$HOME/.local/bin:$$PATH"; \
 	cd backend && $(UV) run uvicorn app.main:app --reload
 
-
 .PHONY: alembic-rev
 alembic-rev: uv-setup
 	@if [ -z "$(AUTOGEN)" ]; then echo "Usage: make alembic-rev AUTOGEN=message"; exit 1; fi
@@ -70,14 +72,18 @@ compose-up:
 
 .PHONY: compose-down
 compose-down:
-	@echo "[docker] Stopping and removing services + volumes"
-	docker compose down -v
+	@echo "[docker] Stopping and removing services + orphans"
+	docker compose down --remove-orphans
 
-# Add docker watchers for frontend and backend
 .PHONY: compose-watch
 compose-watch:
 	@echo "[docker] Building and starting services with watchers"
-	docker compose up --watch --build
+	docker compose -f docker-compose.dev.yml up --watch --build
+
+.PHONY: compose-watch-down
+compose-watch-down:
+	@echo "[docker] Stopping and removing services + orphans"
+	docker compose -f docker-compose.dev.yml down --remove-orphans
 
 # Frontend (pnpm) helpers
 .PHONY: frontend-install
@@ -108,4 +114,4 @@ frontend-typecheck: frontend-install
 .PHONY: run-db
 run-db:
 	@echo "[docker] Starting Postgres database"
-	docker compose up -d postgres
+	docker compose -f docker-compose.dev.yml up -d postgres

backend/Dockerfile

@@ -2,9 +2,11 @@
 
 # 1) Builder stage: install uv and resolve dependencies once
 FROM python:3.13-slim AS builder
+
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     UV_LINK_MODE=copy
+
 WORKDIR /app
 
 RUN apt-get update \
@@ -22,14 +24,17 @@ RUN --mount=type=cache,target=/root/.cache/uv uv sync --no-dev
 
 # 2) Runtime stage: copy only what we need and run as a non-root user
 FROM python:3.13-slim AS runtime
+
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1
+
 WORKDIR /app
 
 # Copy the virtual environment from builder and ensure it's used by default
 COPY --from=builder /app/.venv /app/.venv
 ENV VIRTUAL_ENV=/app/.venv
 ENV PATH="/app/.venv/bin:${PATH}"
+ENV PYTHONPATH=/app
 
 # Create an unprivileged user
 RUN useradd -u 10001 -r -m appuser
@@ -38,19 +43,21 @@ RUN useradd -u 10001 -r -m appuser
 COPY app /app/app
 COPY alembic.ini /app/alembic.ini
 COPY alembic /app/alembic
+# Required to get application version
+COPY pyproject.toml /app/pyproject.toml
 
 # Adjust ownership so the non-root user can access files
 RUN chown -R appuser:appuser /app
-USER appuser
 
 # Expose the backend port
 EXPOSE 8000
 
 # Add and use an entrypoint to handle DB wait + migrations
-USER root
 COPY --chown=appuser:appuser entrypoint.sh /app/entrypoint.sh
 RUN chmod +x /app/entrypoint.sh
+
+# Switch to the non-root user
 USER appuser
 
 ENTRYPOINT ["/app/entrypoint.sh"]
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD [".venv/bin/uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/alembic.ini

@@ -3,7 +3,7 @@
 script_location = alembic
 
 # This value is overridden by env.py using Settings.DATABASE_URL
-sqlalchemy.url = postgresql+psycopg://budget_user:budget_pass@localhost:5432/budget_db
+sqlalchemy.url = postgresql+psycopg://user:pass@localhost:5432/db
 
 [loggers]
 keys = root

backend/alembic/env.py

@@ -17,7 +17,7 @@
 from sqlalchemy import engine_from_config, pool
 from sqlmodel import SQLModel
 
-sys.path.append(str(Path(__file__).resolve().parents[1] / "app"))  # noqa: E402
+# sys.path.append(str(Path(__file__).resolve().parents[1] / "app"))  # noqa: E402
 
 from app.core.config import get_settings  # noqa: E402
 import app.models.transaction  # noqa: F401  # ensure Transaction model is loaded

backend/app/core/config.py

@@ -23,6 +23,7 @@ class Settings(BaseSettings):
     # Database URL in SQLAlchemy format
     # Example: postgresql+psycopg://user:password@localhost:5432/budget_db
     database_url: str = "sqlite:///./budget_wise.db"
+    db_echo: bool = True
 
 
 @lru_cache()

backend/app/db/session.py

@@ -19,7 +19,7 @@
 # environment variables.
 engine = create_engine(
     settings.database_url,
-    echo=True,
+    echo=settings.db_echo,
     pool_pre_ping=True,
 )
 

backend/entrypoint.sh

@@ -3,40 +3,21 @@ set -eu
 
 echo "[entrypoint] Starting backend container..."
 
-# Optional: wait for the database to be ready if DATABASE_URL is provided
-if [ -n "${DATABASE_URL:-}" ]; then
-  echo "[entrypoint] Waiting for database to be ready..."
-  python - <<'PY'
-import os, sys, time
-try:
-    import psycopg
-except Exception as e:
-    # psycopg not installed? skip wait
-    print("[entrypoint] psycopg not available; skipping DB wait", flush=True)
-    sys.exit(0)
+RUN_MIGRATIONS=${RUN_MIGRATIONS:-1}
 
-url = os.environ.get("DATABASE_URL")
-if not url:
-    sys.exit(0)
-
-max_attempts = 30
-for i in range(max_attempts):
-    try:
-        with psycopg.connect(url, connect_timeout=3) as conn:
-            print("[entrypoint] Database is ready.")
-            break
-    except Exception as e:
-        print(f"[entrypoint] DB not ready yet ({i+1}/{max_attempts}): {e}")
-        time.sleep(1)
-else:
-    print("[entrypoint] Database is still not ready after waiting; exiting.", file=sys.stderr)
-    sys.exit(1)
-PY
+if [ "$RUN_MIGRATIONS" = "1" ]; then
+  echo "[entrypoint] Running Alembic migrations..."
+  i=0
+  until alembic -c /app/alembic.ini upgrade head; do
+    i=$((i+1))
+    [ "$i" -ge 10 ] && { echo "[entrypoint] Migrations failed after retries. Exiting." >&2; exit 1; }
+    echo "[entrypoint] Alembic failed, retrying in 3s..."
+    sleep 3
+  done
+  echo "[entrypoint] Migrations applied."
+else
+  echo "[entrypoint] Skipping migrations (RUN_MIGRATIONS=$RUN_MIGRATIONS)."
 fi
 
-# Run migrations (if any)
-echo "[entrypoint] Applying migrations (if any)..."
-alembic upgrade head || echo "[entrypoint] No migrations to apply"
-
 echo "[entrypoint] Launching application: $@"
 exec "$@"

backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "budget-wise-backend"
-version = "0.3.0"
+version = "0.3.1"
 description = "FastAPI backend for BudgetWise"
 readme = "README.md"
 requires-python = ">=3.11"

docker-compose.dev.yml

@@ -0,0 +1,95 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: budgetwise-postgres
+    environment:
+      - POSTGRES_DB=${DB_NAME}
+      - POSTGRES_USER=${DB_USER}
+      - POSTGRES_PASSWORD=${DB_PASSWORD}
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "${DB_PORT:-5432}:5432"
+    networks:
+      - db-network
+
+  backend:
+    build: ./backend
+    container_name: budgetwise-backend
+    environment:
+      - DATABASE_URL=postgresql+psycopg://${DB_USER}:${DB_PASSWORD}@postgres:${DB_PORT:-5432}/${DB_NAME}
+      - PYTHONUNBUFFERED=1
+    volumes:
+      - ./backend:/app
+      - backend_venv:/app/.venv
+    ports:
+      - "8000:8000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    networks:
+      - db-network
+      - webapp
+    develop:
+      watch:
+        - action: restart
+          path: ./backend/app
+        - action: restart
+          path: ./backend/alembic
+        - action: restart
+          path: ./backend/alembic.ini
+        - action: rebuild
+          path: ./backend/pyproject.toml
+
+  # Dev: run Next.js with hot reload; mount the source
+  frontend:
+    build:
+      context: ./frontend
+      target: deps # deps stage has pnpm available
+    container_name: budgetwise-frontend
+    working_dir: /app
+    environment:
+      - API_BASE_URL=${API_BASE_URL}
+      - NEXT_TELEMETRY_DISABLED=1
+    command: sh -lc 'test -d node_modules ||
+              pnpm install --frozen-lockfile --yes;
+              pnpm dev'
+    volumes:
+      - ./frontend:/app
+      - frontend_node_modules:/app/node_modules
+    ports:
+      - "3000:3000"
+    depends_on:
+      - backend
+    networks:
+      - webapp
+    develop:
+      watch:
+        - action: restart
+          path: ./frontend
+          ignore:
+            - node_modules/
+            - .next/
+            - .turbo/
+            - .git/
+        - action: rebuild
+          path: ./frontend/pnpm-lock.yaml
+        - action: rebuild
+          path: ./frontend/package.json
+
+volumes:
+  postgres_data:
+  backend_venv:
+  frontend_node_modules:
+
+networks:
+  db-network:
+    driver: bridge
+    internal: false
+  webapp:
+    driver: bridge

docker-compose.yml

@@ -9,18 +9,16 @@ services:
     image: postgres:16-alpine
     container_name: budgetwise-postgres
     environment:
-      - POSTGRES_DB=${DB_NAME}
-      - POSTGRES_USER=${DB_USER}
-      - POSTGRES_PASSWORD=${DB_PASSWORD}
+      POSTGRES_DB: ${DB_NAME}
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
       interval: 5s
       timeout: 5s
       retries: 10
     volumes:
       - postgres_data:/var/lib/postgresql/data
-    ports:
-      - "${DB_PORT:-5432}:5432"
     networks:
       - db-network
 
@@ -29,12 +27,9 @@ services:
     container_name: budgetwise-backend
     environment:
       # PostgreSQL connection string (SQLAlchemy/SQLModel format)
-      - DATABASE_URL=postgresql+psycopg://${DB_USER}:${DB_PASSWORD}@postgres:${DB_PORT}/${DB_NAME}
-      - PYTHONUNBUFFERED=1
-    volumes:
-      # Mount the backend code to allow hot reloading in development.
-      # Comment out in production builds to improve performance.
-      - ./backend:/app
+      DB_ECHO: ${DB_ECHO:-false}
+      DATABASE_URL: postgresql+psycopg://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
+      PYTHONUNBUFFERED: 1
     ports:
       - "8000:8000"
     depends_on:
@@ -43,49 +38,21 @@ services:
     networks:
       - db-network
       - webapp
-    develop:
-      watch:
-        # Restart backend on source changes (bind mount already syncs files)
-        - action: restart
-          path: ./backend/app
-        - action: restart
-          path: ./backend/alembic
-        - action: restart
-          path: ./backend/alembic.ini
-        # Rebuild image when dependencies definition changes
-        - action: rebuild
-          path: ./backend/pyproject.toml
 
   frontend:
-    build: ./frontend
+    build: 
+      context: ./frontend
+      target: runner
     container_name: budgetwise-frontend
     environment:
       API_BASE_URL: ${API_BASE_URL}
-    volumes:
-      # Mount the frontend code to allow hot reloading in development.
-      # Comment out in production builds to improve performance.
-      - ./frontend:/app
+      NEXT_TELEMETRY_DISABLED: 1
     ports:
       - "3000:3000"
     depends_on:
       - backend
     networks:
       - webapp
-    develop:
-      watch:
-        # Restart frontend server on source/config updates
-        - action: restart
-          path: ./frontend
-          ignore:
-            - node_modules/
-            - .next/
-            - .turbo/
-            - .git/
-        # Rebuild image when lockfile or package manifest changes
-        - action: rebuild
-          path: ./frontend/pnpm-lock.yaml
-        - action: rebuild
-          path: ./frontend/package.json
 
 volumes:
   postgres_data:
@@ -94,6 +61,6 @@ volumes:
 networks:
   db-network:
     driver: bridge
-    internal: ${INTERNAL_DB_NETWORK:-false}
+    internal: true
   webapp:
     driver: bridge