193 lines
4.8 KiB
Markdown
193 lines
4.8 KiB
Markdown
# MrixsCraft
|
|
|
|
Private Minecraft server project with a web-based launcher.
|
|
|
|
## Architecture
|
|
|
|
Consists of two independent Go repositories unified via git submodules:
|
|
|
|
- **`server/`** — backend (Go + net/http + PostgreSQL)
|
|
- **`launcher/`** — desktop launcher (Go + Fyne GUI)
|
|
|
|
Both are **separate Go modules** — they have their own `go.mod`, tests, and can be built independently. The only connection between them is HTTP API (Yggdrasil + REST).
|
|
|
|
Domain: `minecraft.mrixs.me` · CDN: `cdn.mrixs.me` · Registry: `gitea.mrixs.me`
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `docs/state.md` | **Current project status** — architecture, API, DB schema, TODOs. Read this first. |
|
|
| `docs/server/Specification.md` | Server specification (RU) |
|
|
| `docs/launcher/Specification.md` | Launcher specification (RU) |
|
|
|
|
**Rule:** Read `docs/state.md` first. During work, compare implementation against specifications. Update `docs/state.md` when something changes.
|
|
|
|
---
|
|
|
|
## Working with Submodules
|
|
|
|
`server/` and `launcher/` are **git submodules**, not regular directories. Each tracks its own remote:
|
|
|
|
```
|
|
launcher → ssh://git@gitea.mrixs.me:2222/Mrixs/MrixsCraft-launcher.git
|
|
server → ssh://git@gitea.mrixs.me:2222/Mrixs/MrixsCraft-server.git
|
|
```
|
|
|
|
### Workflow
|
|
|
|
```bash
|
|
# 1. Enter submodule
|
|
cd server/ # or launcher/
|
|
|
|
# 2. Edit code
|
|
# ...
|
|
|
|
# 3. Build & test locally
|
|
go build ./...
|
|
go test ./...
|
|
|
|
# 4. Commit INSIDE the submodule
|
|
git add -A
|
|
git commit -m "feat: ..." -m "Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
|
|
|
|
# 5. Push the submodule
|
|
git push origin master
|
|
|
|
# 6. (Optional) Return to parent and record the new submodule commit
|
|
cd ..
|
|
git add server # or launcher
|
|
git commit -m "chore: bump server submodule"
|
|
```
|
|
|
|
**Always commit and push inside the submodule first.** CI/CD is triggered by pushes to submodule repos, not the parent.
|
|
|
|
### Clone
|
|
|
|
```bash
|
|
git clone --recurse-submodules gitea.mrixs.me:mrixs/mrixscraft.git MC-server
|
|
```
|
|
|
|
If already cloned without submodules:
|
|
```bash
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
---
|
|
|
|
## Server (`server/`)
|
|
|
|
### Key Paths
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `cmd/server/main.go` | Entry point — routes, middleware, graceful shutdown |
|
|
| `internal/auth/` | Yggdrasil auth (authenticate/refresh/validate) |
|
|
| `internal/api/` | Public API (register, login, skins, capes, launcher) |
|
|
| `internal/admin/` | Admin panel (modpacks, uploads, manifests) |
|
|
| `internal/cas/` | Content-Addressable Storage (SHA-1 file serving) |
|
|
| `internal/templates/` | Website pages (embedded via `go:embed`) |
|
|
| `migrations/` | SQL migrations (manual apply) |
|
|
| `Dockerfile` | Multi-stage build (~20 MB) |
|
|
| `.gitea/workflows/ci.yml` | CI: lint → test → build → docker push |
|
|
|
|
### Build & Test
|
|
|
|
```bash
|
|
cd server/
|
|
go build -o mrixscraft-server ./cmd/server
|
|
go test ./... -race -cover
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Required |
|
|
|----------|---------|----------|
|
|
| `SERVER_PORT` | `8080` | No |
|
|
| `DATABASE_URL` | — | **Yes** |
|
|
| `CAS_DIR` | `/var/www/cdn/files` | No |
|
|
| `JWT_SECRET` | — | **Yes** |
|
|
| `BASE_URL` | `https://minecraft.mrixs.me` | No |
|
|
|
|
---
|
|
|
|
## Launcher (`launcher/`)
|
|
|
|
### Key Paths
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `cmd/launcher/main.go` | Entry point, Fyne bootstrap |
|
|
| `internal/auth/` | Yggdrasil client |
|
|
| `internal/config/` | `launcher.json`, system paths |
|
|
| `internal/fetcher/` | HTTP downloader with SHA-1 verification |
|
|
| `internal/java/` | JRE detection/download |
|
|
| `internal/launch/` | Manifest parsing, game launch |
|
|
| `internal/selfupdate/` | Binary auto-updater |
|
|
| `internal/ui/` | Fyne GUI (screens, components, theme) |
|
|
|
|
### Build
|
|
|
|
```bash
|
|
cd launcher/
|
|
go build -o mrixscraft-launcher ./cmd/launcher
|
|
go run ./cmd/launcher
|
|
```
|
|
|
|
---
|
|
|
|
## Deployment Flow
|
|
|
|
```
|
|
[Commit + push inside submodule]
|
|
│
|
|
▼
|
|
[Gitea Actions CI]
|
|
lint → test → build → docker push
|
|
│
|
|
▼
|
|
[Gitea Container Registry]
|
|
gitea.mrixs.me/mrixs/mrixscraft-server:latest
|
|
│
|
|
▼
|
|
[Watchtower on VPS]
|
|
polls every 5 min → pull → restart
|
|
```
|
|
|
|
**No manual deployment needed.** Push to submodule → auto-deploy.
|
|
|
|
Required Gitea secrets: `PACKAGES_TOKEN` (PAT with `read:package`, `write:package`).
|
|
|
|
---
|
|
|
|
## Style Guidelines
|
|
|
|
- Use Markdown (`.md`) for documentation
|
|
- Go: stdlib `net/http`, `html/template` with `go:embed`, `pgx/v5` for DB
|
|
- Dark theme (#0f0f1a / #16213e) with green accent (#4ade80) for web templates
|
|
- Commit message format: `type: description`
|
|
|
|
---
|
|
|
|
## Git Conventions
|
|
|
|
```
|
|
type: short description
|
|
|
|
longer body if needed
|
|
```
|
|
|
|
Types: `feat`, `fix`, `chore`, `refactor`, `docs`
|
|
|
|
---
|
|
|
|
## Port Reference
|
|
|
|
| Service | Port | Scope |
|
|
|---------|------|-------|
|
|
| server (backend) | 8080 | Internal (Docker) |
|
|
| PostgreSQL | 5432 | Internal (Docker) |
|
|
| Caddy | 80, 443 | Public |
|