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.

Open http://localhost:3000.

Validation

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

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
VPN detection is represented in the schema but may remain disabled in the first release until a provider is selected

See docs/architecture.md for trust boundaries and service responsibilities, and docs/security-review.md for implemented controls and production requirements.

2.4 KiB Raw Blame History