Installation

Installation Guide

This guide covers installing Pilaf and its dependencies for Minecraft plugin testing.

Prerequisites

Java 21

Pilaf requires Java 21 or later. Check your Java version:

java -version

If you don’t have Java 21, install it:

macOS: brew install openjdk@21
Ubuntu/Debian: sudo apt install openjdk-21-jdk
Windows: Download from Eclipse Temurin

Docker and Docker Compose

For the Docker backend, install Docker:

macOS: Docker Desktop
Windows: Docker Desktop
Linux: Docker Engine

Verify installation:

docker --version
docker-compose --version

Node.js (Optional)

For the Mineflayer backend, install Node.js 16+:

macOS: brew install node
Windows/macOS: Download from nodejs.org
Linux: Use nodesource repository

Installing Pilaf

Option 1: Clone from GitHub

# Clone the repository
git clone https://github.com/cavarest/pilaf.git
cd pilaf

# Build the project
./gradlew build

# Install to local system (optional)
./gradlew installDist

Option 2: Download Release

Download the latest release from GitHub Releases:

# Download and extract
wget https://github.com/cavarest/pilaf/releases/download/v0.1.0/pilaf-0.1.0.tar.gz
tar -xzf pilaf-0.1.0.tar.gz
cd pilaf-0.1.0

# Run Pilaf
./bin/pilaf --help

Option 3: Using Docker Image

Pull the Pilaf Docker image:

docker pull cavarest/pilaf:latest
docker run --rm cavarest/pilaf --help

Directory Structure

After installation, you’ll have this structure:

pilaf/
├── bin/
│   └── pilaf              # Main executable
├── lib/
│   ├── pilaf-0.1.0.jar    # Main JAR file
│   └── dependencies/      # Dependency JARs
├── config/
│   └── pilaf.yaml         # Default configuration
├── stories/               # Your test stories
│   └── *.yaml
└── docs/                  # Documentation

Configuration

Default Configuration File

Create a pilaf.yaml configuration file:

# Backend configuration
backend:
  type: docker  # docker, mineflayer, or headlessmc

# Server settings
server:
  host: "localhost"
  rcon_port: 25575
  rcon_password: "dragon123"
  minecraft_port: 25565

# Client settings (for Mineflayer)
client:
  host: "localhost"
  port: 3000

# Docker settings
docker:
  network_name: "pilaf-network"
  server_image: "itzg/minecraft-server:java21"

Environment Variables

Pilaf also supports environment variables:

export PILAF_RCON_PASSWORD="your-password"
export PILAF_SERVER_HOST="localhost"
export PILAF_CLIENT_PORT="3000"

Dependencies

Pilaf automatically manages its dependencies via Gradle:

// Key external libraries
dependencies {
    // RCON client with multi-packet support
    implementation 'com.github.cavarest:rcon:0.2.0'

    // YAML parsing
    implementation 'org.yaml:snakeyaml:2.0'

    // Template engine for HTML reports
    implementation 'io.pebbletemplates:pebble:3.2.2'

    // JSON processing
    implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.0'
}

The Cavarest RCON library is fetched from JitPack, which builds dependencies directly from GitHub. No manual installation required.

Testing Your Installation

Build and Test

# Run unit tests
./gradlew test

# Build the project
./gradlew build

# Run a simple test story
./gradlew run --args="--backend docker test-story-1-basic-items.yaml"

Verify Backend Connection

Test that your backend is working:

# Test Docker backend
./gradlew run --args="--backend docker --health-check"

# Test Mineflayer backend
curl http://localhost:3000/health

Next Steps

Quick Start Guide - Get started with your first test
Architecture Overview - Understand the system design
Writing Stories - Learn the YAML DSL

Troubleshooting

Java Version Error

If you see "Unsupported major.minor version 52.0", you need Java 21:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Docker Permission Denied

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Port Already in Use

If ports 25575 or 3000 are already in use, modify your configuration:

server:
  rcon_port: 25576  # Change to different port
client:
  port: 3001        # Change to different port