Skip to main content

​
Overview

This guide will walk you through setting up Mercury Core for local development, from installing prerequisites to creating your first account. By the end, you’ll have a fully functional Mercury Core instance running on your machine.
This quickstart is for development purposes. For production hosting, see the Installation guide.

​
Prerequisites

Before you begin, ensure you have the following installed:

Bun

Latest version of Bun runtime and package managerDownload Bun

Docker

Latest version of Docker (or Podman as an alternative)Download Docker

Modern Browser

Any major browser from early 2024 onwards

Terminal

Command-line access on your system
We recommend using Visual Studio Code as your editor with the Mercury Core development extension pack.

​
Installation Steps

1

Clone the Repository

Clone the Mercury Core repository to your local machine:
git clone https://github.com/your-org/mercury-core.git
cd mercury-core
2

Install Dependencies

Install all required dependencies using Bun:
bun i
This will install all packages defined in Site/package.json including:
  • SvelteKit and Svelte 5
  • TypeScript and type definitions
  • SurrealDB client
  • UnoCSS for styling
  • And more developer tools
3

Configure Environment Variables

Copy the example environment file and configure it:
cp Site/.env.example Site/.env
Edit Site/.env with your preferred text editor. The default values work for local development:
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
For development, you can use the default values. For production, you must change all passwords and keys to secure values.
4

Start Database and Economy Services

Launch the required backend services using Docker Compose:
docker compose up -d database economy
This starts:
  • SurrealDB database on port 8000
  • Economy service (Go-based) on port 2009
If you can’t use Docker, you can run services manually:SurrealDB:
# Install SurrealDB first: https://surrealdb.com/install
surreal start -l trace -u=root -p=root file:./data/surreal
Economy Service:
# Install Go first: https://go.dev/dl/
cd Economy
go run .
Run these in separate terminal windows or as background processes.
5

Start Development Server

Navigate to the Site directory and start the Vite development server:
cd Site
bun dev
You’ll see output similar to:
VITE v5.x.x  ready in xxx ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
Navigate to the URL shown in your terminal (usually http://localhost:5173). Do not use HTTPS for local development.
The development server features:
  • Hot module replacement (HMR) - changes appear instantly
  • Type checking and IntelliSense
  • Fast refresh on file save
6

Create Your First Account

Once the server is running:
  1. Open your browser and navigate to http://localhost:5173/register
  2. Fill out the registration form with your desired username and password
  3. Complete the account creation process
Your account will be created with default avatar body colors configured in mercury.core.ts:
mercury.core.ts
DefaultBodyColors: {
  Head: 24,
  LeftArm: 24,
  LeftLeg: 119,
  RightArm: 24,
  RightLeg: 119,
  Torso: 23,
}
7

Explore Mercury Core

You’re all set! You can now:
  • Browse the home page and explore features
  • Customize your character in /character
  • Create games in /develop
  • Browse the catalog in /catalog
  • Configure settings in /settings
Press Ctrl+I in the browser to open the inspector, which lets you select any element and view it in your editor.

​
Understanding the Data Directory

Mercury Core stores all persistent data in the data/ directory (hidden from source control): 
data/
├── assets/       # Binary files: images, meshes, etc.
├── economy/      # Transaction ledger and economy data
├── icons/        # Place icons
├── surreal/      # SurrealDB database files
└── thumbnails/   # Asset thumbnails
The data/ directory should be kept private and backed up regularly. Consider mounting it to an external volume in production.

​
Making Changes

While the development server is running:
  1. Edit any file in Site/src/ - changes will reflect immediately in the browser
  2. Modify configuration in mercury.core.ts to customize branding, features, and behavior
  3. Check types by running bun run check in the Site directory
If you’re using WSL2 and changes aren’t reflecting, add this to vite.config.ts:
server: { watch: { usePolling: true } }

​
Building for Production

To preview how your site will work in production: 
# From the Site directory
bun run build
bun preview

# Or use the combined command
bun buildview
This creates an optimized production build in Site/build/ and starts a preview server.

​
Next Steps

Customize Your Revival

Learn how to configure branding, themes, and features in mercury.core.ts

Production Hosting

Deploy Mercury Core to a production server with Caddy and Docker

Client Integration

Connect Roblox revival clients to your Mercury Core instance

Architecture

Understand Mercury Core’s system architecture and services

​
Troubleshooting

If port 5173 is already in use, Vite will automatically try the next available port. Check your terminal output for the actual URL.
Ensure Docker containers are running:
docker ps
You should see database and economy containers. If not, run:
docker compose up -d database economy
Try:
  1. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
  2. Restart the dev server (Ctrl+C then bun dev)
  3. Clear browser cache
  4. If on WSL2, enable polling in vite.config.ts (see tip above)
Ensure Bun is installed and in your PATH:
curl -fsSL https://bun.sh/install | bash
Then restart your terminal.
Need help? Check out the Installation guide for more detailed setup instructions or the Configuration guide to customize your instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us