Minecraft Account Manager

A Discord-first account registry for a private Java Edition Minecraft network. Players link Discord to one or more Minecraft accounts, while a fail-closed Velocity plugin admits only registered accounts.

Workspace layout

apps/web — Next.js 16 web application and API, styled with Tailwind CSS v4
apps/discord-bot — discord.js slash-command bot
packages/contracts — shared Zod contracts and CloudEvents types
packages/database — PostgreSQL Drizzle schema and versioned migrations
plugins/velocity — fail-closed Velocity admission plugin

Requirements

Node.js 22+
npm 11+
Docker with Compose, or PostgreSQL 17+

Local setup

cp .env.example .env.local
docker compose up -d postgres
npm install
npm run db:migrate
npm run dev

Set DISCORD_GUILD_ID and DISCORD_INVITE_URL in .env.local so unauthenticated visitors can reach the Discord server. The HTTPS invite is the most reliable way to open Discord or join; the landing page also offers a discord:// app link.

Set IP_INTELLIGENCE_PROVIDER=proxycheck, add PROXYCHECK_API_KEY, and configure trusted proxy handling before allowing users to add accounts. Portal and game logins continue if lookup fails, but user account additions fail closed when an address is unknown, VPN, proxy, or Tor.

Open http://localhost:3000.

Product design

Implemented and proposed behavior is tracked as OKF user stories in design/index.md. Validate the bundle with npm run design:validate.

Validation

npm run design:validate
npm test
npm run typecheck
npm run lint
npm run build
npm run velocity:build

Releases and containers

Gitea Actions validate every change and use conventional commits to produce semantic releases from main. Releases include a public, versioned Velocity JAR plus separate web runtime and Drizzle migration images.

See docs/releases.md for artifact names, required repository secrets, and deployment order.

Database workflow

Always create and apply versioned migrations:

npm run db:generate
npm run db:migrate

Do not use drizzle push; it bypasses the reviewed migration history and can cause destructive schema changes.

Provision or rotate a Velocity API token after migrating:

npm run plugin:create-credential --workspace @minecraft-account-manager/database -- velocity-main

The token is displayed once and stored only as a SHA-256 hash.

Confirmed product decisions

PostgreSQL and Drizzle ORM
Keycloak OIDC for admin access with the minecraft-account-manager-admin role
Admin user search, account management, primary-account changes, and Discord nickname synchronization
Deployment-managed Discord guild ID and invite URL
discord.js bot with /register and /account
Java Edition online-mode accounts only
Velocity admission checks are fail closed
ProxyCheck.io geolocation and VPN/proxy/Tor detection with a 48-hour PostgreSQL cache

See docs/architecture.md for trust boundaries and service responsibilities, docs/api-errors.md for the RFC 9457 API error contract, and docs/security-review.md for implemented controls and production requirements.

3.2 KiB Raw Blame History