Skip to main content
This guide will walk you through setting up Mercury Core for local development, allowing you to customize and extend the platform.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Latest version of Bun
  • Latest version of Docker (optional, but recommended)
  • A modern web browser (Early 2024 onwards)
  • A code editor (Visual Studio Code recommended)
If you don’t have or can’t install Docker, you can run the database and economy service manually. See the alternative setup section below.

​
Installation Steps

1

Clone the repository

Clone Mercury Core to your local machine:
git clone <repository-url>
cd mercury-core
2

Install dependencies

Install all project dependencies using Bun:
bun i
3

Configure environment variables

Copy the example environment file and modify it:
cp Site/.env.example Site/.env
Edit Site/.env to configure your environment variables:
Site/.env
ORIGIN=https://mercs.dev
PORT=4443
BODY_SIZE_LIMIT=1G
EMAIL_PASSWORD=password
RCC_KEY=password
GAMESERVER_KEY=password
OPEN_CLOUD_KEY=whatever
The password, port, and RCCService key may be changed as required for your setup.
4

Start the database and economy service

Use Docker Compose to start the required services:
docker compose up -d database economy
This starts:
  • Database (SurrealDB) on port 8000
  • Economy service on port 2009
5

Start the development server

Navigate to the Site directory and start the dev server:
cd Site
bun dev
Navigate to the link shown in your terminal (remember not to use HTTPS for local development).
6

Create your first account

Once the server is running, navigate to /register and create an account to get started.

​
Alternative Setup (Without Docker)

If you can’t install Docker, you can run the services manually:
1

Install SurrealDB

Download and install SurrealDB for your platform.
2

Start the database

In the repository’s root directory, run:
surreal start -l trace -u=root -p=root file:./data/surreal
Keep this terminal window open or run it in the background.
3

Install Go

Download and install Go for your platform.
4

Start the economy service

Navigate to the Economy directory and run:
cd Economy
go run .
Keep this terminal window open or run it in the background.

​
Development Workflow

​
Live Reloading

Changes to your code will automatically be reflected in the browser when you save files. The Vite development server provides instant hot module replacement.
If you’re using WSL2 and the repository is stored on the Windows drive, the server may not correctly reflect changes. Either move the repository to a WSL-managed folder, or add the following to the default export in vite.config.ts:
server: { watch: { usePolling: true } },

​
Inspector Tool

While in the browser, press Ctrl+I to open the inspector, allowing you to select any element and view it in your editor.

​
Building for Production Preview

To test a production build locally: 
bun run build
bun preview

​
Available Scripts

The following npm scripts are available in the Site/ directory:
ScriptCommandDescription
devbun devStart development server
buildbun run buildBuild for production
previewbun previewPreview production build
buildviewbun buildviewBuild and preview in one command
formatbun run formatFormat code with Biome
lintbun run lintLint code with Biome
checkbun run checkRun Svelte type checking
check:watchbun run check:watchRun type checking in watch mode

​
Docker Services Configuration

The compose.yml file defines three services:

​
Database Service

database:
  build: ./Database
  ports:
    - 8000:8000
  restart: unless-stopped
  volumes:
    - ./data/surreal:/database
  command:
    - start
    - -u=root
    - -p=root
    - surrealkv://database

​
Economy Service

economy:
  build: ./Economy
  ports:
    - 2009:2009
  restart: unless-stopped
  volumes:
    - ./data/economy:/data/economy

​
Site Service (Optional)

site:
  build: .
  ports:
    - 4443:4443
  restart: unless-stopped
  depends_on:
    - database
    - economy
The site service is optional for development. You’ll typically run bun dev directly instead of using the containerized version.
For the best development experience, we recommend:
  • Visual Studio Code or derivatives (Insiders, VSCodium)
  • Mercury Core development extension pack - Includes all necessary extensions
The extension pack provides support for:
  • TypeScript
  • Svelte
  • Go
  • Code navigation and intellisense
  • Quality-of-life improvements

​
Next Steps

Now that your development environment is set up:

Build docs developers (and LLMs) love

Get started for freeTalk to us