Creating a Dockerfile for your server

Hathora Cloud utilizes Docker, which is a technology that allows you to package your server project in a portable way so that it can be run in any Linux environment.

In order to deploy on Hathora Cloud, you will need to provide a Dockerfile in the root of your tar file:

tar.gz file
├── Dockerfile
└── <...your server build/project files>

note

You will not need to have Docker installed on your machine, the Docker build happens on Hathora build servers.

The core structure of a Dockerfile contains:

1. Base OS and packages (FROM)
2. Copy project files into container (COPY)
3. Configure build steps (RUN) - can skip if you've already copied a Linux executable in step 2
4. Start command (CMD)

Unity

FROM ubuntu:22.04

# Add these dependencies to enable your server to make outbound TLS requests
RUN apt-get update && \
  apt-get install -y ca-certificates && \
  update-ca-certificates

# Copy the server build files into the container, if Dockerfile is @ parent
COPY ./Server-Build-Dir .

RUN chmod +x ./your_unity_server.x86_64


# Run the Linux server in headless mode as a dedicated server
CMD ./your_unity_server.x86_64 -mode server -batchmode -nographics

Check out our detailed onboarding guide for Unity.

Unreal

FROM ubuntu:22.04

# Add these dependencies to enable your server to make outbound TLS requests
RUN apt-get update && \
  apt-get install -y ca-certificates && \
  update-ca-certificates

# Unreal doesn't like running as root, so let's create a user
RUN groupadd --gid 1000 unreal \
  && useradd --uid 1000 --gid unreal --create-home unreal
USER unreal

# Now copy over your server build
WORKDIR /home/unreal
COPY --chown=unreal:unreal . .

# Make sure your init script and server binary are executable
# If you have any other binaries (e.g. crash handlers), make sure to set those as executable too!
RUN chmod +x init.sh
RUN chmod +x YourGame/Binaries/Linux/YourGameServer

# Start init script (passing any parameters you need)
CMD ./init.sh

Check out our detailed onboarding guide for Unreal.

JS/TS

FROM node:18-alpine # node version

COPY . .            # copy project files

RUN npm install     # install dependencies
RUN npm run build   # build project

# Add these dependencies to enable your server to make outbound TLS requests
RUN apk update && apk upgrade && \
  apk add ca-certificates && \
  update-ca-certificates

CMD npm start       # start server

Check out our detailed onboarding guide for JS/TS.

Godot

FROM centos:centos8

RUN cd /etc/yum.repos.d/
RUN sed -i 's/mirrorlist/#mirrorlist/g' /etc/yum.repos.d/CentOS-*
RUN sed -i 's|#baseurl=http://mirror.centos.org|baseurl=http://vault.centos.org|g' /etc/yum.repos.d/CentOS-*

RUN yum install -y wget unzip libXcursor openssl openssl-libs libXinerama libXrandr-devel libXi alsa-lib pulseaudio-libs mesa-libGL

# TODO: replace with your Godot version
ENV GODOT_VERSION "4.0.1"

# Install Godot Server
RUN wget -q https://downloads.tuxfamily.org/godotengine/${GODOT_VERSION}/Godot_v${GODOT_VERSION}-stable_linux.x86_64.zip \
&& unzip Godot_v${GODOT_VERSION}-stable_linux.x86_64.zip \
&& mv Godot_v${GODOT_VERSION}-stable_linux.x86_64 /usr/local/bin/godot \
&& chmod +x /usr/local/bin/godot

# Add these dependencies to enable your server to make outbound TLS requests
RUN dnf -y update && \
    dnf -y install ca-certificates && \
    update-ca-trust

COPY your_game_server.pck .

CMD /usr/local/bin/godot --headless --main-pack ./your_game_server.pck

Check out our detailed onboarding guide for Godot.

Other

Check out Docker's official guide to containerizing an application, or reach out on our Discord for help

Join our developer community!

Discord

Optional init.sh script

You can optionally use an init.sh script in a Dockerfile to handle tasks that need to occur before launching the game server. For example, parsing environment variables, passing Hathora metadata as command line args, or any other initialization logic that must be completed before the container starts.

#!/usr/bin/env bash

echo "Beginning init.sh script..."

# Hathora default environment variables (these are added by Hathora automatically)
echo "HATHORA_INITIAL_ROOM_CONFIG : $HATHORA_INITIAL_ROOM_CONFIG"
echo "HATHORA_PROCESS_ID : $HATHORA_PROCESS_ID"
echo "HATHORA_APP_ID : $HATHORA_APP_ID"
echo "HATHORA_DEPLOYMENT_ID : $HATHORA_DEPLOYMENT_ID"
echo "HATHORA_BUILD_TAG : $HATHORA_BUILD_TAG"

# These need to be add manually as environment variables (via application's deployment config)
echo "HATHORA_API_TOKEN : $HATHORA_API_TOKEN"

host=$HATHORA_HOSTNAME
port=$HATHORA_DEFAULT_PORT
echo "Connection info: $host:$port"

# Parse custom EnvVariable "COMMAND_LINE_ARGS"
# Add this as an environment variable when your create your deployment - either in Console UI or via CI integration
# Example value for $COMMAND_LINE_ARGS: "-batchmode -nographics -mode server"
echo "COMMAND_LINE_ARGS : $COMMAND_LINE_ARGS"

# Parse room config
# TODO: replace 'example_room_config' with $HATHORA_INITIAL_ROOM_CONFIG
example_room_config='{"property1":"sample-data-123","property2":[1,2,3],"property3":{"value":"test"},"property4":false}'
# Extract specific JSON properties using jq
gameInstanceId=$(echo "$example_room_config" | jq '.gameInstanceId')
gameSessionQueueName=$(echo "$example_room_config" | jq '.gameSessionQueueName')
maximumPlayerSessionCount=$(echo "$example_room_config" | jq '.maximumPlayerSessionCount')
property4=$(echo "$example_room_config" | jq '.property4')
echo "gameInstanceId: $gameInstanceId"
echo "gameSessionQueueName: $gameSessionQueueName"
echo "property3: $property3"
echo "property4: $property4"

echo "Starting game server..."

# TODO: replace with your own game server start command
./Hathora-Unity_LinuxServer.x86_64 $COMMAND_LINE_ARGS