73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
npm test
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run build
|
|
npm run velocity:build
|
|
```
|
|
|
|
## Database workflow
|
|
|
|
Always create and apply versioned migrations:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
- 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`](docs/architecture.md) for trust boundaries and service responsibilities, and [`docs/security-review.md`](docs/security-review.md) for implemented controls and production requirements.
|