# Feature Specification: Docker Deployment Setup

**Feature**: `002-docker-deployment`
**Created**: 2026-03-06
**Status**: Implemented
**Source**: Migrated from spec/setup-tasks.md

> Note: This is a setup task (infrastructure), not a user-facing feature.

## User Scenarios & Testing

### User Story 1 - Build and run the application as a single Docker container (Priority: P1)

A developer or operator can build the project with a single `docker build .` command and run it as a self-contained container. The multi-stage Dockerfile compiles backend and frontend in isolation and produces a minimal runnable image.

**Why this priority**: Docker packaging is the primary deployment mechanism. Without it, no deployment can happen.

**Independent Test**: Run `docker build .` and then start the container. Verify the health-check endpoint responds.

**Acceptance Scenarios**:

1. **Given** the repository is checked out, **When** `docker build .` is executed, **Then** the build succeeds and produces a working image.
2. **Given** a built Docker image, **When** a container is started from it, **Then** the health-check endpoint responds successfully.
3. **Given** the repository is checked out, **When** a `.dockerignore` file is present, **Then** build artifacts, IDE files, and unnecessary files are excluded from the build context.

### Edge Cases

- What happens when the frontend build fails inside the Docker build? The multi-stage build must fail visibly so the broken image is never produced.
- What happens if the health-check endpoint is not reachable? Docker and orchestrators mark the container as unhealthy.

## Requirements

### Functional Requirements

- **FR-001**: A multi-stage Dockerfile MUST exist at the repo root that builds both backend and frontend and produces a single runnable container.
- **FR-002**: The Dockerfile MUST use separate build stages so backend and frontend build dependencies are not included in the final image.
- **FR-003**: A `.dockerignore` file MUST exclude build artifacts, IDE files, and unnecessary files from the build context.
- **FR-004**: The container MUST expose a health-check endpoint so Docker and orchestrators can verify the app is alive.
- **FR-005**: `docker build .` MUST succeed and produce a working image.
- **FR-006**: A started container MUST respond successfully to the health-check endpoint.

> Scope note (Addendum 2026-03-04): Database connectivity (`DATABASE_URL`), runtime environment variable configuration (Unsplash API key, max active events), and README docker-compose documentation are out of scope for T-2. They are deferred to T-4 where JPA and Flyway are introduced and can be tested end-to-end.

### Key Entities

- **Dockerfile**: Multi-stage build definition at the repo root. Stages: frontend build (Node), backend build (Maven/Java), final runtime image.
- **.dockerignore**: Excludes `target/`, `node_modules/`, IDE directories, and other non-essential files.

## Success Criteria

### Measurable Outcomes

- **SC-001**: `docker build .` completes without errors from a clean checkout.
- **SC-002**: A container started from the built image responds to the health-check endpoint within the configured timeout.
- **SC-003**: The final Docker image does not contain Maven, Node.js, or build tool binaries (multi-stage isolation verified).