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 '[email protected]'
  use: '[email protected]',
  
  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

Build docs developers (and LLMs) love

Get started for freeTalk to us