Getting Started

This guide walks you through deploying BadgerPanel using Docker Compose. By the end, you will have a fully functional panel with the API, web frontend, database, cache, object storage, and reverse proxy all running on a single server.

Prerequisites

System Requirements

Requirement	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	20 GB SSD	50+ GB SSD
OS	Ubuntu 20.04+ / Debian 11+ / RHEL 8+	Ubuntu 22.04 LTS

Panel vs Game Servers

These requirements are for the Panel only. Game servers run on separate Daemon nodes or Kubernetes clusters with their own resource requirements.

Software Requirements

• Docker 24.0+ and Docker Compose v2
• Git for cloning the repository
• A domain name pointed at your server's public IP
• Ports 80 and 443 open in your firewall

Installing Docker

If Docker is not already installed:

# Ubuntu / Debian
curl -fsSL https://get.docker.com | bash

# Verify installation
docker --version
docker compose version

Root or Docker Group

Docker commands require root access or membership in the docker group. The setup commands in this guide assume you are running as root or using sudo.

Step 1: Clone the Repository

# Clone the BadgerPanel repository
git clone https://github.com/badgerpanel/panel.git /opt/badgerpanel
cd /opt/badgerpanel

Step 2: Run the Setup Script

BadgerPanel includes an interactive setup script that generates all configuration files, creates secure passwords, and prepares the environment.

chmod +x scripts/setup.sh
./scripts/setup.sh

The setup script will prompt you for:

Prompt	Description	Example
Domain name	Your panel's domain	panel.your-domain.com
SSL mode	Certificate configuration	letsencrypt, custom, or selfsigned
Email address	For Let's Encrypt and admin account	admin@your-domain.com
Admin password	Password for the initial admin account	(minimum 8 characters)

The script automatically:

• Generates secure random passwords for MySQL, Redis, and MinIO
• Creates the .env file with all required environment variables
• Configures Nginx with your domain and SSL settings
• Sets up MinIO buckets for backup storage
• Prepares Docker Compose overrides if needed

What Gets Generated

After running the setup script, you will find a .env file in the project root containing all configuration. See Configuration for details on every variable.

Step 3: Start the Stack

docker compose up -d

This pulls all required images and starts the following services:

Service	Description
api	Go API server (runs database migrations on startup)
web	Next.js frontend application
nginx	Reverse proxy with TLS termination
mysql	MySQL 8.0 database
redis	Redis 7 for cache and sessions
minio	MinIO object storage for backups
daemon-builder	Compiles BadgerDaemon binaries (amd64, arm64, arm)
orchestrator-builder	Compiles BadgerOrchestrator binaries (amd64, arm64)

First Startup

The first startup takes a few minutes as Docker pulls images, compiles the daemon/orchestrator binaries, and runs database migrations. Subsequent startups are much faster.

Verify Services Are Running

docker compose ps

All services should show a status of Up or Up (healthy). If any service is restarting or exited, check its logs:

# View logs for a specific service
docker compose logs api
docker compose logs web
docker compose logs nginx

Step 4: Access the Panel

Once all services are running, open your browser and navigate to:

https://panel.your-domain.com

Self-Signed Certificates

If you chose selfsigned during setup, your browser will show a security warning. This is expected for development environments. Click "Advanced" and proceed to the site.

Step 5: First Login

Log in with the admin credentials you set during the setup script:

• Email: The email address you provided
• Password: The admin password you set

After logging in, you will land on the client dashboard. To access the admin area, click the Admin link in the sidebar or navigate to:

https://panel.your-domain.com/admin

Step 6: Initial Configuration

After your first login, configure these essential settings in the admin area:

1. General Settings

Navigate to Admin > Settings > General and verify:

• Panel name and description
• Panel URL matches your domain
• Default timezone is correct
• Registration is enabled or disabled as desired

2. Email Configuration

Navigate to Admin > Settings > Email and configure SMTP:

SMTP Host:     smtp.your-provider.com
SMTP Port:     587
Encryption:    STARTTLS
Username:      your-smtp-username
Password:      your-smtp-password
From Address:  noreply@your-domain.com
From Name:     BadgerPanel

Use the Send Test Email button to verify your configuration.

Email Providers

Common SMTP providers include Mailgun, SendGrid, Amazon SES, Postmark, and your domain's email hosting. Gmail SMTP works for testing but has daily sending limits.

3. Create Your First Node

To start hosting game servers, you need at least one Daemon node or Orchestrator cluster:

1. Navigate to Admin > Nodes
2. Click Create Node
3. Fill in the node details (name, FQDN, port allocations)
4. Copy the generated installation command
5. Run it on your game server node

See Installing the Daemon or Installing the Orchestrator for detailed instructions.

4. Import Game Eggs

1. Navigate to Admin > Nests
2. Create a nest (e.g., "Minecraft")
3. Click Import Egg to import game server templates
4. Upload the egg JSON file

BadgerPanel ships with eggs for popular games. See Supported Games for the full list.

5. Create a Server

Once you have a node online and eggs imported:

1. Navigate to Admin > Servers
2. Click Create Server
3. Select the owner, node, nest, and egg
4. Configure resource limits and startup variables
5. Click Create -- the server will be provisioned automatically

Directory Structure

After setup, the BadgerPanel installation directory looks like this:

/opt/badgerpanel/
├── docker-compose.yml      # Service definitions
├── .env                    # Environment configuration
├── scripts/
│   └── setup.sh            # Setup script
├── nginx/
│   ├── nginx.conf          # Nginx configuration
│   └── ssl/                # SSL certificates
├── data/
│   ├── mysql/              # MySQL data (persistent)
│   ├── redis/              # Redis data (persistent)
│   └── minio/              # MinIO data (persistent)
└── daemon-builds/          # Compiled daemon/orchestrator binaries

Data Persistence

The data/ directory contains all persistent data including your database, cache, and backups. Always back up this directory before performing updates or system maintenance.

Next Steps

• Configuration -- Customize environment variables and panel settings
• SSL Certificates -- Set up Let's Encrypt or custom certificates
• Installing the Daemon -- Add Docker game server nodes
• Billing Setup -- Configure Stripe, PayPal, and products
• Troubleshooting -- Common issues and solutions