Foodbox downloads the Eisodosirak lunch menu image, parses it with Naver Clova OCR, keeps the result in a file database, renders a Svelte calendar, and sends daily Slack notifications.
Production runs as two small containers:
- one non-root Go application containing the API, scheduler, OCR pipeline, file store, and compiled Svelte assets;
- Caddy as the only host-facing service, providing automatic HTTPS and reverse proxying to the application.
- Go 1.26.10 (the toolchain pinned by CI and release workflows;
go.moddeclares Go 1.26.0 as the module minimum) - Node.js 24 and npm
- Docker with Docker Compose v2 for container testing or deployment
Backend tests do not require production credentials:
cd backend
go test ./...Build the frontend:
cd front
npm ci
npm run buildThe Go process reads configuration only from its environment; it does not load
.env itself. Copy .env.example to the repository-local .env, replace every
placeholder outside version control, export that file in the shell, and then
run the application from backend/. When running from that directory, make
sure the database and static-directory variables resolve to the repository's
db/ and front/dist/ directories.
cd backend
set -a
source ../.env
set +a
DB_FILE_DIR=../db STATIC_DIR=../front/dist go run ./cmd/foodboxFor a production-like local build that bundles the frontend and uses the image runtime defaults:
docker build --tag foodbox-local .
docker run --rm --env-file .env --publish 8080:8080 \
--env DB_FILE_DIR=/data --env STATIC_DIR=/app/static \
--volume foodbox-local-data:/data foodbox-localThen check the readiness endpoint and menu API:
curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/api/menuRun the full backend verification from backend/:
go test ./...
go test -race ./...
go vet ./...
go build ./cmd/foodboxRun the frontend build from front/:
npm ci
npm run buildThe Go tests deliberately pin behavior that users can observe. They cover the file-database representation and upsert order, exact public API JSON, Slack payload and Korean message text, 09:00 Asia/Seoul scheduling, startup/schedule overlap, OCR date edge cases, and complete golden-menu output for the retained OCR fixtures. Run both the ordinary and race suites before changing persistence, crawling, OCR, API, scheduling, or Slack behavior.
Container and deployment changes should additionally render Compose, build the
Linux AMD64 image, and smoke-test /healthz, /, and /api/menu. CI performs
the clean-checkout backend, frontend, and container builds before a production
image is published.
Do not put credentials in source files, Docker images, commands, issue comments, or GitHub repository variables. The table names the variables only; secret values are intentionally omitted.
| Variable | Required | Purpose |
|---|---|---|
CLOVA_URL |
Yes | Clova OCR invocation endpoint |
CLOVA_SECRET_KEY |
Yes | Clova OCR credential |
SLACK_TOKEN |
Yes | Incoming-webhook path secret, not a bot OAuth token |
SLACK_CHANNEL |
Yes | Slack destination channel |
CRAWL_URL |
No | Eisodosirak menu board URL |
SLACK_URL |
No | Slack webhook base URL |
SLACK_USERNAME |
No | Display name used by the Slack message |
ADMIN_TOKEN |
No | Internal management API credential; an empty value disables those routes |
SERVER_PORT |
No | Application listen port |
DB_FILE_DIR |
No | Directory containing db.json and metadata.json |
STATIC_DIR |
No | Compiled Svelte asset directory |
TZ |
No | Runtime timezone; production scheduling uses Seoul time |
Production keeps application configuration in the server-side .env. The
deployment script never replaces this file and restricts its permissions. It
creates a separate .deploy.env containing only deployment metadata needed by
Compose. FOODBOX_IMAGE and DOMAIN belong to that generated deployment file,
not to the application secret store.
Public routes:
| Method | Route | Purpose |
|---|---|---|
GET |
/healthz |
Verify that the file store is readable and writable |
GET |
/api/menu |
Return all menus, newest first |
GET |
/api/menu/today |
Return today's menu |
Management routes implemented by the application:
| Method | Route | Purpose |
|---|---|---|
POST |
/api/crawl |
Download, OCR, and persist the current menu |
POST |
/api/upload |
Parse one multipart file upload, limited to 10 MB |
POST |
/api/menu/manual |
Validate and upsert one menu from an ISO date and ordered menu list |
POST |
/api/slack/notify |
Send today's notification immediately |
Management routes require ADMIN_TOKEN through a bearer authorization header
or X-Admin-Token. Production Caddy returns 404 for them before requests reach
the application, so possessing the token does not expose them on the public
internet. Add a separately authenticated operator path before changing that
edge policy.
For local development, or when the application port is published, register or correct one date manually with an authenticated JSON request:
curl --fail --request POST http://127.0.0.1:8080/api/menu/manual \
--header "Authorization: Bearer $ADMIN_TOKEN" \
--header 'Content-Type: application/json' \
--data '{"date":"2026-10-01","menus":["콩나물국","갈비찜","미역줄기볶음","무생채나물무침","콩조림","아삭이장무침","꼬마김치"]}'Production Compose exposes the app port only to the Compose network, and the public Caddy edge intentionally blocks this management route. Run the same request inside the app container instead:
ADMIN_TOKEN_VALUE='replace-with-server-admin-token'
docker compose --env-file .deploy.env exec -T app wget -qO- \
--header="Authorization: Bearer ${ADMIN_TOKEN_VALUE}" \
--header='Content-Type: application/json' \
--post-data='{"date":"2026-10-01","menus":["콩나물국","갈비찜","미역줄기볶음","무생채나물무침","콩조림","아삭이장무침","꼬마김치"]}' \
http://127.0.0.1:8080/api/menu/manualThe date must be a valid YYYY-MM-DD value and menus must contain at least
three non-empty strings. Repeating a date replaces only that date; existing
dates remain unchanged.
Responses use the {status,error,data} envelope and the menu fields consumed by
the frontend. Error responses use the corresponding HTTP status. The
All state-changing management routes require POST.
db.jsonstores dates as[year,month,day]alongsidemenusandvalid. Disk records are oldest first;/api/menuis newest first.- Deployment snapshots preserve legacy records with
"menus": null, which the Go store reads as a nil slice; non-array or non-string menu values remain invalid, and new writes use arrays. metadata.jsonpersists the last successfully processed image hash, avoiding duplicate OCR work across restarts. A matching hash is skipped only while the database still contains today's menu, so missing state can repair itself.- Writes use a unique temporary file, file and directory sync, and atomic replacement. Only one application instance may own the volume.
- Startup refresh runs after the HTTP server becomes ready and does not block readiness on vendor or Clova availability.
- Slack notification runs once daily at 09:00 Seoul time. Startup refresh and daily notification cannot overlap; a 09:00 tick during refresh is queued and sent after refresh completes.
.github/workflows/ci.ymltests Go, validates deployment operations, builds Svelte, and builds the Linux AMD64 container for pull requests targetingmainand manual dispatches. Commits pushed todevdo not start CI..github/workflows/deploy.ymlstarts on every push tomain. Its own release verification must pass before it builds and publishes the GHCR image, and only the exact published digest is passed to the server deployment job..github/workflows/rollback.ymlis a manually dispatched rollback frommainto the stored previous successful Go release.
The Oracle VM never runs Go, Node, or Docker image builds during normal deployment. It pulls an immutable digest, backs up the file database, starts the stack, and accepts the release only after Compose health checks and the public HTTPS health check succeed.
Application credentials are never sent by the workflow. They remain in the
Oracle VM's protected .env. The GitHub production Environment contains only
the SSH deployment secrets and optional DEPLOY_PATH / PUBLIC_URL variables.
The GHCR package must either be publicly readable or the VM must already be
logged in with a narrowly scoped read-only package credential.
A push to main starts the deploy workflow whether it came from a merged PR or
a direct push. PR review and approval are enforced only by the repository's
branch ruleset; Actions does not impose them. Configure a required reviewer on
the GitHub production Environment to hold the server job for explicit
approval after verification and image publication. The server locks concurrent
operations, snapshots the database, pulls immutable images, and accepts a
release only after runtime, API, UI, database, and single-writer checks pass.
If no previous successful Go release exists, a failed deployment restores the
exact stopped-state database and the original configuration-existence state,
then remains stopped. Later deployment failures restore and verify the Go
release that was active when deployment started. See deploy/README.md for the
operation exit-code contract.
After two successful deployments, the Roll back production workflow can be
manually dispatched from main to restore and verify the previously successful
digest. Never run docker compose down -v because the Caddy volumes contain
certificate state.