Set up Packs Server

Most servers don’t need this. If you aren’t sure, read Embedded or Packs Server? first.

What you need

• A Linux machine with one of these systems:
  • Debian 13 (trixie) or newer, or Ubuntu 24.04 or newer
  • Fedora 44 or newer, or RHEL 10 and its rebuilds, such as Rocky Linux and AlmaLinux
  • openSUSE Leap 16 or Tumbleweed
  • Arch Linux
• Root access, through sudo or a root shell.
• About 2 GB of free memory for Packs Server. You can change that later.

The usual setup is Packs Server on the same machine as your Minecraft server, and that’s what this guide sets up.

1. Install Packs Server

Pick your system, then the tab that matches your Oasis: Release for a release of Oasis, Dev for a dev build. Then run the whole block as root:

SystemDebian and Ubuntu

• Debian and Ubuntu
• Fedora and RHEL
• openSUSE
• Arch Linux

Release

mkdir -p /etc/apt/keyrings
curl -fsSL https://oasis-protection.com/packs.asc -o /etc/apt/keyrings/packs.asc
echo "deb [signed-by=/etc/apt/keyrings/packs.asc] https://telesphorepo.com/debian/packs-server-deb/ stable main" > /etc/apt/sources.list.d/packs.list
apt update
apt install packs

Dev

mkdir -p /etc/apt/keyrings
curl -fsSL https://oasis-protection.com/packs.asc -o /etc/apt/keyrings/packs.asc
echo "deb [signed-by=/etc/apt/keyrings/packs.asc] https://telesphorepo.com/debian/packs-server-deb-dev/ stable main" > /etc/apt/sources.list.d/packs.list
apt update
apt install packs

If curl is missing, install it first with apt install curl.

This installs Java 25 if you don’t have it already, then starts Packs Server. It starts again by itself whenever the machine reboots. Run Packs Server shows how to update it.

To switch between dev builds and releases later, run the other tab’s block. A dev build you already have stays until the next release comes out, and then the update installs it as usual.

2. Make a store

A store holds the history of one Minecraft server. Make one, plus a key that your server uses to log in:

packs store create survival
packs key add survival paper

The second command prints two keys: the private key and the server key. Copy both now, because Packs Server shows the private key only once. If you lose it, run packs key add again with a new name.

The packs command lists everything else it can do.

3. Connect Oasis

Open plugins/Oasis/config.yml on your Minecraft server and fill in the storage section:

storage:
  engine: server
  server:
    address: 127.0.0.1:7650
    store: survival
    key: "paste the private key here"
    server-key: "paste the server key here"

Restart your Minecraft server. Then run /oasis status. It should say Packs Server.

Pterodactyl and Pelican

With a panel, your Minecraft server runs inside a container. Inside that container, 127.0.0.1 means the container itself, not the machine that runs Packs Server, so Oasis needs a different address. The panel gives every container a private network that reaches the machine, and Packs Server can listen there.

First, find that network’s address. Open Wings’ config file, /etc/pterodactyl/config.yml for Pterodactyl or /etc/pelican/config.yml for Pelican, and look under docker, then network, then interface. It’s usually 172.18.0.1.

Next, tell Packs Server to listen on it. Open /etc/packs/packs-server.properties, change the listen line, and restart Packs Server:

listen = 172.18.0.1:7650

systemctl restart packs-server

Finally, use the same address in Oasis’s config:

    address: 172.18.0.1:7650

If you run a firewall like ufw, let the containers through with ufw allow from 172.18.0.0/16 to any port 7650.

Packs Server on another machine

Keep Packs Server on the same machine as your Minecraft server, or on the same local network, such as two VMs on one host. A longer distance makes lookups and rollbacks slower.

Nothing stops you from running it further away. Two servers in the same data center may be close enough that you never notice. If you try it, test lookups and rollbacks on your own setup and decide whether the delay is acceptable to you. Set listen to an address your Minecraft server can reach, put that address in Oasis’s config, and open port 7650 in the firewall to your Minecraft server’s address only.

The connection is encrypted over TCP, wherever the two run. The keys you made in step 2 prove each side to the other, and each connection gets fresh keys of its own, so nobody between the two machines can read your history or change what Oasis sends.

4. Bring your history along

If you used Packs Embedded before, your old history is still in plugins/Oasis/store. Oasis reminds you about it at startup. To bring it over, run:

/oasis move
/oasis move confirm

Lookups and rollbacks are paused until the move finishes. /oasis move status shows how far it has got. If you cancel the move or it fails, the old copy stays untouched, and you’re back where you started.

When the move ends, Oasis renames the old store and does not delete it. With Packs Embedded, the old copy waits in plugins/Oasis/store-moved-<time>. With Packs Server, Packs Server keeps its old copy beside its store, as <name>.moved-<time>. Oasis deletes the old copy 7 days later, but only when the time in its name and the time in its retired file agree. If they do not agree, Oasis keeps the copy and writes one line in the console. Then you delete the copy by hand.

The rename means a move back works, and your history never splits in two. To move back, change storage.engine in Oasis’s config, restart, and run /oasis move again.

If Packs Server goes down

Your server keeps logging. Oasis holds new edits in plugins/Oasis/outbox and sends them over as soon as Packs Server is back. Nothing is lost.

What’s next

Run Packs Server covers the day-to-day: checking on it, reading its log, giving it more memory, updating and uninstalling.