Server Setup

Server setup and installation

Wiki home · Player commands · Get help

Install Civilizations, connect its database, configure worlds, and validate a server before players join.

This wiki documents Civilizations 1.0.1. Numbers are bundled defaults; in-game menus and previews show your server’s current values.

On this page: Requirements and compatibility · 1. Prepare a Minecraft server · 2. Build or obtain the plugin JAR · 3. Create the database · 4. Install and generate configuration · 5. Configure storage, economy, and worlds · 6. Set borders and the war schedule · 7. Verify startup and admit players

Requirements and compatibility

You need a Spigot 26.2 server, Java 25, and a reachable MySQL 8.x database. A vanilla server cannot load Bukkit/Spigot plugins. Other server distributions must implement the required Spigot API; the plugin documentation does not establish compatibility with every fork. Folia support is not declared.

Java 25 is required for both building and running this plugin. There is no SQLite, flat-file, or database-free mode. Setting the economy to DISABLED disables currency features, not MySQL.

Use one active Minecraft server process per Civilizations database schema. server-id identifies audit records; it does not provide shared-network synchronization between multiple servers.

Integration	Needed for	Setup
Vault and a registered economy provider	Currency costs, /sell, paid plots, treasury transfers, automatic tax collection	Install both and set economy.mode: VAULT
PlaceholderAPI	%civ_*% placeholders for compatible displays	Install it and leave integrations.placeholderapi: true
WorldGuard 7+	Rejecting claims that overlap protected regions	Install its required dependencies and leave integrations.worldguard: true
CoreProtect	Integration status / operator visibility	Install it if desired; investigation and rollback use CoreProtect's own tools

These are optional soft dependencies, not libraries bundled into the Civilizations JAR. Vault alone does not create player balances. The economy provider must support the operations you intend to use, including offline withdrawals for plot taxes. WorldGuard and other plugins can impose additional restrictions beyond Civilizations.

1. Prepare a Minecraft server

If using a hosting panel, select a compatible Spigot server version, select Java 25 for its startup environment, and obtain a dedicated MySQL database from the host. Confirm that the database can be reached from the game server, not just from your own computer.

For a self-hosted server, follow the official Spigot BuildTools guide and Spigot installation guide. Use the matching server revision. Keep the running Minecraft server in its own directory, separate from this source checkout.

After obtaining the server JAR, an example launch command is:

java -Xms2G -Xmx4G -jar spigot-26.2.jar nogui

Replace the filename with the actual server JAR. The heap values are an example, not a measured capacity recommendation; leave memory for the operating system and MySQL, and tune for your player count, world generation, and other plugins.

Read the Minecraft EULA and accept it in the generated eula.txt only if you agree. Use the server's stop command for a clean shutdown. A hosting panel or service manager should keep the process running after you close your terminal.

Configure your game connection address/port and firewall for your hosting environment. Keep database access restricted to the Minecraft host or a private network. Do not expose MySQL just to let players join Minecraft.

2. Build or obtain the plugin JAR

If you have a release JAR for this source version, use it. Otherwise install a JDK 25 and Maven, open a terminal in the plugin source repository, and run:

java -version
mvn -version
mvn clean verify

Both version commands should report Java 25 for their respective processes. Maven downloads the compile-time Spigot API and other dependencies; you do not need BuildTools to build this plugin.

Install this artifact:

target/Civilizations-1.0.1.jar

Do not install an original-*.jar, a source JAR, or a test JAR. The release JAR includes its database/runtime libraries; the server provides the Spigot API.

3. Create the database

If your host already provisioned a database, use the exact database name, username, password, and endpoint it supplied. Otherwise run this example as a MySQL administrator:

CREATE DATABASE civilizations
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_0900_ai_ci;

CREATE USER 'civilizations'@'127.0.0.1'
  IDENTIFIED BY 'replace-with-a-long-random-password';

GRANT ALL PRIVILEGES ON civilizations.*
  TO 'civilizations'@'127.0.0.1';

The account host must match the Minecraft server's source host as MySQL sees it. On a remote database, 127.0.0.1 in this example is not the game server's address. On a container host, 127.0.0.1 inside the game container refers to that container; use the database endpoint available on its network.

Privileges are limited to this dedicated schema. Schema creation/alteration privileges are needed because the plugin applies migrations itself. Use a dedicated password and account, not your database administrator account.

