Scripts Reference

All scripts live under /opt/scripts/ in the container. Library scripts (lib/) are sourced by the entrypoint and other scripts. Command scripts (cmd/) are standalone executables for external use.

Table of Contents

• Script Relationships
• Entrypoint
• Library Scripts
• Command Scripts
• Health Check

Script Relationships

graph TD
    E[entrypoint.sh] -->|sources| U[lib/utils.sh]
    E -->|sources| S[lib/state.sh]
    E -->|sources| A[lib/auth.sh]
    E -->|sources| O[lib/options.sh]
    E -->|sources| C[lib/config.sh]
    E -->|sources| D[lib/download.sh]
    E -->|sources| API[lib/api.sh]

    E -->|spawns bg| AU[cmd/auto-update.sh]

    H[healthcheck.sh] -->|sources| U
    H -->|sources| S

    ST[cmd/status.sh] -->|sources| U
    ST -->|sources| S
    ST -->|sources| D
    ST -->|sources| O

    UP[cmd/update.sh] -->|sources| U
    UP -->|sources| S
    UP -->|sources| D

    AU -->|sources| U
    AU -->|sources| S
    AU -->|sources| D

    AI[cmd/auth-init.sh] -->|sources| U
    AI -->|sources| S
    AI -->|sources| A

    EX[cmd/exec.sh] -->|sources| U

    SU[cmd/schedule-update.sh] -->|sources| U
    SU -->|sources| S
    SU -->|sources| D

Entrypoint

entrypoint.sh

The main container startup script. Orchestrates initialization, downloads, authentication, and server launch.

Startup Sequence:

flowchart TD
    A[Container Start] --> B[Source library scripts]
    B --> C[Early diagnostics]
    C --> C1{x86_64?}
    C1 -->|No| C2[Exit 1]
    C1 -->|Yes| D[Check permissions]
    D --> D1{/data writable?}
    D1 -->|No| D2[Exit 1]
    D1 -->|Yes| E[Setup user PUID/PGID]
    E --> F[Create directories]
    F --> G[Initialize state files]
    G --> H[Check for scheduled update]
    H --> H1{.update-on-restart?}
    H1 -->|Yes| H2[Perform update]
    H1 -->|No| I[Detect existing files]
    H2 --> I
    I --> I1{Server files exist?}
    I1 -->|No| J[Download server files]
    I1 -->|Yes| K{AUTO_UPDATE?}
    J --> L
    K -->|Yes| K1[Check for update]
    K -->|No| L
    K1 --> L
    L[Validate mods] --> L1{SKIP_BROKEN_MODS?}
    L1 -->|Yes| L2[Quarantine broken mods]
    L1 -->|No| M
    L2 --> M
    M[Generate config.json] --> N[Generate API config]
    N --> O[Authenticate OAuth]
    O --> O1{Tokens valid?}
    O1 -->|No| O2[Device code flow]
    O1 -->|Yes| P[Drop privileges]
    O2 --> P
    P --> Q[Start version checker bg]
    Q --> R[Start mod monitor bg]
    R --> S[Launch Java server]
    S --> T[Wait for exit]
    T --> U[Cleanup and exit]

Signal Handling:

• SIGTERM / SIGINT — Gracefully stops the server, updates state to stopped, and exits

Key Environment Variables:

PUID, PGID, UMASK, SERVER_PORT, JAVA_XMS, JAVA_XMX, ENABLE_AOT, PATCHLINE, AUTO_UPDATE, SKIP_BROKEN_MODS, DEBUG, VERSION_CHECK_ENABLED, VERSION_CHECK_INTERVAL

Library Scripts

lib/utils.sh

Core utility library sourced by all scripts.

Logging Functions:

JSON Helpers:

Auto-type detection handles numbers, booleans (true/false), nested objects/arrays, and strings (with proper escaping).

Boolean Helpers:

File and Process Utilities:

lib/state.sh

Manages persistent state via atomic JSON files in /data/.state/.

Core Operations:

Server State (server.json):

Version State (version.json):

Auth State (auth.json):

Config State (config.json):

Health State (health.json):

Mods State (mods.json):

