Getting Started

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

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

Step 4: Choose Server Files Method

Option A: Official Hytale Downloader (Recommended)

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

• Configuration Reference - All configuration options
• User Management - Set up users and permissions
• Server Management - Manage your server