Skip to main content

​
Overview

This guide will walk you through setting up Guccho from initial configuration to running your development server.
Make sure you’ve completed the installation steps before proceeding.

​
Configuration Setup

Guccho requires two main configuration files: one for the UI and one for the backend.
1

Create UI configuration

Copy the example UI configuration file:
cp guccho.ui.config.example.ts guccho.ui.config.ts
Edit guccho.ui.config.ts to customize your frontend settings:
guccho.ui.config.ts
export default {
  legacyOption: {
    name: 'Your Server Name', // Customize your server name
  },
  baseUrl: 'your-domain.com', // Your server's base domain
  brand: {
    icon: 'ion:paw', // Brand icon from Iconify
    iconClass: 'w-8 h-4',
  },
  // ... additional UI settings
} satisfies UIConfig
You can customize branding, footer links, and internationalization settings. See the example file for detailed comments.
2

Create backend configuration

Copy the example backend configuration file:
cp guccho.backend.config.example.ts guccho.backend.config.ts
Edit guccho.backend.config.ts to match your backend setup:
guccho.backend.config.ts
import { resolve } from 'node:path'
import { env, safeEnv } from './src/server/common/utils'

export default {
  // Choose your backend: 'bancho.py' or 'ppy.sb@bancho.py'
  use: 'ppy.sb@bancho.py',
  
  article: {
    location: resolve('articles'), // Where to store articles
  },
  
  sessionStore: 'redis', // or 'memory'
  leaderboardSource: 'database', // or 'redis'
  
  redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost',
  dsn: env('DB_DSN'), // Required: MySQL connection string
  
  avatar: {
    location: resolve('.dump/avatar'),
    domain: 'a.your-domain.com',
  },
  
  api: {
    v1: 'http://api.your-domain.com/v1',
    sb: 'http://api.your-domain.com/sb',
  },
} satisfies UserBackendConfig
The dsn field is required and must point to a valid MySQL database. Guccho will not start without it.
3

Set up environment variables

Create a .env file using the example as a template:
cp .env.example .env
Edit .env with your environment-specific values:
.env
NUXT_PUBLIC_BASE_URL=your-domain.com

# Database connection (required for bancho.py backends)
DB_DSN=mysql://username:password@localhost:3306/database

# Redis connection (required if using redis session store)
REDIS_URL=redis://localhost:6379
Use safeEnv() in config files for optional variables and env() for required ones. Missing required variables will prevent Guccho from starting.
4

Create articles directory

Create the directory for storing articles:
mkdir -p articles

​
Running Guccho

​
Development Server

Start the development server on http://localhost:3000: 
pnpm dev
Your Guccho instance should now be running at http://localhost:3000!

​
Production Build

For production deployment, build the application first:
1

Build for production

pnpm build
2

Start production server

pnpm start:prod
The production server uses dotenv-cli to load environment variables from .env.

​
Configuration Options Explained

​
Environment Variable Helpers

Guccho provides two helper functions for environment variables:
  • env(name): Required variable. Throws an error if not set.
  • safeEnv(name): Optional variable. Returns undefined if not set.
// Required - will crash if DB_DSN is not set
dsn: env('DB_DSN')

// Optional with fallback
redisURL: safeEnv('REDIS_URL') ?? 'redis://localhost'

​
Path Resolution

Always use resolve() for file paths to ensure they work regardless of where Guccho is started from: 
import { resolve } from 'node:path'

// Good - uses absolute path
location: resolve('articles')

// Also good - explicit absolute path
location: '/var/www/guccho/articles'

// Bad - relative paths may break
location: './articles'

​
Troubleshooting

Make sure you’ve set the DB_DSN environment variable in your .env file:
DB_DSN=mysql://username:password@localhost:3306/database
If using Redis for sessions or leaderboards, ensure Redis is running:
redis-cli ping
# Should return: PONG
Alternatively, use sessionStore: 'memory' in guccho.backend.config.ts for development.
Try reinstalling dependencies:
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
Next Steps

Backend Configuration

Learn about advanced backend configuration options

UI Configuration

Customize your UI and branding

Features

Explore Guccho’s features

Architecture

Understand the system architecture