A modern, feature-rich web frontend for custom osu! servers
Soumetsu is the official web frontend for RealistikOsu!, a custom server for the popular rhythm game osu!. Built with modern web technologies and a focus on user experience, Soumetsu provides a beautiful, responsive interface for players to interact with the server.
Originally based on hanayo, Soumetsu has evolved into a fully-featured web application that powers one of the most active custom osu! communities. With a clean, modern design and extensive customization options, it's the perfect foundation for your own osu! server.
- 🎨 Modern UI/UX - Beautiful, responsive design built with Tailwind CSS
- ⚡ High Performance - Fast, efficient Go backend with optimised templates
- 🔧 Highly Customisable - Easy to modify and extend for your needs
- 🌐 Feature Complete - Everything you need for a thriving osu! community
- 📱 Mobile Friendly - Works seamlessly on all devices
- 🔒 Secure - Built with security best practices in mind
Soumetsu comes packed with all the features you'd expect from a modern osu! server frontend:
- 👤 User Profiles - Comprehensive user profiles with statistics, achievements, and customization
- 🎵 Beatmap System - Browse, search, and download beatmaps with ranking support
- 🏆 Leaderboards - Global and country-specific leaderboards for all game modes
- 👥 Clan System - Create and manage clans with member management and boards
- 📊 Statistics - Detailed performance tracking and analytics
- 💬 Community Features - User interactions, comments, and social features
- 🎯 osu!standard - Full support for standard mode
- 🥁 osu!taiko - Taiko mode leaderboards and statistics
- 🍎 osu!catch - Catch the Beat mode support
- ⌨️ osu!mania - Mania mode rankings and features
- 🔐 Authentication - Secure login and registration system
- 📧 Email Integration - Password reset and notifications via Mailgun
- 🤖 Discord Integration - Connect with Discord for authentication and features
- 🛡️ Security - reCAPTCHA support and IP-based security features
Before you begin, ensure you have the following installed:
- Go 1.21 or higher (Download)
- Node.js 16+ and npm (Download)
- MySQL 5.7+ or MariaDB 10.3+
- Redis 6.0+
- Make (optional, for Docker builds)
-
Clone the repository
git clone https://github.com/RealistikOsu/soumetsu.git cd soumetsu -
Install Go dependencies
go mod download
-
Install Node.js dependencies
npm install
-
Build frontend assets
npm run tailwind:build # Or use the build script ./build.sh -
Configure the application
cp env.example .env # Edit .env with your configuration (see Configuration section) -
Run the application
go run ./cmd/soumetsu
The application will be available at http://localhost:8080 (or your configured port).
Soumetsu uses environment variables for configuration. Copy env.example to .env and customise the values:
SOUMETSU_PORT=8080 # Port to run the server on
SOUMETSU_ENV=development # Environment (development/production)
SOUMETSU_COOKIE_SECRET=your-secret # Secret key for cookies (min 32 chars)
SOUMETSU_KEY=your-soumetsu-key # Application key
SOUMETSU_BASE_URL=http://localhost:8080MYSQL_HOST=localhost
MYSQL_TCP_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your-password
MYSQL_DATABASE=rosuREDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASS=
REDIS_DB=0
REDIS_USE_SSL=falseMAILGUN_DOMAIN=your-mailgun-domain
MAILGUN_API_KEY=your-api-key
MAILGUN_PUBLIC_KEY=your-public-key
MAILGUN_FROM=noreply@your-domain.comDISCORD_SERVER_URL=https://discord.gg/your-server
DISCORD_APP_CLIENT_ID=your-client-id
DISCORD_APP_CLIENT_SECRET=your-client-secretRECAPTCHA_SITE_KEY=your-site-key
RECAPTCHA_SECRET_KEY=your-secret-keySOUMETSU_INTERNAL_AVATARS_PATH=./static/avatars
SOUMETSU_INTERNAL_BANNERS_PATH=./static/banners
SOUMETSU_AVATAR_URL=https://a.ussr.pl
SOUMETSU_BANCHO_URL=https://c.ussr.plSOUMETSU_API_URL=http://localhost:5000
SOUMETSU_BEATMAP_MIRROR_API_URL=https://api.ussr.pl
SOUMETSU_BEATMAP_DOWNLOAD_MIRROR_URL=https://mirror.ussr.plNote: Make sure to change all default values, especially secrets and keys, before running in production!
-
Start the development server with hot-reload for CSS
# Terminal 1: Run the Go server go run ./cmd/soumetsu # Terminal 2: Watch Tailwind CSS changes npm run tailwind:watch
-
Build for production
# Build Go binary go build -o soumetsu ./cmd/soumetsu # Build frontend assets npm run tailwind:build
Soumetsu includes Docker support for easy deployment:
# Build Docker image
make build
# or
docker build -t soumetsu:latest .
# Run with Docker
make run
# or
docker run --network=host --env-file=.env soumetsu:latestsoumetsu/
├── cmd/
│ └── soumetsu/ # Main application entry point
├── internal/ # Internal Go packages
│ ├── api/ # API handlers
│ ├── config/ # Configuration management
│ └── models/ # Data models
├── web/
│ ├── static/ # Static assets (CSS, JS, images)
│ └── templates/ # HTML templates
├── data/ # Data files (YAML, JSON)
├── scripts/ # Build and utility scripts
└── website-docs/ # Documentation content
npm run tailwind:watch- Watch and rebuild Tailwind CSS on changesnpm run tailwind:build- Build Tailwind CSS for productionnpm run dev- Alias fortailwind:watch./build.sh- Full build script (installs deps, builds CSS and JS)
- RealistikOsu! Website: https://ussr.pl/
- GitHub Organization: https://github.com/RealistikOsu
- Original hanayo: https://github.com/osuripple/hanayo
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.
The AGPL-3.0 license ensures that any modifications to this software, when run on a network server, must be made available to users of that server.
Ready to build your own osu! server? Get started with Soumetsu today!