Skip to content

Mineflake

logo

Mineflake is a tool for creating and managing Minecraft servers declaratively. It is written in Rust and uses Nix for package management.

Support Ukraine license MIT matrix wakatime Cache derivations

Source code: https://github.com/nix-community/mineflake

Quick start

Installation

Mineflake can be used with Nix or without it. To use Mineflake without Nix, you need to install Rust and Cargo. To do so, run:

If you want to use Mineflake with Nix, you need to install Nix. To do so, run:

bash <(curl -L https://nixos.org/nix/install) # (1)
nix run github:nix-community/mineflake --help # (2)

  1. This command installs Nix. If you want to install it manually, you can find more information on Nix website.

  2. This doesn't install Mineflake to your system, it just runs it. So if you want to execute mineflake apply command, you need to run nix run github:nix-community/mineflake apply instead.

Faster builds (optional)

You can install Cachix to your system to significantly speed up builds:

nix-env -iA cachix -f https://cachix.org/api/v1/install

And activate cache for Mineflake:

cachix use nix-community
Note about usage with Nix

Mineflake uses flake feature of Nix (hence the name), so you need to enable flakes support. Wiki page about Flakes has more information about it.

Go to latest release page and download the executable. Its name should be mineflake-linux-X.Y.A where X.Y.A - version. So, the script would be:

curl -L https://github.com/nix-community/mineflake/releases/download/vX.Y.A/mineflake-linux-X.Y.A --output mineflake
chmod +x mineflake
sudo mv mineflake /usr/local/bin # second arg can be any path, that is in $PATH enviroment variable
mineflake --help
If last command fails

On most systems, this wouldn't happen, although you need to add /usr/local/bin to your PATH environment variable. Add this to your .bashrc or just run the command, and it will be rollbacked after your logout:

export PATH="$PATH:/usr/local/bin"

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # (1)
cargo install mineflake # (2)
mineflake --help

  1. This command installs Rust and Cargo. If you want to install it manually, you can find more information on Rust website.

  2. This command installs Mineflake CLI to your system. It's usually located in ~/.cargo/bin directory.

If last command fails

You need to add ~/.cargo/bin to your PATH environment variable. To temporary fix this issue execute:

export PATH="$PATH:~/.cargo/bin"
Which method I should use?

If you are familiar with Nix, you should use Nix. If you are not, you should use Cargo.

With Nix you get more control and simplier package management. Both methods have same package set and same features.

Windows support

Mineflake doesn't support Windows officially, but it can be used on Windows with some workarounds.

There 2 ways to use Mineflake on Windows:

  1. Use WSL2. It's the easiest way to use Mineflake on Windows, as it's the same as using it on Linux. WSL also has Nix support, so you can use Nix to install Mineflake.
  2. Install Rust and Cargo manually. You can find more information on Rust website.

Note about configuration diffrences between Nix and non-Nix versions

All examples in this documentation are written for non-Nix version of Mineflake, but they are also valid for Nix version, with some exceptions:

  • All packages are Nix derivations.
  • You can't use files that are not in your Nix store/flake directory. For example, if you want to use server.properties file, you need to add it to your flake directory and use ./server.properties path, instead of /path/to/server.properties.
  • You can use functions and variables. For example, you can use builtins.readFile function to read file contents, or mineflake.mkMfConfig to easily add config entry.

Example of config for non-Nix version:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
defaults:
  repo: &repo "https://raw.githubusercontent.com/nix-community/mineflake/8f442611468fc60cd07003447d6c7625e60a50e4/repo.json"

type: spigot

command: "java -Xms1G -Xmx1G -jar {} nogui"

package:
  type: local
  path: /path/to/paper

plugins:
  - type: repository
    repo: *repo
    name: luckperms

configs:
  - type: raw
    path: server.properties
    content: |
      enable-command-block=true
      enable-rcon=true
      rcon.password=123
      rcon.port=25575

Example of same config for Nix version:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{ jdk, mineflake, ... }:

mineflake.buildMineflakeBin {
    type = "spigot";
    command = "${jre_headless}/bin/java -Xms1G -Xmx1G -jar {} nogui";
    package = mineflake.paper; # (1)
    plugins = with mineflake; [
        luckperms # (2)
    ];
    configs = [
        (mineflake.mkMfConfig "raw" "server.properties" ''
            enable-command-block=true
            enable-rcon=true
            rcon.password=123
            rcon.port=25575
        '') # (3)
    ];
}

  1. Package is a derivation, so you need to use mineflake.packagename instead of { type: local, path: /path/to/packagename }.

  2. You can't use remote/repository packages. But for default repo all packages have derivations, so you can use them.

  3. You can use functions. mkMfConfig is a function that creates config entry. It's easier and more readable than writing it manually.

Run a simple paper server

To run a simple paper server, you need to create a file named mineflake.yml with the following content:

mineflake.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
defaults:
  repo: &repo "https://raw.githubusercontent.com/nix-community/mineflake/8f442611468fc60cd07003447d6c7625e60a50e4/repo.json"

type: spigot

command: "java -Xms1G -Xmx1G -jar {} nogui"

package:
  type: local
  path: /path/to/paper

plugins:
- type: repository
  repo: *repo
  name: luckperms

configs:
- type: raw
  path: server.properties
  content: |
    enable-command-block=true
    enable-rcon=true
    rcon.password=123
    rcon.port=25575
server.nix
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{ jdk, mineflake, ... }:

mineflake.buildMineflakeBin {
    type = "spigot";
    command = "c -Xms1G -Xmx1G -jar {} nogui";
    package = mineflake.paper;
    plugins = with mineflake; [
        luckperms
    ];
    configs = [
        (mineflake.mkMfConfig "raw" "server.properties" ''
            enable-command-block=true
            enable-rcon=true
            rcon.password=123
            rcon.port=25575
        '')
    ];
}

Mineflake can read json configurations too, but it's harder to write and read them.

mineflake.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "type": "spigot",
    "command": "java -Xms1G -Xmx1G -jar {} nogui",
    "package": {
        "type": "local",
        "path": "/path/to/paper"
    },
    "plugins": [
        {
            "type": "repository",
            "repo": "https://raw.githubusercontent.com/nix-community/mineflake/8f442611468fc60cd07003447d6c7625e60a50e4/repo.json",
            "name": "luckperms"
        }
    ],
    "configs": [
        {
            "type": "raw",
            "path": "server.properties",
            "content": "enable-command-block=true\nenable-rcon=true\nrcon.password=123\nrcon.port=25575"
        }
    ]
}

And then run mineflake apply command. It will download paper, luckperms and create a server.properties file with the specified content.

After that you can run mineflake run to start the server.

You can find more information about mineflake.yml file in Configuration section.