forge/docs/SURREALDB_SETUP.md

SurrealDB Setup

Forge uses SurrealDB for durable storage. The Rust server extension connects to SurrealDB on startup and applies Forge schema modules automatically, so setup comes down to running a reachable database and matching the Forge config.

Launch Requirement

Before launching an Arma server or local multiplayer test with Forge enabled:

1. Start SurrealDB and confirm it is listening on the endpoint Forge will use.
2. Copy arma/server/extension/config.example.toml to config.toml beside forge_server_x64.dll.
3. Make sure config.toml matches the running SurrealDB endpoint, namespace, database, username, and password.

Server owners and developers must do this before starting the dedicated server or hosting a test session. Mission designers and players do not need their own SurrealDB instance unless they are running the server locally, but the server they connect to must have SurrealDB running and configured.

If SurrealDB is not running, or if config.toml points at the wrong endpoint or credentials, persistence-backed systems such as actors, bank accounts, garages, lockers, organizations, phone data, stores, and tasks will not be ready for normal gameplay.

Choose the Right Path

Developer or Server Operator

Use this path if you are building Forge, running a local test server, or hosting the live Arma server.

Official SurrealDB resources:

• SurrealDB install page
• SurrealDB CLI start reference

Forge also includes helper scripts under arma/server/surrealdb:

cd arma/server/surrealdb
.\UpdateMe.bat
.\RunMe.bat

On Linux or macOS:

cd arma/server/surrealdb
./setup.sh
./run.sh

Install SurrealDB with the official method for your platform:

# Windows
iwr https://windows.surrealdb.com -useb | iex

# macOS
brew install surrealdb/tap/surreal

# Linux
curl -sSf https://install.surrealdb.com | sh

For Forge, start a persistent local database instead of the default in-memory mode:

surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb://forge.db

root/root is only the local development default. For a public or shared server, set a real password and keep config.toml aligned.

Then copy arma/server/extension/config.example.toml to config.toml next to forge_server_x64.dll and keep the values aligned with the database you started:

[surreal]
endpoint = "127.0.0.1:8000"
namespace = "forge"
database = "main"
username = "root"
password = "root"
connect_timeout_ms = 5000

Before starting the game server, confirm SurrealDB is still running. After launching the Arma server:

1. Let the extension connect and apply the Forge schema modules.
2. Verify the connection state:

"forge_server" callExtension ["status", []];
"forge_server" callExtension ["surreal:status", []];

If you change the endpoint, namespace, database, username, or password in SurrealDB, change the same values in Forge's config.toml.

Mission Designer or Community Manager/Leader

Use this path if you mostly need to inspect, query, or adjust data for a test or live server and you are not changing Forge source code.

Official SurrealDB resources:

• Surrealist installation
• Surrealist web app
• Surrealist local database serving

Recommended approach:

1. Install Surrealist Desktop. It is the better fit for Forge because the official docs note that the web app can be limited when connecting to localhost or non-HTTPS endpoints.
2. Connect Surrealist to the same database Forge uses.
3. Use the values from the server's config.toml:

Endpoint:   http://127.0.0.1:8000
Namespace:  forge
Database:   main
Username:   root
Password:   root

If you need your own local sandbox instead of connecting to an existing Forge server, install SurrealDB first and follow the developer/server-operator path above. Surrealist Desktop can also launch a local database for you after the surreal executable is installed and available on your PATH.