docs(dev): add iteration 1 setup and reports

DEVELOPMENT.md

@@ -0,0 +1,233 @@
+# Development Guide
+
+This guide explains how to prepare and run Lab Timesheet on a developer
+computer. The application runs from Java. PostgreSQL and Mailpit run in Docker
+containers.
+
+Application containerization and Docker Compose are planned for a later
+iteration, so they are not required for Iteration 1 development.
+
+## 1. Install the required tools
+
+Install:
+
+- Java 25
+- Docker Desktop or OrbStack
+- Node.js 24 and npm 11
+- Git
+- IntelliJ IDEA, if you want to run the application from the IDE
+
+Confirm the tools are available:
+
+```bash
+java -version
+docker version
+node --version
+npm --version
+```
+
+On macOS, select an installed Java 25 JDK with:
+
+```bash
+export JAVA_HOME=$(/usr/libexec/java_home -v 25)
+export PATH="$JAVA_HOME/bin:/opt/homebrew/opt/node@24/bin:$PATH"
+```
+
+Java 25 is the supported project baseline. A newer local JDK can compile the
+project but is not the shared team baseline.
+
+## 2. Prepare the project
+
+Clone the repository, open a terminal in its root directory, then create your
+local environment file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and replace the database password placeholder. Generate the
+encryption master key with:
+
+```bash
+openssl rand -base64 32
+```
+
+Copy that output into `LAB_SECURITY_MASTER_KEY`. Never commit `.env` or share a
+real key in chat, screenshots, test evidence, or documentation.
+
+Install and build the local frontend assets:
+
+```bash
+npm ci
+npm run build
+```
+
+## 3. Start the development containers
+
+### PostgreSQL 18.4
+
+Create a named volume once. The volume keeps your development data when the
+container is stopped or replaced.
+
+```bash
+docker volume create labtimesheet-postgres-data
+```
+
+Start PostgreSQL:
+
+```bash
+docker run -d \
+  --name labtimesheet-postgres \
+  --restart unless-stopped \
+  -e POSTGRES_DB=labtimesheet \
+  -e POSTGRES_USER=labtimesheet \
+  -e POSTGRES_PASSWORD=replace-with-same-password-as-env \
+  -p 127.0.0.1:55432:5432 \
+  -v labtimesheet-postgres-data:/var/lib/postgresql \
+  postgres:18.4
+```
+
+Use the same password for `POSTGRES_PASSWORD` and `LAB_DB_PASSWORD` in `.env`.
+PostgreSQL stores the original password in the volume. Changing only `.env`
+later will not change the database password.
+
+### Mailpit
+
+Mailpit receives development email without sending it to real people.
+
+```bash
+docker run -d \
+  --name labtimesheet-mailpit \
+  --restart unless-stopped \
+  -p 127.0.0.1:1025:1025 \
+  -p 127.0.0.1:8025:8025 \
+  axllent/mailpit:v1.27.4
+```
+
+Confirm both containers are running:
+
+```bash
+docker ps
+```
+
+Useful container commands:
+
+```bash
+docker logs labtimesheet-postgres
+docker logs labtimesheet-mailpit
+docker stop labtimesheet-postgres labtimesheet-mailpit
+docker start labtimesheet-postgres labtimesheet-mailpit
+```
+
+Stopping the containers keeps the database volume. Do not remove the volume
+unless you intentionally want to discard your local development data.
+
+## 4. Run from a terminal
+
+Load the environment file in the same terminal that will run Spring Boot:
+
+```bash
+set -a
+source .env
+set +a
+./mvnw spring-boot:run
+```
+
+Open:
+
+- First-Admin setup: `http://localhost:8080/bootstrap`
+- Login: `http://localhost:8080/login`
+- Mailpit inbox: `http://localhost:8025`
+
+At first setup, configure SMTP through the Admin console with:
+
+| Setting | Development value |
+|---|---|
+| Host | `localhost` |
+| Port | `1025` |
+| Security | `NONE` |
+| Username | leave empty |
+| Password | leave empty |
+| From address | a local address such as `labtimesheet@example.test` |
+| From name | `Lab Timesheet` |
+
+Test the draft before activating it. Mailpit's web inbox shows activation and
+other development messages.
+
+Stop the application with `Control+C`.
+
+## 5. Run with IntelliJ IDEA
+
+### Open the project
+
+1. Open IntelliJ IDEA.
+2. Choose **Open** and select the repository root.
+3. Allow IntelliJ to import the Maven project.
+4. Open **File > Project Structure > Project**.
+5. Select a Java 25 SDK. Add the JDK installation if it is not listed.
+
+### Create the run configuration
+
+1. Open **Run > Edit Configurations**.
+2. Select **+**, then **Spring Boot**.
+3. Use the name `Lab Timesheet (dev)`.
+4. Set **Main class** to
+   `com.lab.labtimesheet.LabtimesheetApplication`.
+5. Set **Use classpath of module** to the main `labtimesheet` module.
+6. Set **JRE** to Java 25.
+7. Set **Active profiles** to `dev`.
+8. Set **Working directory** to the repository root.
+9. Open the **Environment variables** editor and add every variable from your
+   local `.env` file.
+10. Apply the configuration and run it.
+
+Some IntelliJ editions can load variables from an environment file directly.
+If that option is available, select the local `.env`; otherwise use the
+environment-variable table. Do not store real secrets in a shared or committed
+run configuration.
+
+Run `npm ci` and `npm run build` in IntelliJ's terminal before the first launch
+and after changing Tailwind or icon sources.
+
+## 6. Common problems
+
+### The application cannot connect to PostgreSQL
+
+Run:
+
+```bash
+docker ps
+docker logs labtimesheet-postgres
+```
+
+Check that `.env` uses port `55432`, database `labtimesheet`, user
+`labtimesheet`, and the password used when the PostgreSQL volume was first
+created.
+
+### Port 8080, 55432, 1025, or 8025 is already in use
+
+Stop the other program or container using that port. Keep `.env` and the Docker
+port mapping consistent if you intentionally select another development port.
+
+### Mail does not appear in Mailpit
+
+Check that Mailpit is running and that the active Admin SMTP configuration uses
+host `localhost`, port `1025`, and security `NONE`. A container health warning
+does not by itself prove that SMTP is unavailable; use the Admin SMTP test.
+
+### IntelliJ uses the wrong Java version
+
+Check both **Project SDK** and the run configuration's **JRE**. They should both
+be Java 25.
+
+### Styles or icons are missing
+
+Run:
+
+```bash
+npm ci
+npm run build
+```
+
+For test setup, commands, TDD, and test evidence rules, read
+[TESTING.md](TESTING.md).