Name: HyOS
Author: HyOS

Deploy HyOS using Docker Compose on any Linux, macOS, or Windows system with Docker.

The simplest way to deploy HyOS is with Docker Compose. This works on any system with Docker installed.

Prerequisites

Docker Engine 24+ with Compose v2
8 GB RAM minimum
x86_64 architecture

Quick Deploy

Create a docker-compose.yml file:

x-api-config: &api-config
  API_CLIENT_SECRET: ${API_CLIENT_SECRET:-changeme123}
  API_CLIENT_ID: ${API_CLIENT_ID:-hyos-manager}

services:
  hyos-server:
    image: ghcr.io/editmysave/hyos/server:latest
    container_name: hyos-server
    stdin_open: true
    tty: true
    ports:
      - "30380:5520/udp"    # Game server
      - "30381:30381/tcp"   # API plugin
    volumes:
      - ./data:/data
    environment:
      <<: *api-config
      PUID: 1000
      PGID: 1000
      TZ: ${TZ:-UTC}
      JAVA_XMS: ${JAVA_XMS:-1G}
      JAVA_XMX: ${JAVA_XMX:-3G}
      API_ENABLED: "true"
      API_WEBSOCKET_ENABLED: "true"
      API_REGENERATE_CONFIG: "true"
    healthcheck:
      test: ["CMD", "/opt/scripts/healthcheck.sh"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
    restart: unless-stopped

  hyos-manager:
    image: ghcr.io/editmysave/hyos/manager:latest
    container_name: hyos-manager
    ports:
      - "30382:3000"
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      <<: *api-config
      REST_API_CLIENT_SECRET: ${API_CLIENT_SECRET:-changeme123}
      REST_API_CLIENT_ID: ${API_CLIENT_ID:-hyos-manager}
      ADAPTER_TYPE: rest
      HYTALE_CONTAINER_NAME: hyos-server
      HYTALE_STATE_DIR: /data/.state
      HYTALE_SERVER_HOST: hyos-server
      HYTALE_SERVER_PORT: "30381"
      NODE_ENV: production
      COOKIE_SECURE: "false"
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    restart: unless-stopped
    depends_on:
      - hyos-server

Then start it:

docker compose up -d

First Run

Check logs for the authentication prompt:

docker logs -f hyos-server

Complete the OAuth device flow when prompted
The server will download game files and start automatically
Access the manager UI at http://localhost:30382

Updating

Pull the latest images and recreate:

docker compose pull
docker compose up -d

Configuration

See the Configuration Reference for all available environment variables.

Next Steps

Configuration — Tune JVM, server settings, and auto-updates
Mods — Install and manage mods
Dashboard — Use the web UI
TrueNAS Deployment — Deploy on TrueNAS SCALE

Docker Compose Deployment