# Development and staging workflow

## Environments

| Environment | Purpose | Address |
|---|---|---|
| Windows | Source editing and Git workflow only | Not applicable |
| Rocky Linux | Docker development and production-like staging | `http://192.168.1.101:9190` |
| Future VPS | Planned deployment environment | Not provisioned yet |
| Workplace production | Out of scope until reviewed and approved | Not documented here |

Rocky checkout:

```text
/home/sandbox/Documents/projects/WeatherTool
```

Private Rocky bare Git remote:

```text
/home/sandbox/Documents/git/WeatherTool.git
```

Development branch:

```text
codex/staging-baseline
```

## Safety boundaries

- Do not commit `.env`, credentials, database data, `web/node_modules`, or `web/dist`.
- Keep `ENABLE_SCHEDULED_JOBS=false` with placeholder or development credentials.
- Do not publish the staging PostgreSQL port.
- Do not run `npm audit fix` without reviewing the proposed dependency changes.
- Do not change ownership or permissions of the container-managed `postgres/` directory as a deployment workaround.
- Do not use the current staging procedure as an undocumented workplace-production procedure.

## Windows development

Use Windows to edit and review source files and to create Git commits. Docker builds,
the running application, synthetic-data operations, and browser testing belong on
Rocky. Docker Desktop is not part of the normal project workflow.

## Commit and transfer workflow

On Windows, review and commit a coherent change:

```powershell
git status --short
git diff --check
git add <files>
git commit -m "Describe the coherent change"
git push rocky codex/staging-baseline
```

On Rocky, update the staging checkout:

```bash
cd /home/sandbox/Documents/projects/WeatherTool
git pull --ff-only
```

## Rocky frontend-only deployment

For frontend-only changes, rebuild the bind-mounted production assets without restarting Scala or PostgreSQL:

```bash
cd /home/sandbox/Documents/projects/WeatherTool
docker compose run --rm node
docker compose ps
curl -I http://localhost:9190/
```

Use a hard browser refresh after deployment.

## Rocky full-stack deployment

Only use a full backend rebuild when backend or Scala dependency changes require it. Because the repository-local PostgreSQL bind directory is container-owned, build a clean context directly from the committed Git tree:

```bash
cd /home/sandbox/Documents/projects/WeatherTool
git archive HEAD | docker build -t weathertool-staging-scala -f Dockerfile.local -
docker compose up -d --no-build scala
docker compose ps
```

This archive pipeline includes committed source only, creates no temporary files, and prevents Docker from scanning the protected `postgres/` directory. Do not loosen database-directory permissions. A future durable Compose fix is to move database storage outside the build context or use a named volume.

## Verification

At minimum, verify:

1. `docker compose ps` reports PostgreSQL healthy and Scala running.
2. `/` returns HTTP 200.
3. The home navigation loads.
4. City Analysis can query synthetic observations.
5. Each map resolution renders and downloads.
6. Faktiskā automatically loads the latest fixed-station temperatures, allows overrides, assigns font symbols, supports exceptions, and downloads a 3840×1440 PNG.
7. Faktiskā symbols remain automatically attached to their corresponding temperature badges when several different Daira glyphs are tested.
8. Browser developer tools show no new runtime errors.

Known limitation: direct browser refreshes on newer client-side routes such as `/faktiska` can return 404 because the backend static-route list does not yet provide a general SPA fallback. Navigate from the home page until that backend behavior is fixed.

## Rollback

Prefer a normal Git revert rather than manually copying old files:

1. Identify the faulty commit with `git log --oneline`.
2. On the development checkout, run `git revert <commit>`.
3. Push the revert and build and test it on Rocky.
4. Push the revert commit.
5. Pull it on Rocky and run the appropriate frontend-only or full-stack deployment command.

Database rollback is a separate operation and must not be inferred from a source rollback. Database backup and restore procedures are not yet defined.
