Installation Guide

Welcome to the comprehensive installation guide for osuNoLimits. This guide will walk you through setting up Shiina-Web and bancho.py-ex from scratch.

Prerequisites

Before starting, ensure you have:

• A Linux server (Ubuntu 24.04+ recommended)
• A domain name with DNS access
• Basic command-line knowledge
• Approximately 30-60 minutes

Domain Configuration

Configure the following subdomains to point to your server. We strongly recommend using Cloudflare for DNS management and DDoS protection.

Required Subdomains

Create these DNS records pointing to your server's IP:

A RecordsCloudflare SetupExample

Subdomain	Purpose	Example
@	Main domain	osunolimits.dev
osu	Game client connection	osu.osunolimits.dev
c	Game server	c.osunolimits.dev
c4	Game server	c4.osunolimits.dev
a	API endpoint	a.osunolimits.dev
assets	Static assets	assets.osunolimits.dev
api	Bancho API	api.osunolimits.dev

1. Add your domain to Cloudflare
2. Update nameservers at your registrar
3. Create the A records listed above
4. Enable proxy (orange cloud) for web traffic protection

SSL Configuration

You can choose between flexible or strict SSL encryption. For production environments, we recommend Full (Strict) SSL mode with valid certificates.

📖 Detailed SSL setup guide

Version Control Recommendation

Create a GitHub fork of the repositories before proceeding. This allows you to:

• Easily pull updates
• Make custom modifications
• Maintain your configuration

Installing bancho.py-ex

Docker Installation

Docker is required to run bancho.py-ex. Choose your operating system below:

Ubuntu Debian Fedora

Cleanup First

Remove any conflicting Docker packages:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do 
    sudo apt-get remove $pkg
done

Step 1: Add Docker's official GPG key and repository

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Step 2: Add Docker repository to APT sources

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Step 3: Install Docker

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Cleanup First

Remove any conflicting Docker packages:

for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do 
    sudo apt-get remove $pkg
done

Step 1: Add Docker's official GPG key and repository

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Step 2: Add Docker repository to APT sources

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Step 3: Install Docker

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Cleanup First

Remove any conflicting Docker packages:

sudo dnf remove docker \
              docker-client \
              docker-client-latest \
              docker-common \
              docker-latest \
              docker-latest-logrotate \
              docker-logrotate \
              docker-selinux \
              docker-engine-selinux \
              docker-engine

Step 2: Add Docker repository

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

Step 3: Install Docker

sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 4: Enable Docker service

sudo systemctl enable --now docker

Nginx Installation

Nginx serves as our web server and reverse proxy. Follow the instructions for your operating system:

Ubuntu & Debian Fedora

Remove Apache2 (Ubuntu only)

If Apache2 is installed, remove it first to avoid conflicts:

sudo systemctl stop apache2
sudo apt remove apache2 apache2-utils apache2-bin apache2.2-common
sudo apt autoremove

Step 1: Update package list and install Nginx

sudo apt update
sudo apt install nginx

Step 2: Verify installation

sudo systemctl status nginx

Expected Output

You should see Active: active (running) in green text.

Step 1: Update packages and install Nginx

sudo dnf update
sudo dnf install nginx

Step 2: Start and enable Nginx

sudo systemctl start nginx
sudo systemctl enable nginx

Step 3: Configure firewall

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Step 4: Verify installation

sudo systemctl status nginx

Git Installation

Git is required for cloning the repository and managing updates.

Ubuntu & Debian Fedora

Step 1: Update package list and install Git

sudo apt update
sudo apt install git

Step 2: Verify installation

git --version

Expected Output

You should see something like git version 2.34.1

Step 3: Configure Git (replace with your information)

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Step 1: Update packages and install Git

sudo dnf update
sudo dnf install git

Step 2: Verify installation

git --version

Expected Output

You should see something like git version 2.34.1

Step 3: Configure Git (replace with your information)

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Repository Setup

Clone the bancho.py-ex repository to your server:

Use Your Fork

If you created a fork, replace the URL with your fork's URL for easier updates.

git clone https://github.com/osu-NoLimits/bancho.py-ex.git /home/bancho-py-ex
cd /home/bancho-py-ex

Environment Setup

First, create your configuration files from the provided examples:

cp .env.example .env
cp logging.yaml.example logging.yaml

Edit Configuration

Open the environment file for editing:

nano .env

Required Configuration

You must configure these essential settings before proceeding:

Authentication SSL Settings (Optional) Customization (Optional) Webhooks (Optional)

Setting	Description	Required
OSU_API_KEY	Get your osu! API key here	✅
DB_PASS	Strong database password	✅
DOMAIN	Your domain (e.g., osunolimits.dev)	✅

Only required for Full/Strict SSL mode

SSL_CERT_PATH=/path/to/your/fullchain.crt
SSL_KEY_PATH=/path/to/your/private.key

Setting	Description	Example
SERVER_NAME	Your server's display name	osuNoLimits
DISCORD_URL	Your Discord invite link	https://discord.gg/yourinvite
MENU_ICON_URL	In-game menu icon	URL to your icon
MENU_ONCLICK_URL	Click destination	Your website URL
SEASONAL_BGS	Background images	Comma-separated URLs

Configure Discord webhooks for notifications:

FIRST_PLACES_WEBHOOK=https://discord.com/api/webhooks/...
ENABLE_FIRST_PLACES_WEBHOOK=True
DISCORD_AUDIT_LOG_WEBHOOK=https://discord.com/api/webhooks/...

Nginx Configuration

Install the pre-configured nginx setup:

./scripts/install-nginx-config.sh

Configuration Complete

Your nginx configuration has been automatically set up with the correct proxy settings for all bancho.py-ex endpoints.

Build and Start

With everything configured, build and start the project:

# Build the Docker containers
make build

# Start all services
make run

Development vs Production

• For development: Use make run for easier debugging
• For production: Consider using make run-bg or screen -S bancho make run to run in background

Autoban Configuration

Configure performance point limits to prevent cheating:

nano caps.json

PP Caps Configuration

{
    "enabled": true,
    "caps": {
        "0": 800,    // osu! standard
        "1": 1000,   // osu! taiko  
        "2": 900,    // osu! catch
        "3": 850     // osu! mania
    }
}

Important Notes

• Set "enabled": true to activate automatic banning
• Adjust PP values based on your server's skill level
• Monitor logs for any false positives