Spawn Panel

A self-hosted web panel to create and manage Minecraft (and Hytale) servers with Docker — from your PC or any VPS.

Status: Early release · Actively developed · Contributions welcome

---

Features

• Server management — create, start, stop, restart and delete servers in one click
• Live console — send commands and read output in real time via WebSocket
• File manager — browse, edit, upload and delete server files from the browser
• Mod installer — search and install mods directly from CurseForge
• Automatic backups — schedule backups with configurable retention policies
• Role-based access — superadmin / admin / moderator roles
• Multi-language — i18n ready (add your own locale file)
• Docker-based — each server runs in its own container; no manual Java setup required

---

Requirements

• Docker and Docker Compose
• A Linux host (PC or VPS) — Windows is supported via Docker Desktop
• Port 8000 (API) and 5173 (frontend dev) free, or configure your own reverse proxy

---

Quick start

# 1. Clone the repository
git clone https://github.com/YOUR_USERNAME/spawn-panel.git
cd spawn-panel

# 2. Create your environment file
cp .env.example .env

# 3. Edit .env — at minimum set a strong SECRET_KEY
#    Generate one with:  openssl rand -hex 32
nano .env

# 4. Start the panel
docker compose up -d

# 5. Open the panel in your browser
#    http://localhost:5173

Default credentials on first launch:

Username	Password
admin	P@ssw0rd

You will be prompted to change the password on first login.

---

Environment variables

Copy .env.example to .env and fill in the values:

Variable	Required	Description
SECRET_KEY	Yes	JWT signing key. Generate with: openssl rand -hex 32
PANEL_BASE_DIR	No	Base dir for servers and backups. Default: /opt/spawn-panel
CURSE_API_KEY	No	CurseForge API key for the mod installer (optional)

Note on CORS: In the default setup the Vite dev server proxies all API calls, so CORS is never triggered. If you serve the built frontend from a different origin than the backend API, edit allow_origins in backend/main.py to list your frontend domain explicitly.

---

Project structure

spawn-panel/
├── backend/          # FastAPI application
│   ├── routers/      # API endpoints (auth, servers, console, files, mods, backups)
│   ├── main.py       # App entry point & startup tasks
│   ├── database.py   # SQLAlchemy models & SQLite setup
│   ├── docker_handler.py  # Docker SDK integration
│   ├── backup_handler.py  # Backup logic & retention
│   └── config.py     # Environment-based configuration
├── frontend/         # Vue 3 + Vite + Tailwind CSS
│   └── src/
│       ├── views/    # Page-level components
│       └── components/  # Shared UI components
├── docker-compose.yml
├── .env.example
└── LICENSE

---

Tech stack

Layer	Technology
Backend	Python 3.11, FastAPI, SQLAlchemy, SQLite
Frontend	Vue 3, Vite, Tailwind CSS
Runtime	Docker, Docker Compose
Auth	JWT (PyJWT + bcrypt)
Real-time	WebSocket

---

Contributing

Pull requests are welcome. For major changes please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Open a pull request

---

Support the project

If you find this project useful, consider supporting its development:

☕ Support on Ko-fi

---

License

MIT — free to use, modify, and distribute.