Skip to main content

Getting Started

This guide walks you through installing and configuring the KyuubiSoft Panel.

Prerequisites​

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • 4GB+ RAM available
  • UDP port 5520 open (game traffic)
  • TCP port 18080 open (web panel)

Installation​

Step 1: Clone Repository​

git clone https://github.com/KyuubiDDragon/KyuubiSoft-Hytale-Panel.git
cd KyuubiSoft-Hytale-Panel

Step 2: Create Environment File​

cp .env.example .env

Step 3: Configure Required Variables​

Edit .env and set these required variables:

# Generate a secure JWT secret (minimum 32 characters)
JWT_SECRET=$(openssl rand -base64 48)

# Set your panel access
MANAGER_USERNAME=admin
MANAGER_PASSWORD=YourSecurePassword123!

# Configure CORS (your panel URL)
CORS_ORIGINS=http://localhost:18080
Important

Never use default passwords in production. The password should be at least 12 characters.

Step 4: Choose Server Files Method​

USE_HYTALE_DOWNLOADER=true
HYTALE_PATCHLINE=release

On first start, the panel will display an OAuth login link. Complete the login to download server files automatically.

Option B: Custom Download URLs​

If you have the server files hosted elsewhere:

SERVER_JAR_URL=https://your-server.com/HytaleServer.jar
ASSETS_URL=https://your-server.com/Assets.zip

Option C: Manual File Copy​

After starting the containers:

docker cp HytaleServer.jar hytale:/opt/hytale/server/
docker cp Assets.zip hytale:/opt/hytale/server/
docker restart hytale

Step 5: Start the Stack​

docker-compose up -d

Step 6: Server Authentication​

Attach to the server container and authenticate:

docker attach hytale

Then run:

/auth login device

Open the displayed URL in your browser and enter the code.

Step 7: Access the Panel​

Navigate to http://YOUR-SERVER-IP:18080 and login with your configured credentials.

Portainer Deployment​

  1. Go to Portainer → Stacks → Add Stack
  2. Name: hytale
  3. Select Repository and enter: 
    https://github.com/KyuubiDDragon/KyuubiSoft-Hytale-Panel
  4. Add environment variables (not in .env file)
  5. Deploy

Verifying Installation​

After starting, verify everything is working:

# Check container status
docker-compose ps

# View server logs
docker-compose logs -f hytale

# View panel logs
docker-compose logs -f hytale-manager

The panel should show:

  • Server status: Online
  • Players: 0/max
  • Memory usage statistics

First Steps After Setup​

  1. Configure Server Settings

    • Go to Settings → Quick Settings
    • Set server name and MOTD

  2. Create Additional Users

    • Go to Users → Add User
    • Assign appropriate roles

  3. Set Up Backups

    • Go to Scheduler
    • Create automated backup tasks

  4. Install Mods/Plugins

    • Go to Mods & Plugins
    • Browse CurseForge or upload manually

Troubleshooting​

Container won't start​

# Check logs
docker-compose logs hytale

# Verify file permissions
ls -la /opt/hytale/

Permission denied errors​

Fix file permissions:

sudo chown -R 9999:9999 /opt/hytale
sudo chmod -R g+rw /opt/hytale

Panel can't connect to server​

Ensure both containers are on the same network:

docker network inspect hytale-net

OAuth login fails​

Check the downloader credentials:

docker exec hytale cat /opt/hytale/downloader/.hytale-downloader-credentials.json

Next Steps​