MinePanel

La Storia

Avviare un server Minecraft è facile. Gestirlo bene, mantenerlo sotto controllo, dare accesso ad altre persone in modo sicuro, monitorare le risorse e fare tutto questo senza consegnare l'intera infrastruttura a qualche piattaforma cloud esterna è dove le cose iniziano a diventare fastidiose.

Volevo qualcosa di più vicino al resto della mia infrastruttura self-hosted: installarlo su hardware che controllo io, sapere esattamente dove vivono i dati e mantenere tutto il sistema portabile. Non volevo un altro servizio in cui il famoso "setup semplice" finisce prima o poi per trasformarsi in un abbonamento, in un'infrastruttura proprietaria o in una dashboard che finisce per possedere più del server di quanto lo possieda io.

Da questa frustrazione è nato MinePanel. Quella che all'inizio era semplicemente l'idea di "voglio un modo pulito per controllare server Minecraft eseguiti tramite Docker" è diventata progressivamente una domanda molto più grande: come dovrebbe essere una vera piattaforma self-hosted per la gestione di server Minecraft, se la trattassi come infrastruttura reale invece che come uno script da progetto del weekend?

Cosa Lo Rende Speciale

L'idea alla base di MinePanel è molto semplice: il tuo server dovrebbe essere davvero tuo. ⛏️

MinePanel gira sulla tua macchina, controlla il tuo Docker daemon, salva lo stato nel tuo database PostgreSQL ed esegue ogni istanza Minecraft nel proprio container. Non esiste un cloud MinePanel obbligatorio nel mezzo e non c'è nessuna infrastruttura esterna da cui dover chiedere il permesso per andarsene. Punta un dominio alla macchina, configura l'ambiente, avvia lo stack Compose e hai un vero backend di gestione HTTPS che gira sull'hardware che controlli.

La parte che preferisco è che questa semplicità non arriva nascondendo le parti difficili. Dietro al deployment praticamente immediato ci sono autenticazione vera, 2FA, autorizzazioni granulari, workflow di richiesta accesso, gestione del lifecycle dei container, metriche in tempo reale, controlli sulle risorse e un backend progettato tenendo ben presente che avere accesso al Docker socket significa avere accesso serio all'infrastruttura. L'obiettivo è rendere l'esterno quasi banalmente semplice, mantenendo l'interno progettato con estrema intenzionalità.

La Parte Tecnica

Funzionalità Principali

• 🚀 Self-hosting con un comando - avvia lo stack principale con Docker Compose invece di configurare manualmente panel, database, reverse proxy e TLS.
• 📦 Un container per ogni server - ogni server Minecraft gira nel proprio container Docker, mantenendo le istanze isolate e rendendo il lifecycle prevedibile.
• 🎯 Permessi granulari per server - i ruoli ADMIN, MOD e USER si combinano con permessi specifici per server, evitando il classico approccio "il moderatore può fare tutto".
• 🔄 Workflow di accesso ai server - le modalità OPEN, REQUEST e PRIVATE permettono di controllare esattamente come gli utenti possono ottenere accesso.
• ⚙️ Monitoraggio host in tempo reale - CPU, RAM e disco vengono trasmessi tramite WebSocket, così gli amministratori possono vedere cosa sta succedendo senza polling continuo.
• 🎨 Esperienza web dedicata - la dashboard di gestione vive in una React PWA separata dal backend, mentre il sito pubblico di MinePanel è costruito con SvelteKit.
• 🔐 Autenticazione pensata per un vero panel - sessioni JWT tramite cookie HttpOnly, refresh session, 2FA, recovery flow, rate limiting e bootstrap automatico del primo amministratore.
• 🧱 Infrastruttura di tua proprietà - PostgreSQL, dati Minecraft, container Docker e API di gestione restano tutti sotto il controllo dell'operatore.

Il Segreto

Ho costruito il progetto usando:

