> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Minecraft

> Run a Minecraft Java server managed by the Crafty Controller web panel. Install, find your admin password, create a server, and connect.

The **Minecraft** app runs a Java Edition server managed by [Crafty Controller](https://craftycontrol.com) — a web admin panel that lets you create, configure, start, and back up Minecraft servers from your browser. No SSH or config-file editing required for day-to-day use.

This page covers running it on Suji end-to-end. Crafty Controller is maintained upstream; Suji provides the [marketplace packaging](https://github.com/suji-hq/suji-templates/tree/main/minecraft-server).

***

## Before you install

There's nothing to prepare — no API keys or tokens. Crafty generates its own admin credentials on first boot.

A couple of things to know up front:

* **The admin panel and the game run on two different addresses.** The Crafty panel is a private web UI behind your `*.suji.fr` tunnel; the Minecraft server itself is reachable by players on the VM's public IP at port `25565`.
* **You accept Mojang's EULA inside the panel** when you create a server — there's no separate setup step.

***

## Install

Dashboard → **Apps** → **Minecraft** → **Install**:

| Field     | Required | Notes                                                                              |
| --------- | -------- | ---------------------------------------------------------------------------------- |
| VM        | yes      | Pick a VM with free capacity, or create one.                                       |
| Subdomain | no       | Suggestion is `minecraft`. This is the Crafty **panel** URL, not the game address. |

There are no secrets to fill in — Crafty bootstraps its own admin account.

Pick a VM size with headroom: **Small** runs a light server, but **Medium or larger** is recommended. Minecraft is memory-hungry — it needs \~2 GB to run, and \~6 GB makes for a comfortable server. See [Recommended size](#recommended-size).

Click **Deploy**. The install reaches `running` in \~1 minute. You'll see a panel URL like `https://minecraft-<random>.suji.fr` — that's the Crafty admin panel (served over HTTPS on port 8443 behind the tunnel).

***

## First login — find your admin password

Crafty creates an `admin` user on first boot with a **randomly generated password**. There is no env var to preset it, so you retrieve it after install. Two ways:

### Option A — Logs tab (easiest)

1. Dashboard → instance → **Logs** tab → pick **Minecraft**.
2. On first boot Crafty prints the generated credentials. Look for a line with the default username and password.

### Option B — Files tab

Crafty also writes the credentials to a file on its config volume:

1. Dashboard → instance → **Files** tab.
2. Switch the root to the Minecraft install's volume.
3. Open `default-creds.txt` (under the Crafty config directory, container path `/crafty/app/config/default-creds.txt`).
4. It's a small JSON file — read the `username` (`admin`) and `password` values.

Then open the panel URL (`https://minecraft-<random>.suji.fr`), log in as **`admin`** with that password, and — recommended — change the password from Crafty's user settings.

<Note>
  Your browser may warn about the panel's TLS certificate. That's expected: Crafty serves a self-signed cert on `8443` and Suji's tunnel passes it through. The connection is still encrypted end-to-end over the tunnel.
</Note>

***

## Create and launch a server

Inside the Crafty panel:

1. Click **Create New Server**.
2. Choose the Minecraft type and version (e.g. Java vanilla, the version you want).
3. Set the server name and any options (memory, world settings).
4. **Accept the Mojang EULA** when prompted — required before a server will start.
5. Click **Create**. Crafty downloads the server jar.
6. From the server's page, click **Start** (the play button).

Wait for the console to show the server has finished loading (`Done!`).

***

## Connect from your Minecraft client

The game server listens on port **`25565`** on the VM's public IP — this is separate from the panel URL.

1. On the install detail page, find the **Connect (Minecraft)** section — it shows the public game address with a copy button.
2. In your Minecraft Java client → **Multiplayer** → **Add Server**.
3. Paste the address (the VM's public IP, port `25565` is the default so you can usually omit it).
4. Join.

Give players that same address to connect.

<Note>
  Only **one** Minecraft server — the one bound to port `25565` — is publicly reachable. You can create additional servers in Crafty for testing or admin use, but they won't be exposed to players unless you remap ports.
</Note>

***

## Day-to-day management

| Want to…                                   | Where                                                                |
| ------------------------------------------ | -------------------------------------------------------------------- |
| Create / start / stop / configure servers  | Crafty panel (`https://minecraft-<random>.suji.fr`)                  |
| Run console commands (op, whitelist, etc.) | Crafty panel → server → Console                                      |
| Take a world backup                        | Crafty panel → server → Backups                                      |
| View container logs                        | Dashboard → Logs (pick Minecraft)                                    |
| Open a shell inside the container          | Dashboard → Terminal (pick Minecraft)                                |
| Browse worlds / config on disk             | Dashboard → Files (pick the Minecraft volume)                        |
| Restart the whole app                      | Install detail page → Restart                                        |
| Upgrade to a newer version                 | Install detail page → Upgrade (when available — upgrades are manual) |
| Remove the install + its data              | Install detail page → Uninstall                                      |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="I can't find the admin password">
    Crafty only prints it once, on the very first boot. Check the **Logs** tab (it may have scrolled past — search the full log) or open `default-creds.txt` via the **Files** tab (container path `/crafty/app/config/default-creds.txt`). If you've already changed the password and forgotten it, reset it from Crafty's user management (with another admin account), or from the Crafty container via the **Terminal**.
  </Accordion>

  <Accordion title="Browser warns the panel certificate is invalid">
    Expected. Crafty serves a self-signed cert on port `8443`; the tunnel passes it through unmodified. Proceed past the warning — traffic is still encrypted over Suji's Cloudflare Tunnel.
  </Accordion>

  <Accordion title="Players can't connect to the server">
    Check, in order:

    * The server is **started** in Crafty (green/running), not just created.
    * You **accepted the EULA** — a server won't start without it.
    * Players are using the **public game address** (VM IP, port `25565`) from the install's **Connect (Minecraft)** section — *not* the `*.suji.fr` panel URL.
    * The server finished loading — the Crafty console shows `Done!`.
  </Accordion>

  <Accordion title="Server is slow or crashing under load">
    Minecraft is memory-bound. A busy server with many chunks loaded can exhaust available RAM and get OOM-killed. Move to a larger VM, or reduce view-distance / simulation-distance and the allocated server memory in Crafty.
  </Accordion>
</AccordionGroup>

***

## Where things live

| What                                | Inside container     | Named volume     |
| ----------------------------------- | -------------------- | ---------------- |
| Server worlds, jars, configs        | `/crafty/servers`    | `crafty-servers` |
| Backups                             | `/crafty/backups`    | `crafty-backups` |
| Crafty config + `default-creds.txt` | `/crafty/app/config` | `crafty-config`  |
| Logs                                | `/crafty/logs`       | `crafty-logs`    |

Uninstalling deletes these volumes by default. Choose **keep data** during uninstall to preserve your worlds.

***

## Recommended size

* The server needs **\~2 GB minimum**, but **\~6 GB is recommended** for a server with a few players and a normal view distance. **Small** (the smallest Suji VM) runs a light server; size up to **Medium or larger** for headroom.
* Minecraft holds the active world in memory and runs the simulation tick locally — it's genuinely CPU- and RAM-sensitive, unlike lighter apps. Player count, view distance, and mods all push memory, so size up for bigger worlds.
* If you run other apps on the same VM, remember the VM's total CPU/memory is shared — size up accordingly.

***

## Reporting issues

| Class                                                         | Where                                                                             |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Crafty Controller bug (panel behavior, server management)     | [Crafty Controller](https://craftycontrol.com)                                    |
| Marketplace packaging bug (compose / manifest / install form) | [suji-hq/suji-templates issues](https://github.com/suji-hq/suji-templates/issues) |
| Suji platform bug (dashboard, billing, network)               | Support ticket from the dashboard                                                 |