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

# Quickstart

> Get a PopLock server running on a fresh Linux host in under 15 minutes.

This guide walks you through installing every component on a clean Linux system: the required packages, the `serv` CLI, the startup scripts, and the Minecraft server jar itself.

<Note>
  PopLock requires **Java** to run the Minecraft server. Install it before starting:

  ```bash theme={null}
  sudo apt install openjdk-21-jre-headless
  ```

  PaperMC 1.21.4 requires Java 21. Check `java -version` to confirm.
</Note>

## Prerequisites

Install the system packages that PopLock's scripts depend on:

```bash theme={null}
sudo apt install tmux jq curl unzip
```

| Package | Purpose                                                      |
| ------- | ------------------------------------------------------------ |
| `tmux`  | Runs the Minecraft server in a persistent background session |
| `jq`    | Parses JSON for version checks and the API                   |
| `curl`  | Downloads server jars and checks for updates                 |
| `unzip` | Reads version info embedded inside the server jar            |

You also need **Node.js** if you plan to run the REST API. Install it from the [official Node.js site](https://nodejs.org) or via your distribution's package manager.

***

## Installation

<Steps>
  <Step title="Create the server directory">
    Create the directory that will hold all server files and give your user ownership of it:

    ```bash theme={null}
    sudo mkdir -p /usr/local/games/minecraft_server/java
    sudo chown -R $USER:$USER /usr/local/games/minecraft_server/java
    ```

    The full directory structure after setup will look like this:

    ```
    /usr/local/games/minecraft_server/java/
    ├── server.jar
    ├── start.sh
    ├── log4j2.xml
    ├── server.properties
    ├── whitelist.json
    ├── eula.txt
    ├── world/
    │   └── datapacks/
    └── backups/
        ├── jars/
        ├── snapshot_YYYYMMDD_HHMMSS.tar.gz
        └── minecraft_backup_YYYYMMDD_HHMMSS.tar.gz
    ```
  </Step>

  <Step title="Install serv and snapshot.sh">
    Copy both management scripts to `/usr/local/bin/` and mark them executable:

    ```bash theme={null}
    sudo cp serv /usr/local/bin/serv
    sudo chmod +x /usr/local/bin/serv

    sudo cp snapshot.sh /usr/local/bin/snapshot.sh
    sudo chmod +x /usr/local/bin/snapshot.sh
    ```

    `serv` is the primary command you'll use to control the server. `snapshot.sh` is the automated daily backup script, typically run by cron.
  </Step>

  <Step title="Install start.sh and log4j2.xml">
    Copy the startup loop and the Log4j configuration into the server directory:

    ```bash theme={null}
    cp start.sh /usr/local/games/minecraft_server/java/start.sh
    chmod +x /usr/local/games/minecraft_server/java/start.sh

    cp log4j2.xml /usr/local/games/minecraft_server/java/log4j2.xml
    ```

    `start.sh` contains the server launch loop with automatic restart logic. `log4j2.xml` suppresses noisy console output from server commands.
  </Step>

  <Step title="Download server.jar">
    Get the latest PaperMC build for your target Minecraft version. Replace `BUILDNUM` with the current build number, which you can find on [papermc.io/downloads](https://papermc.io/downloads):

    ```bash theme={null}
    curl -o /usr/local/games/minecraft_server/java/server.jar \
      "https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/BUILDNUM/downloads/paper-1.21.4-BUILDNUM.jar"
    ```

    The file must be named exactly `server.jar`.

    <Info>
      After initial setup, you can run `serv update` at any time to automatically pull and apply the latest PaperMC build for your current Minecraft version.
    </Info>
  </Step>

  <Step title="Accept the EULA">
    Mojang requires you to accept the Minecraft End User License Agreement before the server will start:

    ```bash theme={null}
    echo "eula=true" > /usr/local/games/minecraft_server/java/eula.txt
    ```
  </Step>

  <Step title="Start the server">
    Launch the server in a background tmux session:

    ```bash theme={null}
    serv start
    ```

    After it boots (usually 15–30 seconds), check that it came up cleanly:

    ```bash theme={null}
    serv status
    ```

    You should see the server version, uptime, memory usage, and current player count.

    <Tip>
      Run `serv console` to attach to the live server console and watch it in real time. Press **Ctrl+B then D** to detach without stopping the server.
    </Tip>
  </Step>
</Steps>

***

## Next steps

Your server is running. Here are a few things to set up next:

<CardGroup cols={2}>
  <Card title="REST API" icon="webhook" href="/api/installation">
    Install the lightweight Node.js HTTP API so you can manage the server remotely — including from Discord via n8n.
  </Card>

  <Card title="Resource pack" icon="palette" href="/resource-pack/installation">
    Install the PopLock custom textures and redesigned UI for all Java Edition players.
  </Card>

  <Card title="Automated snapshots" icon="clock" href="/scripts/snapshot-cron">
    Set up the nightly cron job that takes automated daily snapshots with in-game countdown warnings.
  </Card>

  <Card title="serv commands" icon="terminal" href="/scripts/serv-commands">
    Full reference for every serv subcommand — backup, restore, update, and more.
  </Card>
</CardGroup>