Skip to main content

​
Quickstart

This guide will get you from zero to running a local Purpur server with the Oyasai platform in under 10 minutes.

​
Prerequisites

Windows Users: You must use WSL (Windows Subsystem for Linux). Install WSL first, then complete all steps inside your WSL terminal.
Before you begin, ensure you have:
  • A Unix-like environment (Linux, macOS, or WSL on Windows)
  • At least 4GB of free disk space
  • Internet connection for downloading dependencies

​
Installation

1

Install Nix

Download and install Nix from nixos.org. The multi-user installation is recommended, but single-user works too.
curl -L https://nixos.org/nix/install | sh
After installation completes, restart your terminal or source the Nix profile:
. ~/.nix-profile/etc/profile.d/nix.sh
Verify the installation:
nix --version
2

Enable Experimental Features

Nix flakes and the nix command are experimental features that must be explicitly enabled.
mkdir -p ~/.config/nix
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
These features are stable and widely used, but remain “experimental” in Nix terminology.
3

Clone the Repository

Clone the platform repository to your local machine:
git clone https://github.com/oyasaiserver/platform.git
cd platform
4

Verify Flake Configuration

Test that Nix can read the flake configuration:
nix flake show
You should see output listing available packages and development shells. If you see errors, check that experimental features are enabled.
5

Enter Development Shell

The development shell contains all tools needed for development: Java, Gradle, Node.js, Terraform, and more.
nix develop
This command will:
  • Download all required dependencies
  • Set up the development environment
  • Drop you into a shell with all tools available
The first run will take several minutes as Nix downloads and builds dependencies. Subsequent runs are nearly instant.
Verify you have the required tools:
java --version
gradle --version

​
Running Your First Server

Now that your environment is set up, let’s run a Minecraft server.
1

Run the Minimal Server

The platform includes a pre-configured minimal server for testing:
nix run .#oyasai-minecraft-minimal
This command will:
  • Download Purpur server version 1.21.8
  • Install essential plugins (EssentialsX, FastAsyncWorldEdit, PlugManX)
  • Accept the EULA automatically
  • Create a local/ directory
  • Start the server on port 25565
The first run downloads the server JAR and may take a few minutes. The server will generate world files in the local/ directory.
2

Connect to Your Server

Once the server shows Done! in the console, open Minecraft:
  1. Launch Minecraft Java Edition version 1.21.8
  2. Go to Multiplayer → Add Server
  3. Server Address: localhost:25565
  4. Connect and play!
To stop the server, type stop in the console or press Ctrl+C.
3

Explore Server Files

All server files are in the local/ directory:
ls -la local/
You’ll find:
  • plugins/ - Installed plugin JARs
  • world/ - World data
  • server.properties - Server configuration
  • logs/ - Server logs
The local/ directory is gitignored and safe to delete. Running the server again will recreate it.

​
Building Plugins

Let’s build the custom Oyasai plugins from source.
1

Build All Plugins

From the repository root, inside the development shell:
gradle build --parallel
This builds all plugins in the plugins/ directory concurrently.
2

Build a Specific Plugin

To build just one plugin:
gradle :plugins:OyasaiUtilities:build
Replace OyasaiUtilities with any plugin name:
  • DynamicProfile
  • EntityPose
  • OyasaiAdminTools
  • OyasaiPets
  • PaintTools
  • And more…
Built JARs are located in plugins/<name>/build/libs/.
3

Update Dependencies

If you modify plugin dependencies in build.gradle.kts, regenerate the lock file:
gradle2nix
This updates gradle.lock with the new dependency graph for Nix.

​
Creating a Custom Server Configuration

Create your own server configuration for development or testing.
1

Create Configuration File

Create a new Nix file in packages/:
packages/oyasai-minecraft-dev.nix
{ oyasaiPurpur, oyasai-plugin-registry }:

oyasaiPurpur rec {
  name = "oyasai-minecraft-dev";
  version = "1.21.8";

  directory = "dev-server";
  port = 25566;  # Different port to run alongside other servers

  plugins = with (oyasai-plugin-registry.forVersion version); [
    essentialsx
    fastasyncworldedit
    plugmanx
    vault
  ];
}
Available plugins are defined in packages/oyasai-plugin-registry/data.json. The forVersion function filters plugins compatible with your Minecraft version.
2

Register Configuration

Add your configuration to the build system by editing nix/oyasai-scope.nix.Find the packages section (around line 126) and add your config:
packages = lib.filterAttrs (_: availableOnSystem) {
  inherit (oyasaiScope)
    # keep-sorted start
    oyasai-minecraft-dev
    oyasai-minecraft-main
    oyasai-minecraft-marzipan
    oyasai-minecraft-minimal
    # keep-sorted end
    ;
};
3

Stage and Run

Git must track the file for Nix to see it:
git add packages/oyasai-minecraft-dev.nix
git add nix/oyasai-scope.nix
Now run your custom server:
nix run .#oyasai-minecraft-dev
Your server will start in the dev-server/ directory on port 25566.

​
Code Formatting

The platform enforces consistent code formatting across all files.
1

Format All Code

Before committing changes, format your code:
nix fmt
This formats:
  • Nix files
  • Kotlin files
  • TypeScript/JavaScript files
  • Configuration files
2

Verify Formatting in CI

The CI pipeline will reject unformatted code. Always run nix fmt before pushing.
Pull requests with formatting issues will fail CI checks and cannot be merged.

​
Running Tests and Checks

Before submitting changes, verify everything builds correctly. 
nix flake check -L
This command:
  • Builds all packages
  • Runs all tests (if defined)
  • Verifies Nix expressions
  • Shows detailed logs with -L
This is the same check that runs in CI. If it passes locally, it should pass in CI.

​
Next Steps

Plugin Development

Learn how to create and modify Minecraft plugins

Server Configuration

Advanced server configuration with custom plugins and settings

Contributing Guide

Learn about PR conventions, code review, and development workflow

Nix Flakes

Understand how Nix flakes work in this project

​
Common Issues

Nix is not in your PATH. Restart your terminal or source the Nix profile:
. ~/.nix-profile/etc/profile.d/nix.sh
Flakes are not enabled. Run:
mkdir -p ~/.config/nix
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
Another server is running on port 25565. Either:
  • Stop the existing server
  • Change the port in your server configuration
port = 25566;  # Use a different port
You’re not in the development shell. Run:
nix develop
Ensure you’ve:
  1. Run nix fmt to format code
  2. Run nix flake check -L successfully
  3. Committed all changes including gradle.lock

​
Getting Help

If you encounter issues not covered here:
  • Check existing GitHub issues
  • Review the CONTRIBUTING.md file
  • Ask in the development Discord (if available)
  • Open a new GitHub issue with detailed information

Build docs developers (and LLMs) love

Get started for freeTalk to us