better cards

openspec/changes/deploy-without-node/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-10

openspec/changes/deploy-without-node/design.md

@@ -0,0 +1,60 @@
+## 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?

openspec/changes/deploy-without-node/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+The production server only provides Docker and does not have Node.js installed. We need a way to refresh the site to the latest content on that server without installing Node.js on the host.
+
+## What Changes
+
+- Add a Docker-first mechanism to update the deployed site to the latest content without requiring host-installed build tooling (no Node.js on the server).
+- Standardize the deploy/update flow so the server updates are performed via Docker (e.g., pulling a new artifact/image and restarting, or running a containerized refresh job).
+- Document and automate the update command(s) so content refresh is repeatable and low-risk.
+
+## Capabilities
+
+### New Capabilities
+- `docker-content-refresh`: The deployed site can be updated to the latest content on a Docker-only server (no host Node.js), using a containerized workflow.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- Deployment/runtime: Docker compose/service definitions, update procedure, and operational docs.
+- CI/CD: build/publish pipeline may need to produce and publish deployable artifacts suitable for Docker-only servers.
+- Secrets/credentials: any content source credentials needed for refresh/build must be handled via Docker-friendly secret injection.
+- Observability/ops: add or adjust logging/health checks around the refresh/update step to make failures visible.

openspec/changes/deploy-without-node/specs/docker-content-refresh/spec.md

@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Host update does not require Node.js
+The system MUST provide an operator workflow to update the deployed site to the latest content without installing Node.js on the server host. Any build or content-fetch steps MUST run in containers and/or CI, not via host-installed Node.js.
+
+#### Scenario: Operator updates without host Node.js
+- **WHEN** the server host has Docker available but does not have Node.js installed
+- **THEN** the operator can complete the update procedure using Docker commands only
+
+### Requirement: Image-based content refresh is supported
+The system MUST support refreshing the deployed site to the latest content by pulling a newly built deployable artifact (for example, a Docker image) and restarting the running service.
+
+#### Scenario: Successful refresh to latest image
+- **WHEN** the operator runs the documented refresh command
+- **THEN** the server pulls the latest published image and restarts the service using that image
+
+#### Scenario: Refresh failure does not break running site
+- **WHEN** the operator runs the documented refresh command and the pull fails
+- **THEN** the site remains running on the previously deployed image
+
+### Requirement: Refresh is repeatable and auditable
+The system MUST document the refresh procedure and provide a way to verify which version is deployed (for example, image tag/digest or build metadata).
+
+#### Scenario: Operator verifies deployed version
+- **WHEN** the operator runs the documented verification command
+- **THEN** the system reports the currently deployed version identifier

openspec/changes/deploy-without-node/tasks.md

@@ -0,0 +1,25 @@
+## 1. Discovery And Current State
+
+- [ ] 1.1 Identify current deploy target and mechanism (compose/swarm/k8s, image vs files) and document constraints in `README` or `ops/` docs
+- [ ] 1.2 Identify the content source(s) that define "latest content" (e.g., WordPress/API) and how builds currently fetch content
+- [ ] 1.3 Confirm current build output (static assets) and runtime server (e.g., nginx) requirements
+
+## 2. Build And Publish A Deployable Artifact
+
+- [ ] 2.1 Ensure the repo can produce a deterministic production build inside CI (no host dependencies)
+- [ ] 2.2 Create or update a Dockerfile to build the site and package the built output into a runtime image
+- [ ] 2.3 Add build metadata to the image (tagging convention and/or embedded version file)
+- [ ] 2.4 Configure CI to build and publish the image to a registry accessible by the server
+
+## 3. Server-Side Docker-Only Refresh Workflow
+
+- [ ] 3.1 Add or update the server Docker Compose/service definition to run the published image
+- [ ] 3.2 Add documented operator commands to refresh to the latest image (pull + restart)
+- [ ] 3.3 Add a verification command/procedure to show the currently deployed version (tag/digest/build metadata)
+- [ ] 3.4 Define rollback procedure to re-deploy a previous known-good tag/digest
+
+## 4. Validation
+
+- [ ] 4.1 Validate a refresh on a test/staging server: pull latest image, restart, confirm content changes are visible
+- [ ] 4.2 Validate failure mode: simulate pull failure and confirm the existing site remains serving
+- [ ] 4.3 Update docs with a minimal "runbook" for operators (refresh, verify, rollback)