> ## 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.

# Installation

> Install and configure the PopLock server scripts on a self-hosted Linux machine.

## Prerequisites

Install the required system packages before proceeding:

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

## Directory structure

All server files live under a single root directory:

```text theme={null}
/usr/local/games/minecraft_server/java/
├── server.jar
├── start.sh
├── log4j2.xml
├── server.properties
├── whitelist.json
├── world/
│   └── datapacks/
│       └── poplock_datapack.zip
└── backups/
    ├── jars/
    ├── snapshot_YYYYMMDD_HHMMSS.tar.gz
    └── minecraft_backup_YYYYMMDD_HHMMSS.tar.gz
```

## Installation steps

<Steps>
  <Step title="Create the server directory">
    Create the directory tree and take 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
    ```
  </Step>

  <Step title="Install serv">
    Copy the `serv` CLI to `/usr/local/bin` and make it executable:

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

  <Step title="Install snapshot.sh">
    Copy the snapshot script to `/usr/local/bin` and make it executable:

    ```bash theme={null}
    sudo cp snapshot.sh /usr/local/bin/snapshot.sh
    sudo chmod +x /usr/local/bin/snapshot.sh
    ```
  </Step>

  <Step title="Install start.sh">
    Copy the startup loop script into the server directory and make it executable:

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

  <Step title="Install log4j2.xml">
    Copy the log4j configuration file into the server directory. This suppresses
    noisy console output:

    ```bash theme={null}
    cp log4j2.xml /usr/local/games/minecraft_server/java/log4j2.xml
    ```
  </Step>

  <Step title="Place server.jar">
    Drop your PaperMC or Vanilla `server.jar` into the server directory. The file
    must be named exactly `server.jar`.

    To download the latest PaperMC build directly:

    ```bash theme={null}
    # Replace 1.21.4 and BUILDNUM with current values from https://papermc.io/downloads
    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"
    ```

    Alternatively, use `serv update` after completing the rest of this guide to
    pull the latest build automatically.
  </Step>

  <Step title="Accept the EULA">
    Minecraft requires you to accept the 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="Install the alert datapack">
    The PopLock datapack provides the in-game alert sound used by the snapshot
    countdown. Download it directly into the datapacks directory:

    ```bash theme={null}
    sudo wget -O /usr/local/games/minecraft_server/java/world/datapacks/poplock_datapack.zip \
      https://github.com/Scyne/PopLockRP/raw/refs/heads/main/poplock_datapack.zip
    ```

    <Note>
      The `world/datapacks/` directory is created by the server on its first run.
      If you are installing the datapack before the first launch, create the
      directory manually first:

      ```bash theme={null}
      mkdir -p /usr/local/games/minecraft_server/java/world/datapacks
      ```
    </Note>

    Once the server is running, activate the datapack once from the console:

    ```text theme={null}
    datapack enable "file/poplock_datapack.zip"
    ```

    It will load automatically on every subsequent restart.
  </Step>
</Steps>

## Next steps

With installation complete, set up the automated daily snapshot cron job so
worlds are backed up every night — see [Snapshot & Cron](/scripts/snapshot-cron).