• NestJS 11 + TypeScript per il backend. Volevo moduli ben separati, dependency injection, guard, validazione e abbastanza struttura da poter far crescere l'API senza trasformarla in una gigantesca raccolta di route.
• Bun 1.3.14 come runtime JavaScript di produzione e package manager. Startup rapido e workflow di sviluppo leggero si sposano molto bene con il progetto.
• PostgreSQL 16 come unica dipendenza stateful. MinePanel evita intenzionalmente Redis, code esterne o altri servizi infrastrutturali finché non esiste una reale necessità.
• Drizzle ORM 0.45.2 per accesso al database e migrazioni. Mantiene lo schema vicino a TypeScript senza allontanarsi troppo dal modo di ragionare di SQL.
• Dockerode 4 per comunicare direttamente con il Docker daemon locale. È ciò che permette a MinePanel di creare, ispezionare, avviare, fermare, riavviare ed eliminare container Minecraft programmaticamente.
• itzg/minecraft-server come base per i container Minecraft. Offre una foundation matura e pensata per Docker, mentre MinePanel costruisce sopra l'orchestrazione e la gestione.
• Caddy 2 per HTTPS automatico e reverse proxy. Configurare TLS non dovrebbe diventare un tutorial da venti passaggi solo per distribuire un panel Minecraft.
• Socket.IO per la comunicazione in tempo reale, partendo dalle metriche dell'host e lasciando spazio a eventi server più ricchi in futuro.
• React 19 + Vite 7 + TanStack Query per la dashboard PWA. Il frontend è deliberatamente un'applicazione separata, non qualcosa di accoppiato ai template NestJS.
• Svelte 5 + SvelteKit 2 per il sito marketing. Uno stack piccolo e veloce per un sito che ha esigenze molto diverse da quelle della dashboard.
• Kotlin Multiplatform + Compose Multiplatform è invece la direzione prevista per il futuro client mobile, con Android e iOS che condivideranno lo stesso core applicativo.

Sfide e Soluzioni

Dare a un'Applicazione il Controllo di Docker 🔐

• Sfida: montare /var/run/docker.sock dentro un'applicazione significa darle, di fatto, un enorme controllo sull'host. Trattarlo come una normale dipendenza API sarebbe stato irresponsabile.
• Soluzione: ho progettato il layer Docker attorno a trust boundary espliciti. L'API NestJS non viene esposta direttamente a Internet, i dati Minecraft sono montati read-only nel backend, la configurazione del Docker socket viene validata, i container Minecraft vengono creati solo tramite percorsi controllati server-side e le regole di lifecycle e risorse vengono applicate prima che le operazioni vengano accettate.
• Risultato: MinePanel può offrire la comodità della gestione dinamica dei container senza fingere che l'accesso al Docker daemon sia innocuo. L'architettura rende esplicito il punto pericoloso e mi dà un confine chiaro da continuare a rafforzare.

Permessi Senza una Montagna di if 🎯

• Sfida: una semplice divisione ADMIN / USER smette di funzionare quasi subito quando entrano in gioco moderatori, server privati, community e responsabilità diverse per ogni server.
• Soluzione: ho separato i ruoli globali dall'autorizzazione per singolo server. MinePanel ha ruoli ADMIN, MOD e USER, permessi granulari per i MOD, visibilità specifica dei server e workflow espliciti di approvazione tramite REQUEST. L'autorizzazione viene applicata nel backend e non trattata come semplice stato dell'interfaccia.
• Risultato: un moderatore può ricevere esattamente le operazioni di cui ha bisogno, mentre ogni singolo server può mantenere la propria policy di accesso. Questo dà a MinePanel spazio per diventare adatto a vere community multiutente, invece di essere utile solo a un amministratore.

Fare in Modo che lo Stato dei Server Sopravviva alla Realtà 🔄

