Development

Learn how to contribute to the Hytale Docker project and build custom images.

Project Structure

hytale-docker/
├── Dockerfile              # Main container image
├── docker-compose.yml      # Example deployment
├── README.md              # Project overview
├── docs/                  # Documentation site (Fumadocs)
│   ├── app/              # Next.js app
│   ├── components/       # React components
│   ├── content/          # MDX documentation
│   └── public/           # Static assets
├── examples/
│   └── docker-compose.yml # Example configurations
└── scripts/
    ├── auth-manager.sh    # OAuth2 authentication
    ├── entrypoint.sh     # Container startup
    └── update-server.sh  # Server update logic

Development Setup

Clone the Repository

git clone https://github.com/romariin/hytale-docker.git
cd hytale-docker

Install Dependencies

For documentation development:

cd docs
pnpm install  # or npm install

Run Documentation Locally

pnpm dev  # or npm run dev

Visit http://localhost:3000 to view the docs.

Build Docker Image

docker build -t hytale-server:dev .

Test Your Changes

# Use your custom image
cd examples
docker compose down
docker run --rm -it \
  -p 5520:5520/udp \
  -v hytale-data:/home/hytale/server \
  -v hytale-auth:/home/hytale/.config \
  hytale-server:dev

Building Custom Images

Modifying the Dockerfile

The base Dockerfile uses multi-stage builds:

# Stage 1: Base image with Java
FROM eclipse-temurin:25-jre-jammy AS base

# Stage 2: Application setup
FROM base AS app
# Copy scripts and set permissions

Adding Custom Scripts

To add your own scripts:

Create script in scripts/ directory

Add to Dockerfile:

COPY scripts/my-script.sh /app/scripts/
RUN chmod +x /app/scripts/my-script.sh

Call from entrypoint or other scripts

Custom Entrypoint

Modify scripts/entrypoint.sh to customize startup behavior:

#!/bin/bash
set -e

# Your custom initialization
echo "Running custom setup..."

# Call original entrypoint logic
/app/scripts/auth-manager.sh
/app/scripts/update-server.sh

# Start server
exec java $JAVA_OPTS -jar server.jar

Contributing

Development Workflow

Fork the repository
Create a feature branch:
```
git checkout -b feature/my-new-feature
```
Make your changes
Test thoroughly:
- Build Docker image
- Test server startup
- Verify authentication
- Check all documentation

Commit with clear messages:

git commit -m "feat: add custom server configuration support"

Push to your fork:
```
git push origin feature/my-new-feature
```
Open a Pull Request

Commit Convention

Follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
chore: Maintenance tasks
refactor: Code refactoring
test: Test additions/changes

Examples:

feat: add support for custom server properties
fix: resolve authentication token refresh issue
docs: update network setup guide
chore: upgrade base image to Java 25

Testing

Manual Testing

Build Test Image

docker build -t hytale-server:test .

Test Authentication Flow

# Clear previous auth
docker volume rm test_hytale-auth 2>/dev/null || true

# Run with test config
docker run --rm -it \
  -v test_hytale-auth:/home/hytale/.config \
  hytale-server:test

Verify:

Device code is displayed
Authentication URL is valid
Token is stored correctly
Server starts after auth

Test Update Mechanism

docker run --rm \
  -e AUTO_UPDATE=true \
  -v test_hytale-data:/home/hytale/server \
  hytale-server:test

Verify:

Update check runs
Server files download
Permissions are correct

Test Persistence

# First run
docker run --rm --name test-server \
  -v test_hytale-data:/home/hytale/server \
  hytale-server:test

# Stop and restart
docker stop test-server
docker run --rm \
  -v test_hytale-data:/home/hytale/server \
  hytale-server:test

Verify world data persists.

Automated Testing

Create test script (test.sh):

#!/bin/bash
set -e

echo "Building image..."
docker build -t hytale-server:test .

echo "Testing authentication..."
timeout 60s docker run --rm hytale-server:test || true

echo "Testing with volumes..."
docker run --rm \
  -v test_data:/home/hytale/server \
  hytale-server:test \
  ls -la /home/hytale/server

echo "Cleanup..."
docker volume rm test_data

echo "Tests passed!"

Run tests:

chmod +x test.sh
./test.sh

Documentation

Adding New Pages

Create MDX File

cd docs/content/docs
touch my-new-page.mdx

Add Frontmatter

---
title: My New Page
description: Description of the page
---

# My New Page

Content goes here...

Edit docs/source.config.ts:

export default {
  docs: [
    {
      title: 'Getting Started',
      pages: [
        { title: 'Introduction', href: '/docs' },
        { title: 'My New Page', href: '/docs/my-new-page' },
      ],
    },
  ],
};

Preview Changes

pnpm dev

Documentation Style Guide

Use clear, concise language
Include code examples
Add callouts for important information
Use steps for sequential instructions
Link to related pages

Release Process

Version Bumping

Update version in relevant files
Update CHANGELOG.md

Tag release:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Docker Hub Publishing

Images are automatically built and pushed via GitHub Actions:

# .github/workflows/docker-publish.yml
on:
  push:
    tags:
      - 'v*'

Manual push:

docker build -t romariin/hytale-docker:1.0.0 .
docker tag romariin/hytale-docker:1.0.0 romariin/hytale-docker:latest
docker push romariin/hytale-docker:1.0.0
docker push romariin/hytale-docker:latest

Code Style

Shell Scripts

Use #!/bin/bash shebang
Enable strict mode: set -euo pipefail
Quote variables: "$VAR"
Use [[ for tests, not [
Add comments for complex logic

Example:

#!/bin/bash
set -euo pipefail

# Check if server is running
if [[ -f "/home/hytale/server/server.pid" ]]; then
  echo "Server is running"
  exit 0
fi

Dockerfile

Use multi-stage builds
Minimize layers
Run as non-root user
Pin base image versions
Clean up in same layer

Example:

FROM eclipse-temurin:25-jre-jammy AS base
RUN apt-get update && \
    apt-get install -y curl && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

Debugging Tips

Enable Debug Logging

docker run --rm \
  -e DEBUG=true \
  -e LOG_LEVEL=debug \
  hytale-server:test

Inspect Running Container

docker exec -it hytale-server bash

Check Build Layers

docker history hytale-server:test

Validate Dockerfile

docker run --rm -i hadolint/hadolint < Dockerfile

Resources

Getting Help

GitHub Discussions: Ask questions and share ideas
GitHub Issues: Report bugs or request features
Discord: Join the Hytale community

Development

On this page