feat: add docker-compose configuration for development environment

.env.example

@@ -20,6 +20,8 @@ IMAGE_TAG=latest
 # For staging (--profile=local-db): keep DB_HOST=dashboard_db.
 DB_HOST=dashboard_db
 DB_PORT=5432
+# Host port exposed by docker-compose.dev.yml for database clients.
+DB_PORT_PUBLISHED=5434
 DB_NAME=dashboard
 DB_USER=admin
 DB_PASSWORD=CHANGE_ME

.gitignore

@@ -1,12 +1,9 @@
 # Credentials
+dashboard/.tanstack/
 application_default_credentials.json
 .vscode
 .env
 .env.backend
-.env.ingester
-.env.db
-.env.pending_aggregations
-.env.proxy
 .idea
 
 # k6 data

Makefile

@@ -0,0 +1,62 @@
+DASHBOARD_DIR ?= dashboard
+BACKEND_DIR   ?= backend
+
+.DEFAULT_GOAL := help
+.PHONY: help setup install check-lint fix test build ci dev dev-build clean
+
+help: ## Show this help
+	@awk 'BEGIN{FS=":.*##"} /^[a-zA-Z0-9_.-]+:.*##/ {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+setup: ## Copy env files for Docker dev and manual backend workflows, then install dependencies
+	@test -f .env || (cp .env.example .env && echo "Created .env from .env.example")
+	@test -f .env.backend || (cp .env.backend.example .env.backend && echo "Created .env.backend from .env.backend.example")
+	@test -f $(DASHBOARD_DIR)/.env || (cp $(DASHBOARD_DIR)/.env.example $(DASHBOARD_DIR)/.env && echo "Created dashboard/.env from dashboard/.env.example")
+	$(MAKE) install
+
+install: ## Install dependencies (pnpm + poetry)
+	cd $(DASHBOARD_DIR) && pnpm install --frozen-lockfile
+	cd $(BACKEND_DIR) && poetry install
+
+check-lint: ## Run CI-equivalent lint checks (no autofix)
+	cd $(DASHBOARD_DIR) && pnpm lint-staged
+	cd $(BACKEND_DIR) && poetry run ruff check .
+	cd $(BACKEND_DIR) && poetry run ruff format --check .
+
+fix: ## Apply autofixes (lint, format, prettify)
+	cd $(DASHBOARD_DIR) && pnpm lint
+	cd $(BACKEND_DIR) && poetry run ruff check . --fix
+	cd $(BACKEND_DIR) && poetry run ruff format .
+	cd $(DASHBOARD_DIR) && pnpm prettify
+
+test: ## Run fast local tests
+	cd $(DASHBOARD_DIR) && pnpm test --watch=false
+	cd $(BACKEND_DIR) && poetry run pytest -m unit --cov=kernelCI_app --cov=kernelCI_cache --cov-report=term-missing
+
+build: ## Build frontend for production
+	cd $(DASHBOARD_DIR) && pnpm build
+
+ci: ## Reproduce full CI pipeline (lint + build + test + integration)
+	$(MAKE) check-lint
+	$(MAKE) build
+	$(MAKE) test
+	@trap 'docker compose -f docker-compose.test.yml down --volumes --remove-orphans' EXIT; \
+	docker compose -f docker-compose.test.yml up test_db redis -d && \
+	docker compose -f docker-compose.test.yml run --rm test_backend python manage.py migrate && \
+	docker compose -f docker-compose.test.yml run --rm test_backend python manage.py seed_test_data --clear --yes && \
+	docker compose -f docker-compose.test.yml up test_backend -d && \
+	sleep 5 && \
+	cd $(BACKEND_DIR) && TEST_BASE_URL=http://localhost:8001 poetry run pytest -m integration --use-local-db --run-all --cov=kernelCI_app --cov=kernelCI_cache --cov-report=term-missing
+
+dev: ## Start development environment with docker-compose.dev.yml
+	docker compose -f docker-compose.dev.yml up -d
+
+dev-build: ## Start development environment and rebuild images
+	docker compose -f docker-compose.dev.yml up --build -d
+
+clean: ## Remove build artifacts and caches
+	cd $(DASHBOARD_DIR) && rm -rf node_modules dist
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
+	rm -f $(BACKEND_DIR)/.coverage*

README.md

@@ -152,3 +152,5 @@ If you want to verify container/deployment environment settings before running s
 ## Contributing 
 
 Check out our [CONTRIBUTING.md](/CONTRIBUTING.md), and there is an [onboarding guide](docs/Onboarding.md) to help get acquainted with the project. Contributions are welcome!
+
+For a local development environment with live reload (backend + frontend), see [docs/dev-environment.md](docs/dev-environment.md). That Docker-based workflow uses a root `.env` file plus `dashboard/.env`; the backend-specific manual setup above still uses `.env.backend`. Use the env files required by the workflow you choose.

dashboard/.gitignore

@@ -1,3 +1,5 @@
+src/.tanstack-tmp/
+
 # Logs
 logs
 *.log

