c676a9084e
- Add shared `bin/host/config.example.toml` and remove the old host example - Split Arma config creation between `server.cfg` and `basic.cfg` - Update docs and examples to reflect shared host-managed config
137 lines
4.8 KiB
Markdown
137 lines
4.8 KiB
Markdown
# 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. Create Forge's `config.toml`. Use `bin/host/config.example.toml` at the repo
|
|
root when Forge Host manages local services, or copy
|
|
`arma/server/extension/config.example.toml` beside `forge_server_x64.dll`
|
|
for an extension-only deployment.
|
|
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](https://surrealdb.com/install)
|
|
- [SurrealDB CLI `start` reference](https://surrealdb.com/docs/surrealdb/cli/start)
|
|
|
|
Forge Host includes the recommended local setup path. Open the SurrealDB view
|
|
to install or update SurrealDB, configure the bind address and database path,
|
|
and start or stop the local database. Enter `3` to install the latest compatible
|
|
SurrealDB 3.x release, enter an exact version such as `v3.1.2` to pin a
|
|
release, or enter `latest` only after confirming compatibility with the Forge
|
|
server extension.
|
|
|
|
Install SurrealDB with the official method for your platform:
|
|
|
|
```powershell
|
|
# Windows
|
|
iwr https://windows.surrealdb.com -useb | iex
|
|
```
|
|
|
|
```bash
|
|
# macOS
|
|
brew install surrealdb/tap/surreal
|
|
```
|
|
|
|
```bash
|
|
# Linux
|
|
curl -sSf https://install.surrealdb.com | sh
|
|
```
|
|
|
|
For Forge, start a persistent local database instead of the default in-memory
|
|
mode:
|
|
|
|
```powershell
|
|
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 create Forge's `config.toml` and keep the values aligned with the database
|
|
you started. If you use Forge Host locally, copy `bin/host/config.example.toml`
|
|
to the repo root as `config.toml`; the host will use the same file for managed
|
|
processes, ICOM, and extension settings. If you only need the Arma extension
|
|
config, copy `arma/server/extension/config.example.toml` next to
|
|
`forge_server_x64.dll`.
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```sqf
|
|
"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](https://surrealdb.com/docs/surrealist/installation)
|
|
- [Surrealist web app](https://app.surrealdb.com)
|
|
- [Surrealist local database serving](https://surrealdb.com/docs/surrealist/concepts/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`:
|
|
|
|
```text
|
|
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`.
|