4. Install and generate configuration

1. Stop the Minecraft server.
2. Copy Civilizations-1.0.1.jar into plugins/, removing older Civilizations JARs from that directory.
3. Add any optional integration plugins you plan to use.
4. Start once to generate plugins/Civilizations/, then stop before admitting players.
5. Edit the generated configuration and catalogs.

A first startup with the placeholder database password may report connection failures. Territory remains protected while the plugin waits for storage; finish configuration before opening the server.

The plugin generates:

plugins/Civilizations/
├── config.yml
├── resources.yml
├── technologies.yml
├── workorders.yml
├── religion.yml
└── messages.yml

5. Configure storage, economy, and worlds

Edit the matching sections in the generated plugins/Civilizations/config.yml. This is an excerpt, not a replacement for the entire file:

server-id: "primary"

database:
  host: "127.0.0.1"
  port: 3306
  database: "civilizations"
  username: "civilizations"
  password: "replace-with-your-database-password"
  ssl: false
  pool-size: 10
  connection-timeout-ms: 5000
  retry-seconds: 30

economy:
  mode: "VAULT"

worlds:
  allowed: ["world"]
  blacklisted-biomes: []
  fail-closed-during-warmup: true

travel:
  warmup-seconds: 5
  cooldown-seconds: 60
  safe-search-radius: 8
  claim-protection-radius-chunks: 1
  destinations:
    overworld:
      world: "world"
    nether:
      world: "world_nether"
    end:
      world: "world_the_end"

Choose DISABLED instead of VAULT if you want no currency features. The bundled default is DISABLED. With currency disabled, founding money costs are waived, effective plot prices are zero, and treasury transfers, selling, and tax collection are unavailable. Civic resources and Knowledge still matter.

Set database.ssl: true when using an endpoint configured for TLS. Keep real credentials out of source control. The files in src/main/resources/ are distributable templates; the files in the running server's plugin directory are its live configuration.

Use actual loaded world names. Civilizations does not create or load the Nether/End for you. worlds.allowed controls founding/new claims; travel target worlds are configured separately. An empty allowed-world list permits every world, so keep the default explicit list unless that is intended. One civilization's normal territory remains connected in one world.

For /civ teleport overworld, omit x, y, and z to use world spawn, or supply all three plus optional yaw and pitch for a fixed return location. Nether/End entries ignore those coordinates and use random safe ground in their configured worlds.

6. Set borders and the war schedule

Set a deliberate border in each travel world before players arrive. /wild, /nether, and /end sample positions using the target world's current border, including its center. A very large ungenerated area can cause expensive chunk generation during travel. Pre-generate the intended play area using your server's normal tooling if appropriate.

Keep a safe Overworld return point inside its border. Random Nether/End travel is refused if that return route cannot be resolved. Public claim reservations remain around the configured spawn/coordinate anchors, including the legacy Nether/End anchors; the default reservation radius is one chunk.

The default campaign window is Saturday, 14:00–18:00, America/Los_Angeles. Change war.timezone, weekday, start, and end to your intended schedule before players declare wars. The timezone is an IANA identifier, not a fixed UTC offset; scheduled times follow its daylight-saving rules.

7. Verify startup and admit players

Start the server and wait for:

MySQL is ready and the authoritative civilization cache is loaded.

Missing migrations are applied automatically. Do not import the packaged SQL files manually. Run these as an operator in game; omit the leading slash in the server console:

/civ admin migrate
/civ admin invariants
/civ admin audit page=1 size=20

migrate reports migration status; it does not manually execute a migration. For 1.0.1, the expected schema version is 8. Check for a healthy database, matching schema/checksums, no missing tables, and no invariant violations. Existing servers should also review the 1.0.1 upgrade notes.

Before opening the server, use a normal test player to check first-join placement, /wild, /civ help, /civ items, and /civ inspect. Test founding, access restrictions, and a plot purchase on a staging server. Test dimension travel with the required technologies unlocked and a crafted Nether Ember or End Sigil in inventory. Check /civ items → Other Items for their recipes and /religion for favor levels and Demeter's bread offering. If using taxes, confirm the economy provider can debit an offline test account.

---

Continue reading: Configuration reference · Administration and maintenance · Server troubleshooting