• Sfida: le operazioni Docker sono asincrone, esterne e ogni tanto falliscono nei momenti peggiori. Un database che dice che un server è RUNNING non fa magicamente partire il container, e due richieste lifecycle contemporanee possono facilmente portare a stati incoerenti.
• Soluzione: le transizioni del lifecycle sono progettate attorno a cambi di stato espliciti, aggiornamenti in stile compare-and-swap, controlli preventivi sulle risorse e percorsi di errore che evitano di dichiarare successo quando l'esito dell'operazione Docker è incerto.
• Risultato: il backend si comporta molto più come un controller infrastrutturale che come un semplice CRUD attorno a Docker. Questa distinzione è diventata sempre più importante con la crescita di MinePanel.

Dietro le Quinte

Il backend attuale di MinePanel si è evoluto nell'arco di circa sei mesi e, a un certo punto, ha definitivamente smesso di essere un piccolo side project. Ogni volta che completavo un livello, compariva il problema reale successivo: l'autenticazione ha portato alle sessioni, le sessioni al recovery e alla 2FA, i ruoli ai permessi per server, la gestione del lifecycle Docker alla concorrenza e ai controlli sulle risorse, e il self-hosting ha portato ai problemi di deployment, sicurezza e trust boundary.

Una delle cose che ho imparato di più è quanto velocemente "fare un panel" si trasformi in systems design. L'interfaccia è quasi la parte semplice. Il lavoro interessante è decidere cosa succede se Docker sparisce a metà di un'operazione, come impedire che due richieste combattano per lo stato dello stesso server, come devono combinarsi i permessi di un moderatore con la visibilità del server o quanto sia sensato fidarsi di un'applicazione che può raggiungere il Docker daemon.

Ho anche usato molto gli agenti AI durante lo sviluppo di MinePanel. Sono stati estremamente utili come implementatori, reviewer e coppie di occhi aggiuntive, ma questo ha reso ancora più importante avere una specifica forte e un'architettura chiara, non meno. Quando puoi produrre codice molto velocemente, anche una cattiva decisione architetturale può propagarsi molto velocemente. Gran parte del mio lavoro si è quindi spostata dal digitare ogni singola riga al definire invarianti, revisionare decisioni, verificare assunzioni e assicurarmi che tutte le parti continuassero a descrivere un unico sistema coerente.

Probabilmente è proprio per questo che MinePanel significa per me qualcosa in più rispetto alla sua descrizione superficiale. Sì, è un panel per server Minecraft, ma per me è diventato anche un esercizio nel costruire un vero prodotto backend-heavy: autenticazione, autorizzazioni, database, container orchestration, comunicazione real-time, sicurezza infrastrutturale, client multipli, deployment e una roadmap che deve restare coerente mentre tutti questi pezzi crescono insieme. Alcune parti sono state davvero difficili, e ci sono ancora attività di hardening e intere fasi da costruire. Ma è proprio questo il punto. Non voglio che MinePanel sia un mockup elegante di un'idea ambiziosa. Voglio continuare a trasformare quell'idea ambiziosa in infrastruttura che funziona davvero.

Per Iniziare

Ti serve una macchina Linux con Docker, un dominio puntato all'host e le porte 80 e 443 disponibili.

git clone https://github.com/MinePanelProject/minepanel-backend
cd minepanel-backend

cp .env.example .env

# Configura dominio, password del database, JWT secret,
# encryption key, setup token e percorso dei dati Minecraft.
$EDITOR .env

docker compose pull
docker compose up -d

Caddy si occupa automaticamente del provisioning del certificato, le migrazioni PostgreSQL vengono eseguite come parte del deployment e MinePanel può iniziare a gestire i container Minecraft presenti sull'host.

Il backend si trova attualmente nella fase release candidate della v1.0, con le fondamenta dell'autorizzazione che stanno già entrando nella fase successiva. Da qui la roadmap diventa molto più interessante: controlli server real-time più avanzati, console, backup, task schedulati, gestione giocatori e plugin, preset per la creazione dei server, funzionalità di networking, un'esperienza PWA completa e, più avanti, l'app mobile KMP.

L'obiettivo finale non è cambiato: rendere la gestione di una vera infrastruttura Minecraft sul proprio hardware comoda quanto l'utilizzo di un panel hosted, senza dover rinunciare alla proprietà per ottenere quella comodità.