Broken Mods (.broken-mods):

Update State (update.json):

Scheduled Updates (.update-on-restart):

lib/auth.sh

Implements OAuth2 Device Code Flow for Hytale authentication.

Exports: SESSION_TOKEN, IDENTITY_TOKEN, OWNER_UUID

OAuth Endpoints:

lib/options.sh

Builds JVM and Hytale server command-line arguments from environment variables.

GC Configuration:

• G1GC (default): MaxGCPauseMillis, NewSizePercent, MaxNewSizePercent, HeapRegionSize, StringDeduplication, AlwaysPreTouch, ParallelRefProcEnabled
• ZGC: UseZGC, ZGenerational, ZCollectionInterval

lib/config.sh

Generates server config.json and whitelist from environment variables.

Private helpers: _generate_whitelist, _update_config_state

lib/download.sh

Manages server file downloads, extraction, and version tracking.

File Layout Detection:

The script auto-detects two possible directory layouts:

• Layout 1: /data/Server/HytaleServer.jar
• Layout 2: /data/game/Server/HytaleServer.jar

lib/api.sh

Configures the HytaleAPI REST plugin.

Command Scripts

cmd/status.sh

Reports comprehensive server status.

# Human-readable output
docker exec hyos-server /opt/scripts/cmd/status.sh

# JSON output
docker exec hyos-server /opt/scripts/cmd/status.sh --json

JSON output fields: server (running, pid, uptime_seconds), version (current, latest, needs_update), resources (memory_used/total, disk_used/total), config (JVM settings, port), timestamp.

cmd/update.sh

Manually trigger a server update. The server must be stopped.

# Check for updates (dry run)
docker exec hyos-server /opt/scripts/cmd/update.sh --check

# Update with backup
docker exec hyos-server /opt/scripts/cmd/update.sh --backup --force

Process: Verify stopped → detect files → compare versions → backup → download → extract → verify → update .version.

cmd/auto-update.sh

Background service for periodic update checks.

# Single check and exit (for cron)
docker exec hyos-server /opt/scripts/cmd/auto-update.sh --once

# Continuous loop (started by entrypoint)
/opt/scripts/cmd/auto-update.sh

Environment Variables: AUTO_UPDATE_INTERVAL, AUTO_UPDATE_TIME, AUTO_UPDATE_RESTART, AUTO_UPDATE_BACKUP

Logs: Written to /data/logs/auto-update.log

Signal Handling: SIGTERM/SIGINT trigger graceful shutdown. Server stop uses SIGTERM with 60-second timeout, then SIGKILL.

cmd/auth-init.sh

Interactive re-authentication.

docker exec -it hyos-server /opt/scripts/cmd/auth-init.sh

Checks for existing valid tokens, prompts before re-authenticating, runs the device code flow, fetches profile, and saves tokens.

cmd/exec.sh

Execute a server console command by writing to the server process stdin.

docker exec hyos-server /opt/scripts/cmd/exec.sh "say Hello World"
docker exec hyos-server /opt/scripts/cmd/exec.sh "op add PlayerName"

Mechanism: Writes the command string to /proc/<server-PID>/fd/0 (stdin file descriptor).

cmd/schedule-update.sh

Schedule a server update for the next container restart.

# Schedule
docker exec hyos-server /opt/scripts/cmd/schedule-update.sh

# Check if scheduled
docker exec hyos-server /opt/scripts/cmd/schedule-update.sh --check

# Cancel
docker exec hyos-server /opt/scripts/cmd/schedule-update.sh --clear

Creates a .update-on-restart flag file (JSON with target version) that the entrypoint checks on startup.

Health Check

healthcheck.sh

Periodic health probe for Docker and the Manager UI.

# Simple check (exit 0 = healthy, 1 = unhealthy)
docker exec hyos-server /opt/scripts/healthcheck.sh

# JSON output
docker exec hyos-server /opt/scripts/healthcheck.sh --json

Checks Performed:

Docker Integration:

healthcheck:
  test: ["CMD", "/opt/scripts/healthcheck.sh"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 180s

The 180-second start period accounts for first-run downloads and authentication.