Already running a server with players? Moving an existing server onto Atlas keeps the world and everybody’s things — it uses the same proxy and hub set up here.
What you are about to build. Two regions side by side, one border down the middle.
Before you start
Roughly 6 GB of RAM across the four servers, your licence key, and the Atlas jars:
atlas-paper.jar for the shards, atlas-velocity.jar for the proxy’s plugin, and atlas-proxy.jar, the proxy itself.
On a panel specifically
Three things work differently to a VPS, and all three cause the same confused hour if nobody says them:Ports come from your allocation, not from you
Ports come from your allocation, not from you
Each server gets an allocation — an IP and port the panel assigns. You do not choose
server-port; the panel sets it. What you do choose is shard.address, and it must be the allocation the proxy can dial, which on most panels is the public one.The panel injects environment variables
The panel injects environment variables
Atlas reads settings from the environment and from
config.yml, and the file wins. That is deliberate, but it means an operator who edits a panel variable and sees nothing change has no way to find out why. Put your settings in plugins/atlas/config.yml and treat the panel variables as unused.You usually cannot close the shard ports
You usually cannot close the shard ports
Every server you rent gets its own public address, and no firewall you control. So the forwarding secret is doing all of the security work. Read Security before anyone else knows your IP.
Build it
1
Give both shards the same seed
Nothing is copied between servers. Each shard runs the same seed and generates only its own region; the ground either side of the border is shared through MongoDB, which is what keeps the border from showing a seam. How that works is in Same seed, no world copy.Every shard uses the same
server.properties
level-seed and the same level-name, and level-name must match shard.world below. Leave server-port to the panel.What players build in region 0 lives only on region 0’s server. That is the point.2
Start the proxy once to get a forwarding secret
Use Both switches are off in a fresh
atlas-proxy.jar as the proxy server’s jar — it is Velocity, so a Velocity egg runs it — then start it and stop it. It writes velocity.toml and a forwarding.secret. You need that secret before the shards can be configured, which is why the proxy comes first.velocity.toml
velocity.toml; without them every border is a loading screen. See The proxy.Only the hub is listed. The shards register themselves out of MongoDB from their shard.address, so listing them here is neither needed nor wanted. Clear [forced-hosts] as well: a forced host naming a server that does not exist fails Velocity’s own validation and the proxy will not start.3
Configure the proxy plugin
atlas-velocity.jar into the proxy’s plugins/, then:plugins/atlas/config.yml
geo is only a name for this network. Any short word, the same on every box.4
Configure the two shards
Each shard gets
atlas-paper.jar in plugins/, the file below with region and address changed, and the forwarding secret in paper-global.yml.address is that server’s own allocation — the one the proxy dials — and setting it is the whole of self-registration. border-chunks is what shares the ground along the border; it is off unless you turn it on.Then on both shards and the hub:config/paper-global.yml
5
Add your licence key
The same key goes into Without a valid key a shard will not start and the proxy turns everyone away — the console says which. If the licence server cannot be reached, a server that has verified before keeps running for up to two days while it retries. Licence has the details.
plugins/atlas/config.yml on both shards and the proxy:plugins/atlas/config.yml
6
Set up the hub
The hub is a plain Paper server with the same
paper-global.yml forwarding block and no Atlas plugin — it owns no region, so there is nothing for the plugin to do there. It needs no copy of the shards’ world; any world will do.Name it hub and the proxy finds it. If you call it something else, set proxy.hub to match.7
Start in order
MongoDB and Redis first, then the shards, then the hub, then the proxy.Nothing breaks if you get this wrong — a shard with no database retries, and a proxy with no shards sends everyone to the hub — but starting bottom-up means the first error you read is the real one rather than a consequence of it.Watch each shard’s console for the region it claims. A misspelled setting is named rather than ignored:
8
Pre-generate each region on its own shard
Install Chunky on each shard and run Each shard publishes its side of the border as it goes. You can skip this and let players generate as they explore, but then the first person to walk a stretch of border is the one who pays for generating it.
/shard pregen there. It prints the commands that generate exactly that shard’s square:9
Check it worked
Join through the proxy, not through a shard, and run:Two live owners and no dash means the shards registered themselves and the proxy can see both. A dash is a region nobody is serving.
/shard on its own then tells you which region you are in and how far you are from the nearest edge.10
Walk across the border
Spawn at 0,0 sits exactly on the border, in region 1 — the square starting at a line owns it. So walk west, into negative x, and you cross within a few blocks.Turn on
/shard walls first and the boundary is drawn as a particle curtain. /shard bar puts your shard, your ping and the distance to the next border in a boss bar.What you should see: no loading screen, your inventory intact, and the ground on the far side already drawn before you got there. A loading screen means the proxy is not keeping the client’s world — its console names the setting. What you should not see is a disconnect — if you get one, the forwarding secret is wrong on the shard you were walking into.Going to four regions
Rent one more shard, change one number on every box, and restart the network.region: 2 and region: 3, give each its address, the same seed and border-chunks: true, then run /shard pregen on each — including the two you already had, because their squares just changed. Region numbering is left to right then top to bottom from the north-west corner, so the layout becomes:
Spawn at 0,0 moves from region 1 to region 3, because
regions-z changing moves where the origin sits.
Sizing the world for a real SMP
A 2048 region is a tutorial. A real SMP is tens of thousands of blocks across, and the grid handles that fine —region-size is the only number you change.
region-size must be at least 256 and a multiple of 16. There is no upper limit in Atlas.
With border chunks each shard generates and stores only its own square plus a thin corridor of its neighbours’, so more regions divides the world up: a 4x4 is the same map in sixteen pieces, each pre-generated in parallel on its own server. More regions also buys simulation headroom — more players and more redstone over more CPUs.
If you leave
border-chunks off and copy one world folder to every shard instead, every shard holds the whole map: about 224 GB each at a 50,000 radius, and more shards multiplies it rather than dividing it. That path still works and is the conservative one while border chunks are new.When it does not work
More in Troubleshooting.
Next
Security
Read this before anyone else knows your IP. On a panel the forwarding secret is the only thing protecting the shards.
Panel and VPS hosting
Self-registration in full, and spreading the same network across two or three providers.
Grid and ownership
Why the border falls where it does, and what stops two servers both owning you.
Configuration
Every setting, and which ones must match across the network.