dashboard/Dockerfile.dev

@@ -0,0 +1,8 @@
+FROM node:20.15.0-alpine
+WORKDIR /dashboard
+RUN npm install -g pnpm
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+EXPOSE 5173
+CMD ["pnpm", "dev", "--host"]

docker-compose.dev.yml

@@ -0,0 +1,79 @@
+volumes:
+    backend-data:
+    dashboard-db-data:
+
+networks:
+    public:
+    private:
+
+services:
+    backend:
+        build:
+            context: ./backend
+        volumes:
+            - backend-data:${BACKEND_VOLUME_DIR:-/volume_data}
+            - ./backend:/backend          # live reload: source mounted over image copy
+        env_file: [.env]
+        environment:
+            - PYTHONOPTIMIZE=0            # required for runserver/reload to work correctly
+        networks: [private, public]
+        ports: ["8000:8000"]
+        command:
+            - poetry
+            - run
+            - python
+            - manage.py
+            - runserver
+            - 0.0.0.0:8000
+        entrypoint: "./utils/docker/backend_entrypoint.sh"
+        depends_on:
+            dashboard_db:
+                condition: service_healthy
+            redis:
+                condition: service_started
+
+    dashboard_db:
+        image: postgres:17
+        environment:
+            - POSTGRES_USER=${DB_USER:-admin}
+            - POSTGRES_PASSWORD=${DB_PASSWORD:-barebare}
+            - POSTGRES_DB=${DB_NAME:-dashboard}
+        volumes:
+            - dashboard-db-data:/var/lib/postgresql/data
+        networks: [private]
+        ports: ["${DB_PORT_PUBLISHED:-5434}:5432"]
+        healthcheck:
+            test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-admin} -d ${DB_NAME:-dashboard}"]
+            interval: 5s
+            timeout: 5s
+            retries: 5
+
+    redis:
+        image: redis:8.0-M04-alpine
+        networks: [private]
+
+    dashboard_dev:
+        build:
+            context: ./dashboard
+            dockerfile: Dockerfile.dev
+        environment:
+            - TSR_TMP_DIR=/dashboard/src/.tanstack-tmp  # keep codegen tmp on same bind mount as routeTree.gen.ts
+        volumes:
+            - ./dashboard/src:/dashboard/src        # HMR: watch source changes
+            - ./dashboard/public:/dashboard/public  # HMR: watch public assets
+        networks: [public]
+        ports: ["5173:5173"]
+
+    proxy:
+        build: ./proxy
+        restart: always
+        depends_on: [backend, dashboard_dev]
+        networks: [public]
+        volumes:
+            # Override default template with dev template (Vite proxy + WebSocket)
+            - ./proxy/etc/nginx/templates/dev.conf.template:/etc/nginx/templates/default.conf.template
+        environment:
+            - PROXY_TARGET=${PROXY_TARGET:-http://backend:8000}
+        ports:
+            - ${STAGING_EXTERNAL_HTTP_PORT:-9000}:80
+        env_file: [.env]

docs/Onboarding.md

@@ -102,7 +102,7 @@ Definition of Done: You have the KernelCI Dashboard frontend running locally.
 > Running the project with Docker is especially useful for testing, as the production instance also runs in containers. This setup provides a more similar environment to production and helps ensure consistency between development and deployment.
 
 > [!IMPORTANT]
-> The current docker compose has settings meant for the staging deployment; for local development you'll need to open the `dashboard_db` service's port (set `5434:5432` so the external port doesn't conflict with the backend) and set `STAGING_EXTERNAL_HTTP_PORT` as `80` in the .env. You'll also use a single `.env` instead of the separate `.env.service`s.
+> The current docker compose has settings meant for the staging deployment; for local development you'll need to open the `dashboard_db` service's port (set `5434:5432` so the external port doesn't conflict with the backend) and set `STAGING_EXTERNAL_HTTP_PORT` as `80` in `.env`.
 
 1. Make sure your backend, frontend, db ssh and Redis are **not** running locally.
 
@@ -111,7 +111,7 @@ Definition of Done: You have the KernelCI Dashboard frontend running locally.
   sudo snap stop redis
   ```
 
-2. Set up the `.env` files in the root of the project by copying the `.env.name.example` files and removing the `.example` at the end of the filenames. For the development you'll need to change the following variables in the .env.backend file:
+2. Set up the root `.env` file by copying `.env.example` and removing the `.example` suffix. For development you'll need to change the following variables in the `.env` file:
 ```
 DEBUG_SQL_QUERY=False
 DEBUG=True
@@ -123,7 +123,7 @@ DB_HOST=dashboard_db  # Docker can't connect to the ssh tunnel host directly.
 DJANGO_SECRET_KEY=$(openssl rand -base64 22)
 ```
 
-If running the notification commands, you should add to your .env.backend the following variables:
+If running the notification commands, add these variables to `.env`:
 ```
 EMAIL_HOST_USER=<your email>
 EMAIL_HOST_PASSWORD=<your app password>