Self-Hosting Overview¶

This section explains the architecture of the Sparkle emulation ecosystem and helps you understand how different components interact when running a private local server or community instance.

Ecosystem Architecture¶

The Sparkle self-hosted environment consists of multiple services working together to simulate the official game backend services.

Here is how the services communicate under the hood:

flowchart TD
    Client(["Game Client<br>(v3.6.0)"])
    RouterWeb(["Sparkle Router Web<br>(Nuxt 4 / Turnstile)"])
    Router(["Sparkle Router<br>(Go / Echo)"])
    Worker(["Cloudflare Worker<br>(sparkle-router-worker)"])

    API(["Sparkle API Server<br>(Go / net/http)"])
    Schedule(["Schedule Server Mock<br>(Python / FastAPI)"])
    DB[("MariaDB / MySQL / SQLite")]
    Adminer(["Adminer / Adminer-Evo<br>(Database Client)"])
    AdminWeb(["Web Admin<br>(Go-Admin) [Deprecated]"])

    %% Configuration flow
    RouterWeb -->|"Configure endpoints"| Router
    Client -->|"Read redirect config (30s TTL)"| Worker
    Worker -->|"Proxy version check"| Router

    %% Gameplay flow
    Client -->|"API Requests (Port 8080)"| API
    API -->|"Manage Schedule / Town"| Schedule
    API -->|"Read/Write Player Data"| DB
    Adminer -->|"Manage & Inspect Data"| DB
    AdminWeb -->|"Manage & Inspect Data"| DB

    %% Color coding styles
    classDef client fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px,color:#000;
    classDef community fill:#e0f7fa,stroke:#00acc1,stroke-width:2px,color:#000;
    classDef selfhost fill:#fff3e0,stroke:#fb8c00,stroke-width:2px,color:#000;

    class Client client;
    class RouterWeb,Router,Worker community;
    class API,Schedule,DB,Adminer,AdminWeb selfhost;

Tip

Diagram Color Coding:

Light Grey (Client): Game Client (runs on player's device).
Cyan (Community-Managed): Centrally hosted routing infrastructure managed by the Sparkle Community (out of scope for personal self-hosting).
Orange (Self-Hosted): Core servers and databases you host locally or on your private server.

Component Breakdown¶

To host your own Sparkle instance, you only need to run the core game services. The routing infrastructure is centrally managed.

Important

Community-Managed Infrastructure (Not Required for Self-Hosting) Sparkle Router Web, Sparkle Router, and Cloudflare Worker are centrally hosted and maintained by the Sparkle Community. You do not need to self-host these components for a personal instance. Instead, you register your private server endpoint on the community-hosted Router Web portal to redirect your client.

1. Sparkle API Server (Go)¶

The core emulation backend that implements game API endpoints (accounts, gacha, quests, training, rooms, weapons, and more).

Technology: Go (Golang) + mux.Router + Gorm
Primary Port: 8080 (API Server)
Features: Highly scalable, low response latency (typically under 3 seconds per request), supports standard logging (Zap) and OpenTelemetry.

2. Schedule Server Mock (Python)¶

A lightweight sidecar mock service responsible for generating frozen room schedules and item drops. This is used by default for local development.

Technology: Python + FastAPI + Uvicorn
Primary Port: 8100
Integrations: Queried by the main Sparkle API server during player data initialization and login.
Note: An advanced Rust-based production Schedule Server (schedule-server) is also available for dynamic community timeline calculations.

3. Database Clients (Adminer / Web Admin)¶

Tools used to inspect and modify game player databases and master tables.

Adminer / Adminer-Evo (Recommended): The primary tool used for active database management and debugging in local/development environments.
Web Administration Interface (Go-Admin) [DEPRECATED]: A legacy administration dashboard built on Go + Go-Admin. This component is no longer actively maintained.

4. Database Storage¶

Stores persistent player progress, inventory, master tables, and configuration settings.

Supported Engines: MariaDB (Recommended for production), MySQL (v8.0+), or SQLite (CGO-free, recommended for easy offline local development).

5. Sparkle Router Web (Nuxt 4) & Sparkle Router (Go) [Community-Managed / Out of Scope]¶

The routing infrastructure hosted by the Sparkle Community. (Personal self-hosting of these components is not required).

Sparkle Router Web (Nuxt 4): A web interface built with Nuxt 4, Tailwind CSS, and Cloudflare Turnstile, allowing players to securely associate their public IP address with their custom server endpoints.
Sparkle Router (Go): A high-performance proxy router written in Go (using the Echo framework). It handles client /api/app/version/get requests, serving the encrypted redirect payloads based on the IP configuration mapping stored in its memory cache (30-second TTL).
Sparkle Router Worker (Cloudflare Workers): An optional proxy worker deployed to Cloudflare. It intercepts version check requests on the official domain (krr-prd.star-api.com/api/app/version/*) and routes them to the active Sparkle Router instance without requiring DNS alterations on the player's client.

Choose Your Deployment Mode¶

Depending on your purpose, we support two primary hosting approaches:

SQLite Mode (Single Binary / CGO-free):
- Best for: Solo offline play, local research, and lightweight debugging.
- Pros: Zero Docker configuration required. Single .db file database.
Docker-Compose Mode (Production):
- Best for: Small community servers, persistent multi-user environments, and full orchestration.
- Pros: Complete automated setup including automatic daily backups, Adminer panel, sidecar schedule engine, and production-grade MariaDB database.

Proceed to the Self-Hosting Setup Guide to begin setting up your server!