Skip to main content
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
  • ppy.sb@bancho.py - For ppy.sb servers (extends bancho.py)
use: 'ppy.sb@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

​
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',
}

​
Avatar Configuration

​
avatar
object
Configure where avatar images are stored and served from.
avatar: {
  location: resolve('.dump/ppy.sb/avatar'),
  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'),
}

​
Mail Configuration

​
mail
object
Email service configuration for sending notifications.
mail: {
  type: 'smtp',
  auth: 'smtps://account:password@server',
  sender: 'pe@ppy.sb',
}

​
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: 'ppy.sb@bancho.py',

  // 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:password@smtp.example.com',
    sender: 'noreply@example.com',
  },
} satisfies UserBackendConfig

​
Next Steps

UI Configuration

Configure branding, footer links, and UI settings

Environment Variables

Learn about environment variable management

Build docs developers (and LLMs) love

Get started for freeTalk to us