Installation

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	Avatar 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

Installing Shiina-Web

bancho.py-ex should be installed at this step

Installing Java

Ubuntu Debian Fedora

sudo apt install openjdk-21-jdk -y

echo "deb http://deb.debian.org/debian bullseye-backports main" | sudo tee /etc/apt/sources.list.d/backports.list
sudo apt update

# Debian 12
sudo apt install openjdk-21-jdk -y

# Debian 11
sudo apt install -t bullseye-backports openjdk-21-jdk -y

sudo dnf install java-21-openjdk-devel -y

Repository Setup

Clone the Shiina-Web 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/Shiina-Web.git /home/Shiina-Web
cd /home/Shiina-Web

Configuration

# Navigate to the config directory
cd .config

cp .env.example .env && cp customization.yml.example customization.yml && cp logger.env.example logger.env

# Editing customization.yml is pretty obvious (no tutorial here)

nano .env

Required Configuration

You must configure these essential settings before proceeding:

Main Optional

Setting	Description	Required
TURNSTILE_KEY	Get Cloudflare Captcha key here	✅
TURNSTILE_SECRET	Get Cloudflare Captcha key here	✅
DBPASS	Your bancho.py-ex DB_PASS	✅
DOMAIN	Your domain (def. https://osunolimits.dev)	✅
APIURLPUBLIC	Your pub api domain (def. https://api.osunolimits.dev)	✅
ASSETSURL	Your pub assets domain (def. https://assets.osunolimits.dev)	✅
AVATARSRV	Your pub avatars domain (def. https://a.osunolimits.dev)	✅

Setting	Description	Required
DOWNLOAD_MARKETPLACE_PLUGIN	Offers a plugin marketplace (def. true)	❌
APIURL	Local API Host (Should stay default)	❌
AVATARFOLDER	Avatar folder only needs change when installed not like wiki	❌

Build and Start

With everything configured, build and start the project:

# Build shiina
make build

# Start the frontend
make run

Development vs Production

• For development: Use make run-dev for easier debugging and hot reloading
• For production: Consider using screen -S shiina make run to run in background

Frequently Asked Questions

Here you'll find answers to the most common questions.

---

Installation

How can I use local machine MySQL and Redis?

To use local MySQL and Redis you can create a docker-compose.override.yml

cd /home/bancho.py-ex
nano docker-compose.override.yml

File Content:

services:
    bancho:
        depends_on: []
        network_mode: host
        volumes:
        - /home/bancho.py-ex/.data:/srv/root
        - .:/srv/root
        - data:/srv/root/.data
        environment:
        - DB_HOST=127.0.0.1
        - REDIS_HOST=127.0.0.1

    mysql:
        deploy:
        replicas: 0

    redis:
        deploy:
        replicas: 0

Now your bancho will use your machines mysql and redis

No worries the docker-compose.override.yml is in .gitignore

Why are my assets/avatars not showing up?

Fix for Avatar Server (a.your.domain) Returning 404

If /var/log/nginx/error.log reports permission denied, run:

chown -R www-data:www-data /var/lib/docker/volumes/banchopy-ex_data/_data
chown -R www-data:www-data /home/bancho.py-ex/.data
chmod +x /var/lib/docker/volumes/banchopy-ex_data
chmod +x /var/lib/docker/volumes
chmod +x /var/lib/docker

What this does: - Gives www-data (the Nginx user) ownership of the _data folder, which is stored inside a Docker volume.
- Allows all users on your machine to browse the bancho.py Docker volume.
- Allows all users on your machine to browse the Docker volumes folder.
- Allows all users on your machine to browse the Docker folder.
- (does not include sub-folders)

Note: If you use Caddy instead of Nginx, replace all occurrences of www-data with caddy.

How to setup default avatar?

Nginx is looking in /home/bancho.py-ex/.data/avatars for a default.jpg

Note: It can be possible that you need to reset permissions, help is in the section above

How can I recieve Donations on shiina?

The only provider supported is kofi

nano /home/Shiina-Web/data/monetization.json
# Set enabled to `true`
# Restart shiina
nano /home/Shiina-Web/data/monetization/kofi.json

https://ko-fi.com/manage/webhooks?src=sidemenu

Enter https://yourdomain.dev/handlekofi

On Advanced you can get your verification token

File Content

{
    "verificationToken": "your-access-token",
    "pageName": "osunolimits",
    "donationAmount": 1
}

donationAmount is the amount of your currency to pay

If someones buys for 10$ it would equal to 10 months

---

Usage

Why is my rank graph not showing?

It needs at least a week of data to show

Can I change code?

Yes but it isn't recommended, it can cause issues updating. Use plugins/themes if possible

---

Troubleshooting

Can I see frontend logs?

Shiina keeps logs for 30days and rotates them

cd /home/Shiina-Web/logs

How can I recalc PP?

For recalc you need to open a shell in the docker container

docker ps
# Pick the container id that runs bancho
docker exec -it yourid sh
# now go into tools
cd tools/
python recalc.py

How clear frontend sessions/cache?

apt install redis-tools # or for your system
redis-cli
# now you are in redis terminal
EVAL "for _,k in ipairs(redis.call('KEYS', 'shiina:*')) do redis.call('DEL', k) end" 0
# Now you need to restart shiina to initialize some keys