# 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. 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.
