# Configuration

# Configuration

Complete reference for all configuration options in KyuubiSoft Panel.

## Environment Variables

### Required Variables

These must be set for the panel to function:

| Variable | Description | Example |
|----------|-------------|---------|
| `JWT_SECRET` | Token signing key (min 32 chars) | `openssl rand -base64 48` |
| `MANAGER_USERNAME` | Admin login username | `admin` |
| `MANAGER_PASSWORD` | Admin password (min 12 chars) | `SecurePass123!` |
| `CORS_ORIGINS` | Allowed API origins | `http://localhost:18080` |

### Server Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `JAVA_MIN_RAM` | `3G` | Minimum JVM heap size |
| `JAVA_MAX_RAM` | `4G` | Maximum JVM heap size |
| `SERVER_PORT` | `5520` | Game server port (UDP) |
| `SERVER_BIND` | `0.0.0.0` | Network bind address |
| `AUTH_MODE` | `authenticated` | `authenticated` or `offline` |
| `TZ` | `Europe/Berlin` | Container timezone |

### Download Options

| Variable | Default | Description |
|----------|---------|-------------|
| `USE_HYTALE_DOWNLOADER` | `false` | Use official Hytale downloader |
| `HYTALE_PATCHLINE` | `release` | `release` or `pre-release` |
| `AUTO_UPDATE` | `false` | Auto-update on restart |
| `SERVER_JAR_URL` | - | Custom JAR download URL |
| `ASSETS_URL` | - | Custom assets download URL |

### Panel Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `MANAGER_PORT` | `18080` | Web panel port |
| `TRUST_PROXY` | `false` | Enable for reverse proxy |
| `SECURITY_MODE` | `strict` | `strict` or `warn` |
| `DEMO_MODE` | `false` | Run with mock data |

### Resource Limits

| Variable | Default | Description |
|----------|---------|-------------|
| `DOCKER_MEMORY_LIMIT` | `8G` | Container memory limit |
| `DOCKER_CPU_LIMIT` | `4` | Container CPU limit |

### Backup Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `ENABLE_BACKUP` | `false` | Enable built-in backups |
| `BACKUP_FREQUENCY` | `30` | Backup interval (minutes) |

### Optional Integrations

| Variable | Description |
|----------|-------------|
| `MODTALE_API_KEY` | Modtale mod store API key |
| `STACKMART_API_KEY` | StackMart store API key |
| `CURSEFORGE_API_KEY` | CurseForge API key (optional) |

### WebMap Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `WEBMAP_PORT` | `18081` | Live map HTTP port |
| `WEBMAP_WS_PORT` | `18082` | Live map WebSocket port |

## Docker Volumes

The stack uses these persistent volumes:

| Volume | Path | Purpose |
|--------|------|---------|
| `hytale-server` | `/opt/hytale/server` | Server JAR and assets |
| `hytale-data` | `/opt/hytale/data` | Worlds, configs, panel data |
| `hytale-backups` | `/opt/hytale/backups` | Backup storage |
| `hytale-plugins` | `/opt/hytale/plugins` | Server plugins |
| `hytale-mods` | `/opt/hytale/mods` | Server mods |
| `hytale-downloader` | `/opt/hytale/downloader` | Downloader credentials |
| `hytale-auth` | `/opt/hytale/auth` | Server auth data |

## Server Configuration Files

### config.json

Main server configuration at `/opt/hytale/data/config.json`:

```json
{
  "serverName": "My Hytale Server",
  "motd": "Welcome to the server!",
  "maxPlayers": 20,
  "gamemode": "adventure",
  "difficulty": "normal",
  "pvp": true,
  "whitelist": false
}
```

### panel-config.json

Panel-specific settings at `/opt/hytale/data/panel-config.json`:

```json
{
  "acceptEarlyPlugins": false,
  "disableSentry": false,
  "allowOp": true,
  "patchline": "release"
}
```

### Update Configuration

Native update system settings in server `config.json`:

```json
{
  "updateConfig": {
    "enabled": true,
    "checkIntervalSeconds": 3600,
    "notifyPlayersOnAvailable": true,
    "patchline": "release",
    "runBackupBeforeUpdate": true,
    "backupConfigBeforeUpdate": true,
    "autoApplyMode": "DISABLED",
    "autoApplyDelayMinutes": 5
  }
}
```

**Auto-Apply Modes:**
- `DISABLED` - Manual updates only
- `WHEN_EMPTY` - Update when no players online
- `SCHEDULED` - Update after delay

## Reverse Proxy Setup

For HTTPS access via nginx or traefik:

### Nginx Example

```nginx
server {
    listen 443 ssl;
    server_name panel.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:18080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Set in `.env`:
```bash
TRUST_PROXY=true
CORS_ORIGINS=https://panel.yourdomain.com
```

## Multiple Instances

Run multiple servers on the same host:

```bash
# Instance 1
STACK_NAME=hytale-prod HOST_DATA_PATH=/opt/hytale-prod docker-compose up -d

# Instance 2
STACK_NAME=hytale-test HOST_DATA_PATH=/opt/hytale-test docker-compose up -d
```

Each instance gets its own containers and data directory.