## Context

- Production server environment is intentionally minimal: Docker is available, but Node.js is not installed on the host.
- The site needs a repeatable way to get to the latest built content on that server.

## Goals / Non-Goals

**Goals:**
- Update the deployed site to the latest content using Docker-only operations on the server.
- Keep the server host clean (no Node.js installation required).
- Make the refresh procedure repeatable and verifiable.

**Non-Goals:**
- Building site artifacts directly on the server host outside containers.
- Introducing a new CMS/content authoring workflow.
- Solving content freshness triggers end-to-end (webhooks, scheduling) beyond what is needed to support a Docker-based refresh.

## Decisions

1. Build in CI, deploy as a Docker image
Why: keeps host clean and makes deploy deterministic.
Alternatives considered:
- Install Node.js on the host: rejected (violates clean server requirement).
- Build on the host inside a one-off container writing to a bind mount/volume: possible, but adds operational complexity and makes server resources part of the build pipeline.

2. Refresh by pulling a published image and restarting the service
Why: the server only needs Docker + registry access.
Alternatives considered:
- File-based sync (rsync/scp) of static assets: can work, but requires separate artifact distribution and is easier to drift.
- Automated image updating (e.g., watchtower): may be useful later, but start with an explicit, documented operator command.

3. Version visibility via image metadata
Why: operators need to confirm what is running.
Approach:
- Publish images with an immutable identifier (digest) and a human-friendly tag.
- Expose build metadata through standard Docker inspection and/or a small endpoint/static file in the image.

## Risks / Trade-offs

- [Risk] Content can be stale if the CI build does not run when content changes
  Mitigation: add a scheduled build and/or content-change trigger in CI (future enhancement if not already present).

- [Risk] Registry auth/secrets management on the server
  Mitigation: use least-privilege registry credentials and Docker-native secret handling where available.

- [Risk] Short downtime during restart
  Mitigation: use `docker compose up -d` to minimize downtime; consider health checks and rolling strategies if/when multiple replicas are used.

## Migration Plan

- Add or update the Docker image build to produce a deployable image containing the built site output.
- Update server deployment configuration (compose/service) to run the published image.
- Document the operator refresh command(s): pull latest image, restart service, verify deployed version.
- Rollback strategy: re-deploy the previously known-good image tag/digest.

## Open Questions

- What is the authoritative "latest content" source (e.g., WordPress, filesystem, git) and what is the trigger to rebuild/publish a new image?
- Where should operator commands live (Makefile, `ops/` scripts, README section)?
- What is the current deployment target (single host compose, swarm, k8s) and should this change be scoped to one?