Skip to main content

​
Overview

Oyasai Server Platform uses a declarative Nix-based configuration system for managing Minecraft server instances. Server configurations are defined in .nix files that specify version, plugins, and runtime parameters.

​
Server Definition

Server instances are created using the oyasaiPurpur function, which configures a Purpur-based Minecraft server:
packages/oyasai-minecraft-main.nix
{
  oyasaiPurpur,
  oyasai-plugin-registry,
  lib,
  oyasaiDockerTools,
  stdenv,
}:

let
  final = oyasaiPurpur rec {
    name = "oyasai-minecraft-main";
    version = "1.21.8";

    plugins = with (oyasai-plugin-registry.forVersion version); [
      essentialsx
      fastasyncworldedit
      luckperms
      plugmanx
      protocollib
      vault
      nuvotifier
      vertex
    ];

    passthru = lib.optionalAttrs stdenv.hostPlatform.isLinux {
      docker = oyasaiDockerTools.buildLayeredImage {
        inherit name;
        config.Cmd = [ "${lib.getExe final}" ];
      };
    };
  };
in
final

​
Key Parameters

​
name
string
required
Unique identifier for the server instance
​
version
string
required
Minecraft server version (e.g., “1.21.8”)
​
plugins
array
required
List of plugin identifiers from the plugin registry
​
directory
string
default:"."
Working directory for server data
​
port
number
default:"25565"
Server port for Minecraft connections
​
cleanPlugins
boolean
default:"true"
Whether to clean plugins directory on startup

​
Docker Container Configuration

The production server runs in Docker containers with environment-specific configurations:
packages/cdktf/src/stacks/docker-stack.ts
const minecraftMainContainer = new Container(
  this,
  this.envAwareId("minecraft-main-container"),
  {
    image: images.minecraftMain.imageId,
    name: "minecraft-main",
    restart: "unless-stopped",
    tty: true,
    stdinOpen: true,
    destroyGraceSeconds: 2 * 60,
    init: true,
    ports: ports({
      tcp: [8100, 8192, 25565, 25575],
      udp: [19132],
    }),
    env: envs({
      EULA: true,
      TYPE: "PURPUR",
      VERSION: "1.21.8",
      USE_MEOWICE_FLAGS: this.environment !== "local",
      ENABLE_ROLLING_LOGS: true,
      LOG_TIMESTAMP: true,
      MOTD: "§l§r                 §b§lOyasai§f§lServer§7 [v1.21.8]§r\n§l§f            建築勢は集合だ！建築！建築！建築！！！",
      MEMORY: this.envAwareConfig({
        production: "28G",
        development: "12G",
        local: "5G",
      }),
      RCON_PASSWORD: this.secrets.RCON_PASSWORD,
    }),
    healthcheck: {
      test: ["mc-health"],
      startPeriod: "1m",
      interval: "5s",
      retries: 20,
    },
  },
);

​
Network Ports

​
TCP Ports
array
  • 25565: Main Minecraft server
  • 25575: RCON remote console
  • 8100: BluMap web interface
  • 8192: Additional service port
​
UDP Ports
array
  • 19132: Bedrock Edition (Geyser)

​
Environment Variables

​
EULA
boolean
required
Accept Minecraft EULA (must be true)
​
TYPE
string
default:"PURPUR"
Server type (PURPUR, PAPER, SPIGOT)
​
VERSION
string
required
Minecraft version to run
​
MEMORY
string
required
JVM memory allocation (e.g., “28G”, “12G”, “5G”)
​
USE_MEOWICE_FLAGS
boolean
default:"false"
Enable optimized JVM flags for production
​
ENABLE_ROLLING_LOGS
boolean
default:"false"
Enable log rotation
​
LOG_TIMESTAMP
boolean
default:"false"
Add timestamps to log entries
​
MOTD
string
Server message of the day (supports color codes)
​
RCON_PASSWORD
string
required
Password for RCON access
​
ICON
string
URL to server icon image

​
Health Checks

The server implements health checking to ensure availability: 
healthcheck:
  test: ["mc-health"]
  startPeriod: "1m"
  interval: "5s"
  retries: 20
  • Start Period: 1 minute grace period for server startup
  • Interval: Check every 5 seconds
  • Retries: Up to 20 failed checks before marking unhealthy

​
Server Startup

The entrypoint script handles plugin synchronization:
packages/minecraft-main/entrypoint.sh
#!/bin/bash

set -euo pipefail

rm /data/plugins/*.jar
rm -rf /data/plugins/.paper-remapped

rsync -a /overlays/ /data/

chown root -R /data/

exec /image/scripts/start
1

Clean plugins directory

Remove existing plugin JARs and remapped files
2

Sync overlays

Copy fresh plugins from overlays to data directory
3

Fix permissions

Set ownership to root user
4

Start server

Execute main server startup script

​
Environment-Specific Configuration

The platform supports three environments with different resource allocations:
  • Memory: 28GB
  • Features: Optimized JVM flags, rolling logs, automated backups
  • Location: Remote production server

​
Next Steps

Plugin Management

Learn how to add and manage server plugins

Monitoring

Set up server monitoring and health checks

Build docs developers (and LLMs) love

Get started for freeTalk to us