vlepic/terrain_diff_server repository overview

⁠Terra Diffusion Minecraft Server

Docker setup for a Minecraft 1.21.1 Fabric server with the CUDA build of Alesrr/terra-diffusion-compat, intended for a Linux host with an NVIDIA GPU.

⁠What Is Included

• Minecraft 1.21.1 on Fabric via itzg/minecraft-server
• Java 21 base image pinned to an Ubuntu 24.04 based tag
• CUDA 12.8 runtime libraries and cuDNN 9
• Terra Diffusion Compat CUDA jar downloaded from GitHub Releases at image build time
• Fabric API, Terralith, Lithostitched, Dungeons and Taverns, Towns and Towers, BlueMap, and optional Snow Real Magic via Modrinth at server startup
• Loot Integrations, its Dungeons and Taverns/Towns and Towers addons, and Cupboard via CurseForge at server startup
• Persistent /data, including the world and the first-run model download

⁠Local Build Smoke Test

This Windows workspace can build the Linux image if Docker Desktop is using a Linux engine:

docker compose build
docker compose run --rm --entrypoint nvidia-smi minecraft

On the Windows RTX 3080 machine that second command only works if Docker has NVIDIA GPU support enabled. The important target is the Unraid host.

⁠Run With Docker Compose

docker compose up -d
docker compose logs -f

The first launch needs internet access and can take a while because the mod downloads roughly 2.5 GB of model files into data/terrain-diffusion-models.

The CurseForge downloads normally use the API key bundled with the itzg/minecraft-server image. If CurseForge rate-limits or rejects it, create a key at the CurseForge developer console and pass it as CF_API_KEY in your .env.

⁠GitHub Autobuild

Push this repository to GitHub. The workflow in .github/workflows/docker-publish.yml builds and publishes:

ghcr.io/<owner>/<repo>:latest
ghcr.io/<owner>/<repo>:<branch>
ghcr.io/<owner>/<repo>:sha-<commit>

The default build uses the latest release from:

Alesrr/terra-diffusion-compat

To pin a specific upstream release, run the workflow manually and set terra_diffusion_tag, or set TERRA_DIFFUSION_TAG as a Docker build arg in your own build.

⁠Unraid Compose

Use compose.unraid.yml as the starting point and replace:

ghcr.io/OWNER/REPOSITORY:latest

with your published GHCR image.

Expected host paths:

/mnt/user/appdata/terra-diffusion-mc/data
/mnt/user/appdata/terra-diffusion-mc/config
/mnt/user/appdata/terra-diffusion-mc/mods

The container needs GPU access. With Compose this is expressed as an NVIDIA device reservation:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities:
            - gpu

If using Unraid's classic Docker UI instead of Compose, add this extra parameter:

--gpus all

Also make sure the NVIDIA driver plugin/runtime works on Unraid and that this succeeds:

docker run --rm --gpus all nvidia/cuda:12.8.1-base-ubuntu24.04 nvidia-smi

⁠World And Config

The server is configured to create a Terrain Diffusion world:

level-name=terrain-diffusion-world
level-type=terrain-diffusion-mc\:terrain_diffusion

The committed config defaults to GPU inference and conservative VRAM use:

inference.device=gpu
inference.offload_models=true
explorer.port=19801
terralith.enabled=true

Port 19801 is exposed for the /td-explore web UI. Port 8100 is exposed for the BlueMap web UI.