Admin and Operations Guide

This page is for system admins and operators.

System Admin Panel

The /admin page is available to users with the system_admin role.

The admin panel includes:

User management.
Global store management.

Household owners/admins manage household-scoped members, invite links, stores, locations, zones, and catalog items from Manage. System admins manage cross-household/global records from Admin.

Runtime Layout

Local and production runtime pieces:

Backend API: Express, default port 5000.
Frontend: Vite/React, Docker-mapped dev port 3010, direct Vite default 5173.
Database: external Postgres, not a container.
Dev compose: docker-compose.dev.yml.
Production compose: docker-compose.yml.

Environment Variables

Do not commit real .env, backend.env, or frontend.env values.

Important backend variables:

Variable	Purpose
`DATABASE_URL`	Preferred Postgres connection string for backend and root migration scripts.
`DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`, `DB_NAME`	Backend fallback database settings when `DATABASE_URL` is absent.
`JWT_SECRET`	Required for token-compatible auth paths.
`ALLOWED_ORIGINS`	Comma-separated allowed frontend origins for CORS.
`SESSION_COOKIE_NAME`	Optional session cookie name.
`SESSION_TTL_DAYS`	Optional session lifetime in days.

Important frontend variables:

Variable	Purpose
`VITE_API_URL`	Frontend API base URL. Defaults to the local backend URL.
`VITE_ALLOWED_HOSTS`	Optional Vite host allowlist.

Local Operations

Install:

npm ci
npm --prefix backend ci
npm --prefix frontend ci

Run with Docker:

docker compose -f docker-compose.dev.yml up

Run in separate terminals:

npm run dev:backend
npm run dev:frontend

Health checks:

curl http://127.0.0.1:5000/
curl http://127.0.0.1:5000/config

Deployment

Gitea Actions build and deploy this app.

Pushes to main build and tag images as latest.
Pushes to main-new build and tag images as main-new.
Workflows install dependencies, run reliability checks, build backend/frontend images, push images to the configured registry, then deploy through SSH.

Deployment secrets are stored in Gitea Actions secrets. Do not print or paste them into logs.

Reliability Gate

The workflow currently runs:

npm run audit
npm run lint
npm run typecheck
npm test
npm run db:migrate:stale:check
npm run build:backend
npm run build:frontend

Use the same commands locally before pushing risky changes.

Operational Safety

Do not run migrations against production or shared databases unless that is the explicit operator task.
Do not add a Postgres container; the app expects an external database.
Do not log secrets, tokens, session cookies, DB URLs, receipt bytes, or full invite codes.
Invite code logs/audit entries may include last 4 characters only.
Backend/API changes in Docker dev usually require rebuilding/restarting the backend service.

Useful dev backend restart:

docker compose -f docker-compose.dev.yml up -d --build backend

Useful env/CORS reload:

docker compose -f docker-compose.dev.yml up -d --force-recreate --no-deps backend