---
type: User Story
title: Deploy and operate the platform securely
description: Operators have repeatable builds, migrations, credential provisioning, configuration, and security checks.
tags: [operations, security, database, deployment]
timestamp: 2026-08-08T15:05:48Z
story_id: US-015
status: verified
---

# User Story

As a platform operator, I want reproducible deployment and security controls, so that the portal, bot, database, and proxy can be operated safely.

# Acceptance Criteria

- [x] The repository is an npm TypeScript workspace with separate web, bot, contract, database, network, and Minecraft modules.
- [x] PostgreSQL is available through Docker Compose for local use.
- [x] Drizzle changes use generated, versioned migrations rather than schema push.
- [x] Velocity credentials can be provisioned or rotated with a one-time-displayed token stored only as a hash.
- [x] The Velocity Gradle wrapper produces a tested shaded JAR.
- [x] Environment examples document database, Keycloak, Discord, trusted proxy, and ProxyCheck settings without secrets.
- [x] The web application sets CSP, framing, MIME, referrer, and permissions headers.
- [x] Database-backed user and administrator pages render as dynamic React Server Components with server-side data access.
- [x] Core pages provide keyboard focus indication, a skip link, labelled controls, table semantics, live status messaging, sufficient text contrast, and reduced-motion support.
- [x] The web runtime provides a dependency-free, uncached health endpoint for orchestration probes that reports readiness and the immutable `APP_VERSION`, falling back to `development` when no build version is supplied.
- [x] Web and Discord bot runtimes emit structured Pino logs with credential-field redaction and safe operational context.
- [x] npm dependency audit and Semgrep security review complete without findings at the last verified change.
- [x] Architecture, Keycloak, API error, security, bot, and Velocity operating documentation is available.

# Implementation

- [`package.json`](../package.json)
- [`compose.yml`](../compose.yml)
- [`packages/database/drizzle`](../packages/database/drizzle)
- [`packages/database/scripts/create-plugin-credential.ts`](../packages/database/scripts/create-plugin-credential.ts)
- [`plugins/velocity/build.gradle.kts`](../plugins/velocity/build.gradle.kts)
- [`apps/web/next.config.ts`](../apps/web/next.config.ts)
- [`apps/web/src/app/healthz/route.ts`](../apps/web/src/app/healthz/route.ts)
- [`Dockerfile`](../Dockerfile)
- [`packages/logging/src/index.ts`](../packages/logging/src/index.ts)
- [`docs/accessibility.md`](../docs/accessibility.md)

# Validation

Use `npm test`, `npm run typecheck`, `npm run lint`, `npm run build`, `npm run velocity:build`, `npm audit`, and `npm run design:validate`. Structured logging redaction is covered by [`packages/logging/test/logger.test.ts`](../packages/logging/test/logger.test.ts). Health endpoint tests verify the supplied immutable build version, the `development` fallback, readiness status, and uncached response; full workspace tests, type checks, lint, OKF validation, and a production web build passed on 2026-08-08.

# Related Stories

- [Administrator SSO](us-011-admin-sso.md)
- [Standardize API errors](us-014-problem-details.md)
- [Build and publish versioned releases](us-016-automated-releases.md)