# 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

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

### Step 2: Create Environment File

```bash
cp .env.example .env
```

### Step 3: Configure Required Variables

Edit `.env` and set these **required** variables:

```bash
# 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)

```bash
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:

```bash
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:

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

### Step 5: Start the Stack

```bash
docker-compose up -d
```

### Step 6: Server Authentication

Attach to the server container and authenticate:

```bash
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:

```bash
# 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

```bash
# Check logs
docker-compose logs hytale

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

### Permission denied errors

Fix file permissions:
```bash
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:
```bash
docker network inspect hytale-net
```

### OAuth login fails

Check the downloader credentials:
```bash
docker exec hytale cat /opt/hytale/downloader/.hytale-downloader-credentials.json
```

## Next Steps

- [Configuration Reference](./configuration) - All configuration options
- [User Management](./user-management) - Set up users and permissions
- [Server Management](./server-management) - Manage your server