Skip to content

Self-Hosting Setup Guide

This guide walks you through the step-by-step setup process for hosting your own Sparkle server instance, covering both local SQLite development and multi-container production deployments.

Prerequisites

Before beginning, ensure you have installed the following requirements on your host machine:

  • Git: For cloning the repositories and submodules.
  • Docker & Docker Compose: Recommended for standard production setups (Method 1).
  • Go (v1.25.10+): Required only if compiling the Go binary directly on your system (Method 2).
  • Rust & Cargo: Required only if building the Schedule sidecar server directly from source code (Method 2).

This method deploys the entire production-ready Sparkle emulation stack using Docker container orchestration.

Step 1: Clone the Repository

Clone the sparkle-server repository directly:

# Clone the sparkle-server repository
git clone https://gitlab.com/kirafan/sparkle/server.git sparkle-server
cd sparkle-server

Step 2: Configure Environment Variables

Create and configure your .env file:

cp .env_example .env

Open .env and fill out the critical security variables:

# Set your production database name and password
DB_TYPE=mysql
DB_NAME=sparkle
DB_USER=sparkle_user
DB_PASS=your_secure_password
DB_ROOT=your_root_password

# Client encryption configuration
# (Obtain the active decryption details from your community)
SECURITY_ENCRYPT_KEY=<ENCRYPTION_KEY>
SECURITY_ENCRYPT_PAD=<ENCRYPTION_PAD>
SECURITY_ENCRYPT_ENABLED=true

Step 3: Launch the Stack

Start all necessary containers in the background using docker-compose:

docker compose up -d

Note

The default Docker images defined in compose.yaml (e.g., sparkle-api, sparkle-web-admin) target the arm64 architecture (e.g., Apple Silicon or ARM64 Linux servers). If you are running on an x86_64 (AMD64) host (like standard Intel/AMD Windows or Linux machines), Docker will attempt to run them using QEMU emulators. While it works, you may experience significant CPU usage and response latency.

The compose file automatically pulls, configures, and spins up the following services:

  • sparkle-db: MySQL database container.
  • sparkle-schedule: Rust sidecar timeline compiler.
  • sparkle-api: Main Go server endpoint (running on port 8080).
  • sparkle-adminer-evo: Web-based database client.
  • sparkle-web-admin: Premium administrative front-end interface.
  • Note: Secondary helper services like sparkle-batch (for batch jobs) and sparkle-dbbackup (for S3 database backups) are also defined in the compose file but are optional.

Verify all services are running:

docker compose ps

Method 2: Local SQLite Setup (No Docker / Quick Dev)

If you wish to test changes quickly or run a simple local single-player instance without Docker overhead, you can build the servers directly.

Step 1: Set Up the Schedule Server Mock (Optional)

If you want to run the timeline mock server, clone and launch the schedule-server-mock repository in a separate terminal:

# Run this in a separate folder (outside sparkle-server)
git clone https://gitlab.com/kirafan/sparkle/schedule-server-mock.git
cd schedule-server-mock
poetry install
poetry run python main.py

The schedule server mock will start listening at http://127.0.0.1:8100. (Note: If you do not want to run this mock server, the Go server will automatically fall back to a Dummy repository. You can skip this step.)

Step 2: Configure the Go Server to Use SQLite

In your sparkle-server directory, copy the configuration template to .env:

cp .env_example .env

Open .env and edit the database variables to switch to SQLite mode:

# SQLite settings
DB_TYPE=sqlite
DB_NAME=sparkle-server.db

# Schedule service endpoint pointing to the local mock server instance
# (Tip: If you do not want to run the Schedule Server Mock, you can leave this variable empty
# or comment it out. The Go server will automatically fall back to a Dummy repository,
# allowing offline solo play with zero dependency setups!)
ENDPOINT_SCHEDULE_SERVER=http://localhost:8100

# Client encryption configuration
SECURITY_ENCRYPT_KEY=<ENCRYPTION_KEY>
SECURITY_ENCRYPT_PAD=<ENCRYPTION_PAD>
SECURITY_ENCRYPT_ENABLED=true

Step 3: Run the Main Application

Navigate to the directory containing main.go and start the server (the .env file in the project root directory will still be automatically loaded by the application's config engine):

cd cmd/main
go run main.go

The Go server will start listening at http://localhost:8080.

Connecting the Client to Your Server

Once your local server is up and running, you need to point your game client to your custom endpoints.

  1. Get the Endpoint Details:

    • Local Setup: http://localhost:8080 (or your local IP address for physical devices).
    • Production VPS: https://your-domain-or-ip/ (ensure SSL/TLS is handled appropriately via a reverse proxy like Nginx or Caddy if deploying publicly).

  2. Apply Configuration:

    • Choose your preferred connection redirection method (e.g., Sparkle Router or custom interception tools) as described in the player guides.
    • Obtain your community's Asset version hash and point your client to the endpoint matching your deployment.

Enjoy your custom game server environment! 🚀