62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# ADR 0002: Manual server-build releases
|
|
|
|
- Status: Accepted
|
|
- Date: 2026-08-20
|
|
|
|
## Context
|
|
|
|
The project has three repositories but one small hackathon server. The Qlockify reference already proves a simple operational model: the deployment repository contains ignored backend/frontend checkouts, a trusted operator pulls source on the server, and Docker Compose builds and starts the stack there.
|
|
|
|
An earlier proposed design used CI/CD, a private image registry, immutable image digests, and cross-repository candidate events. The stakeholder explicitly rejected that complexity for this project. No CI/CD pipeline is needed.
|
|
|
|
The platform still needs to answer which source is running and how to return to the previous version.
|
|
|
|
## Decision
|
|
|
|
Use manual Qlockify-style deployment on the production server.
|
|
|
|
For a normal release, a trusted deployment user:
|
|
|
|
1. verifies the exact deployment/backend/frontend repository paths, remotes, branches, and clean working trees;
|
|
2. fetches and fast-forwards each checkout to the latest `origin/main`;
|
|
3. records the exact three resulting Git commit hashes;
|
|
4. builds application images locally with Docker Compose;
|
|
5. runs the dedicated migration and health/smoke checks; and
|
|
6. records the release as active only after validation passes.
|
|
|
|
Rollback selects the previous release record, checks out its three hashes, rebuilds locally, and repeats the checks. Database down-migration is never automatic; migrations follow expand/contract compatibility.
|
|
|
|
The deploy flow may adapt Qlockify's `deploy.sh`, but it must not unconditionally `git reset --hard`. A dirty or divergent checkout stops for operator resolution so user changes are not destroyed.
|
|
|
|
There is no CI/CD workflow, Actions runner, automated cross-repository event, private image registry, or direct automated production mutation.
|
|
|
|
## Alternatives considered
|
|
|
|
### CI/CD plus private registry
|
|
|
|
- Pros: build-once artifacts, automated checks, stronger image provenance.
|
|
- Cons: more services, credentials, runner maintenance, workflow coordination, and implementation effort than the hackathon needs.
|
|
- Rejected: stakeholder chose the simpler manual Qlockify model.
|
|
|
|
### Per-service manual deployment
|
|
|
|
- Pros: each repository can be changed independently.
|
|
- Cons: services could be built from incompatible revisions and migration/config changes could race.
|
|
- Rejected: the deployment repository remains the single manual operational entry point.
|
|
|
|
### Git submodules
|
|
|
|
- Pros: deployment commits can pin service revisions.
|
|
- Cons: conflicts with accepted ADR 0001 and the Qlockify-style ignored checkout layout.
|
|
- Rejected: server release records provide the required three-hash provenance.
|
|
|
|
## Consequences
|
|
|
|
- The trusted deployment user and production server contain the source/build toolchain.
|
|
- Deployment is slower and less artifact-reproducible than build-once registry delivery, but exact Git hashes and build records preserve practical traceability.
|
|
- Source forge availability is required for new deployment and usually for rollback unless the target commits remain locally available.
|
|
- Manual quality commands and health checks are essential because no pipeline enforces them.
|
|
- Dirty/diverged checkout handling must fail safely rather than destroying changes.
|
|
- The server stores active and previous non-secret release records.
|
|
- Any future CI/CD or registry introduction requires a new approved ADR.
|