Backend Configuration

Configure Guccho’s backend settings, database connections, Redis, and API endpoints

The backend configuration file (guccho.backend.config.ts) controls how Guccho connects to your private osu! server, database, cache, and other backend services.

Creating Your Configuration

Copy the example configuration file and customize it for your setup:

cp guccho.backend.config.example.ts guccho.backend.config.ts

Use an editor with TypeScript support for better error detection and autocomplete.

Configuration Structure

Your configuration file should export a default object that satisfies the UserBackendConfig type:

import { resolve } from 'node:path'
import { type UserBackendConfig } from './src/def/config'
import { env, safeEnv } from './src/server/common/utils'

export default {
  // your configuration
} satisfies UserBackendConfig

Backend Adapters

use · string · required

The backend adapter to use. This determines which private server implementation Guccho will interface with.

Supported adapters:

• bancho.py - For bancho.py (gulag) servers
• [e-mail] - For ppy.sb servers (extends bancho.py)

use: '[e-mail]'

bancho.py

Basic configuration for bancho.py (gulag) servers:

export default {
  use: 'bancho.py',
  dsn: env('DB_DSN'),
  redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',
  sessionStore: 'redis',
  leaderboardSource: 'database',
  // ... other settings
} satisfies UserBackendConfig

Requires:

• MySQL database connection
• Redis (optional, but recommended for sessions)
• Gulag API v1 endpoint

[e-mail]

Configuration for ppy.sb servers (extends bancho.py with additional features):

export default {
  use: '[e-mail]',
  dsn: env('DB_DSN'),
  redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',
  sessionStore: 'redis',
  leaderboardSource: 'database',
  api: {
    v1: 'http://api.dev.ppy.sb/v1',
    sb: 'http://api.dev.ppy.sb/sb',
  },
  // ... other settings
} satisfies UserBackendConfig

Includes all bancho.py features plus:

• Additional database tables
• Extended API endpoints

Database Connection

dsn · string · required

Database connection string (Data Source Name). This is a required field and should be loaded from environment variables.

Format: mysql://username:password@host:port/database

dsn: env('DB_DSN')

Set in your .env file:

DB_DSN=mysql://username:password@localhost:3306/database

The env() function ensures this variable is set - Guccho will not start without it.

Redis Configuration

redisURL · string

Redis connection URL. Used for session storage and leaderboard caching.

Default: redis://localhost

redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost'

Set in your .env file:

REDIS_URL=redis://localhost:6379

sessionStore · 'redis' | 'memory'

Where to store user sessions.

Options:

• redis - Store sessions in Redis (recommended for production)
• memory - Store sessions in memory (development only)

sessionStore: 'redis'

Using memory for sessions means sessions will be lost when the server restarts.

Leaderboard Configuration

leaderboardSource · 'database' | 'redis'

Source for leaderboard data.

Options:

• database - Query leaderboards directly from the database
• redis - Use cached leaderboard data from Redis (faster)

leaderboardSource: 'database'

API Endpoints

api · object

API endpoint configuration for your private server.

api: {
  v1: 'http://api.dev.ppy.sb/v1',
  sb: 'http://api.dev.ppy.sb/sb',
}

Show API Fields

api.v1 · string

Base URL for the v1 API endpoint.

api.sb · string

Base URL for the sb (ppy.sb-specific) API endpoint. Only used with [e-mail] adapter.

Avatar Configuration

avatar · object

Configure where avatar images are stored and served from.

avatar: {
  location: resolve('.dump/ppy.sb/avatar'),
  domain: 'a.ppy.sb',
}

Show Avatar Fields

avatar.location · string · required

Absolute path to the avatar storage directory. Use resolve() to convert relative paths to absolute.

location: resolve('.dump/ppy.sb/avatar')

avatar.domain · string

Domain name for serving avatars.

domain: 'a.ppy.sb'

Always use absolute paths or the resolve() function for file paths to ensure correct locations when starting Guccho from different directories.

Article Configuration

article · object

Configure where article/news content is stored.

article: {
  location: resolve('articles'),
}

Show Article Fields

article.location · string · required

Absolute path to the articles directory. Use resolve() to convert relative paths.

location: resolve('articles')

Mail Configuration

mail · object

Email service configuration for sending notifications.

mail: {
  type: 'smtp',
  auth: 'smtps://account:password@server',
  sender: '[e-mail]',
}

Show Mail Fields

mail.type · string

Mail service type.

Options:

• smtp - Standard SMTP protocol

mail.auth · string

SMTP authentication URL.

Format: smtps://username:[e-mail]:port

auth: 'smtps://account:[e-mail]'

mail.sender · string

Email address to use as the sender.

sender: '[e-mail]'

Path Helpers

The resolve() function from Node.js converts relative paths to absolute paths:

import { resolve } from 'node:path'

// Relative path
location: resolve('articles')  // becomes /full/path/to/articles

// Multiple segments
location: resolve('.dump', 'avatars')  // becomes /full/path/to/.dump/avatars

Using resolve() ensures paths work correctly regardless of where Guccho is started from.

Complete Example

import { resolve } from 'node:path'
import { type UserBackendConfig } from './src/def/config'
import { env, safeEnv } from './src/server/common/utils'

export default {
  // Backend adapter
  use: '[e-mail]',

  // Database connection (required)
  dsn: env('DB_DSN'),

  // Redis connection (optional, defaults to localhost)
  redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',

  // Session and leaderboard configuration
  sessionStore: 'redis',
  leaderboardSource: 'database',

  // Articles
  article: {
    location: resolve('articles'),
  },

  // Avatar storage
  avatar: {
    location: resolve('.dump/ppy.sb/avatar'),
    domain: 'a.ppy.sb',
  },

  // API endpoints
  api: {
    v1: 'http://api.dev.ppy.sb/v1',
    sb: 'http://api.dev.ppy.sb/sb',
  },

  // Email configuration
  mail: {
    type: 'smtp',
    auth: 'smtps://account:[e-mail]',
    sender: '[e-mail]',
  },
} satisfies UserBackendConfig

Next Steps

UI Configuration

Configure branding, footer links, and UI settings

Environment Variables

Learn about environment variable management