Configurations

This page lists all available configuration options in the .env file and their descriptions.

Warning

In a production environment, be sure to change the default keys and passwords!

Documentation Contributor Tip

This file is auto-generated, and any changes will be overwritten. If you want to modify the translation, please edit data/configuration/en.js. Click the "Edit this page on GitHub" link at the bottom left to jump directly to the editing page of that file.

Last generated on 2026-02-20T09:09:06Z (commit: 0295b5858374cc9d93e6a2647e40cff01a686e2b).

Database Settings

Configuration	Description	Type	Default
`MYSQL_HOST`	MySQL Server Address	string	`localhost`
`MYSQL_PORT`	MySQL Server Port	integer	`3306`
`MYSQL_DATABASE`	MySQL Database Name	string	`osu_api`
`MYSQL_USER`	MySQL Username	string	`osu_api`
`MYSQL_PASSWORD`	MySQL Password	string	`password`
`MYSQL_ROOT_PASSWORD`	MySQL Root Password	string	`password`
`REDIS_URL`	Redis Connection URL	string	`redis://127.0.0.1:6379`

JWT Settings

Configuration	Description	Type	Default
`JWT_SECRET_KEY`	JWT Signing Key	string	`your_jwt_secret_here`
`JWT_ALGORITHM`	JWT Algorithm	string	`HS256`
`ACCESS_TOKEN_EXPIRE_MINUTES`	Access Token Expiration Time (Min)	integer	`1440`
`REFRESH_TOKEN_EXPIRE_MINUTES`	Refresh Token Expiration Time (Min)	integer	`21600`
`JWT_AUDIENCE`	JWT Audience	string	`5`
`JWT_ISSUER`	JWT Issuer	string	`null`

OAuth Settings

Configuration	Description	Type	Default
`OSU_CLIENT_ID`	OAuth Client ID	integer	`5`
`OSU_CLIENT_SECRET`	OAuth Client Secret	string	`FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk`
`OSU_WEB_CLIENT_ID`	Web OAuth Client ID	integer	`6`
`OSU_WEB_CLIENT_SECRET`	Web OAuth Client Secret	string	`your_osu_web_client_secret_here`

Server Settings

Configuration	Description	Type	Default
`HOST`	Server Listening Address	string	`0.0.0.0`
`PORT`	Server Listening Port	integer	`8000`
`DEBUG`	Whether to enable Debug Mode	boolean	`false`
`CORS_URLS`	Additional CORS allowed domain list (JSON format)	array<string>	`[]`
`SERVER_URL`	Server URL	string	`http://localhost:8000/`
`FRONTEND_URL`	Frontend URL, will redirect to this URL when accessing URL opened from game. Empty means no redirect.	string	`null`
`ENABLE_RATE_LIMIT`	Whether to enable Rate Limiting	boolean	`true`

Fetcher Settings

Fetcher is used to fetch data from osu! official API, using osu! official API OAuth 2.0 authentication

Configuration	Description	Type	Default
`FETCHER_CLIENT_ID`	Fetcher Client ID	string	`""`
`FETCHER_CLIENT_SECRET`	Fetcher Client Secret	string	`""`

Log Settings

Configuration	Description	Type	Default
`LOG_LEVEL`	Log Level	string	`INFO`

Verification Service Settings

Configuration	Description	Type	Default
`ENABLE_TOTP_VERIFICATION`	Whether to enable TOTP Two-Factor Authentication	boolean	`true`
`TOTP_ISSUER`	Issuer Name in TOTP Authenticator	string	`null`
`TOTP_SERVICE_NAME`	Service Name displayed in TOTP Authenticator	string	`g0v0! Lazer Server`
`TOTP_USE_USERNAME_IN_LABEL`	Use username instead of email in TOTP label	boolean	`true`
`ENABLE_TURNSTILE_VERIFICATION`	Whether to enable Cloudflare Turnstile Verification (Non-osu clients only)	boolean	`false`
`TURNSTILE_SECRET_KEY`	Cloudflare Turnstile Secret Key	string	`""`
`TURNSTILE_DEV_MODE`	Turnstile Dev Mode (Skip verification, for local dev)	boolean	`false`
`ENABLE_EMAIL_VERIFICATION`	Whether to enable Email Verification	boolean	`false`
`ENABLE_SESSION_VERIFICATION`	Whether to enable Session Verification Middleware	boolean	`true`
`ENABLE_MULTI_DEVICE_LOGIN`	Whether to allow multi-device login simultaneously	boolean	`true`
`MAX_TOKENS_PER_CLIENT`	Max tokens per client per user	integer	`10`
`DEVICE_TRUST_DURATION_DAYS`	Device Trust Duration Days	integer	`30`

Email Service Settings

Configure the email provider and related parameters.

If EMAIL_PROVIDER starts with -, the server will try to load the email provider implementation from the plugin corresponding to the id after it. If EMAIL_PROVIDER does not contain ., it is considered a built-in email provider name. Currently, there is one built-in provider: smtp. Otherwise, the server will try to load the email provider implementation from the module path specified by EMAIL_PROVIDER.

smtp (Default)

bash

EMAIL_PROVIDER="smtp"
EMAIL_PROVIDER_CONFIG='{
    "smtp_server": "smtp.example.com",
    "smtp_port": 587,
    "smtp_username": "your_smtp_username",
    "smtp_password": "your_smtp_password",
}'

Configuration	Description	Type	Default
`EMAIL_PROVIDER`	Email Provider	string	`smtp`
`EMAIL_PROVIDER_CONFIG`	Email Provider Config (JSON)	object	`null`
`FROM_EMAIL`	Sender Email	string	`noreply@example.com`
`FROM_NAME`	Sender Name	string	`osu! server`

Monitoring Settings

Configure application monitoring options, such as Sentry and New Relic.

Place newrelic.ini config file in the project root to automatically enable New Relic monitoring. If config file does not exist or newrelic package is not installed, New Relic initialization will be skipped.

Configuration	Description	Type	Default
`SENTRY_DSN`	Sentry DSN, empty to disable Sentry	string	`null`
`NEW_RELIC_ENVIRONMENT`	New Relic Environment ID, set to "production" or "development"	string	`null`

GeoIP Settings

Configuration	Description	Type	Default
`MAXMIND_LICENSE_KEY`	MaxMind License Key (For downloading offline IP DB)	string	`""`
`GEOIP_DEST_DIR`	GeoIP Database Storage Directory	string	`./geoip`
`GEOIP_UPDATE_DAY`	GeoIP Weekly Update Day (0=Mon, 6=Sun)	integer	`1`
`GEOIP_UPDATE_HOUR`	GeoIP Weekly Update Hour (0-23)	integer	`2`

Game Settings

Configuration	Description	Type	Default
`ENABLE_RX` (`ENABLE_OSU_RX`)	Enable RX mod statistics	boolean	`false`
`ENABLE_AP` (`ENABLE_OSU_AP`)	Enable AP mod statistics	boolean	`false`
`ENABLE_SUPPORTER_FOR_ALL_USERS`	Enable supporter status for all new users	boolean	`false`
`ENABLE_ALL_BEATMAP_LEADERBOARD`	Enable leaderboards for all beatmaps	boolean	`false`
`ENABLE_ALL_BEATMAP_PP`	Allow any beatmap to gain PP	boolean	`false`
`SEASONAL_BACKGROUNDS`	Seasonal Background URL List	array<string>	`[]`
`BEATMAP_TAG_TOP_COUNT`	Minimum votes required for tags to be shown in result list	integer	`2`
`OLD_SCORE_PROCESSING_MODE`	Old Score Processing Mode strict: delete all related scores, pp, stats, replays normal: delete pp and leaderboard scores	enum(strict, normal)	`normal`
`SCORING_MODE`	Scoring Mode: standardised or classic	enum(standardised, classic)	`standardised`

Performance Calculation Settings

Configure performance calculator and its parameters.

If CALCULATOR starts with -, the server will try to load the calculator implementation from the plugin corresponding to the id after it. If CALCULATOR does not contain ., it is considered a built-in calculator name. Currently, there are two built-in calculators: performance_server and rosu. Otherwise, the server will try to load the calculator implementation from the module path specified by CALCULATOR.

osu-performance-server (Default)

bash

CALCULATOR="performance_server"
CALCULATOR_CONFIG='{
    "server_url": "http://localhost:5225"
}'

rosu-pp-py

bash

CALCULATOR="rosu"
CALCULATOR_CONFIG='{}'

Configuration	Description	Type	Default
`CALCULATOR`	Performance Calculator	string	`performance_server`
`CALCULATOR_CONFIG`	Performance Calculator Config (JSON format), see above for details	object<string, unknown>	`{ "server_url": "http://localhost:5225" }`
`FALLBACK_NO_CALCULATOR_PP`	Use simplified pp calculation as fallback when calculator doesn't support a mode	boolean	`false`

Cache Settings

Configuration	Description	Type	Default
`ENABLE_BEATMAP_PRELOAD`	Enable Beatmap Cache Preload	boolean	`true`
`BEATMAP_CACHE_EXPIRE_HOURS`	Beatmap Cache Expiration (Hours)	integer	`24`
`BEATMAPSET_CACHE_EXPIRE_SECONDS`	Beatmapset Cache Expiration (Seconds)	integer	`3600`
`ENABLE_RANKING_CACHE`	Enable Leaderboard Cache	boolean	`true`
`RANKING_CACHE_EXPIRE_MINUTES`	Leaderboard Cache Expiration (Minutes)	integer	`10`
`RANKING_CACHE_REFRESH_INTERVAL_MINUTES`	Leaderboard Cache Refresh Interval (Minutes)	integer	`10`
`RANKING_CACHE_MAX_PAGES`	Max Cached Pages	integer	`20`
`RANKING_CACHE_TOP_COUNTRIES`	Cache Top N Country Leaderboards	integer	`20`
`ENABLE_USER_CACHE_PRELOAD`	Enable User Cache Preload	boolean	`true`
`USER_CACHE_EXPIRE_SECONDS`	User Cache Expiration (Seconds)	integer	`300`
`USER_SCORES_CACHE_EXPIRE_SECONDS`	User Scores Cache Expiration (Seconds)	integer	`60`
`USER_BEATMAPSETS_CACHE_EXPIRE_SECONDS`	User Beatmapsets Cache Expiration (Seconds)	integer	`600`
`USER_CACHE_MAX_PRELOAD_USERS`	Max Preloaded Users	integer	`200`

Asset Proxy Settings

Configuration	Description	Type	Default
`ENABLE_ASSET_PROXY`	Enable Asset Proxy	boolean	`false`
`CUSTOM_ASSET_DOMAIN`	Custom Asset Domain	string	`g0v0.top`
`ASSET_PROXY_PREFIX`	Custom prefix for assets.ppy.sh	string	`assets-ppy`
`AVATAR_PROXY_PREFIX`	Custom prefix for a.ppy.sh	string	`a-ppy`
`BEATMAP_PROXY_PREFIX`	Custom prefix for b.ppy.sh	string	`b-ppy`

Beatmap Sync Settings

Configuration	Description	Type	Default
`ENABLE_AUTO_BEATMAP_SYNC`	Enable Auto Beatmap Sync	boolean	`false`
`BEATMAP_SYNC_INTERVAL_MINUTES`	Auto Beatmap Sync Interval (Minutes)	integer	`60`

Anti-Cheat Settings

Configuration	Description	Type	Default
`BANNED_NAME`	Banned Username List	array<string>	`[ "mrekk", "vaxei", "btmc", "cookiezi", "peppy", "saragi", "chocomint" ]`
`ALLOW_DELETE_SCORES`	Allow users to delete their own scores	boolean	`false`
`CHECK_RULESET_VERSION`	Check Custom Ruleset Version	boolean	`true`
`CHECK_CLIENT_VERSION`	Check Client Version	boolean	`true`
`CLIENT_VERSION_URLS`	Client Version List URLs, see https://github.com/GooGuTeam/g0v0-client-versions to add your own client	array<string>	`[ "https://raw.githubusercontent.com/GooGuTeam/g0v0-client-versions/main/version_list.json" ]`

Storage Service Settings

Used for storing replay files, avatars, etc.

Local Storage (Recommended for Development)

Local storage saves files in the server's local file system, suitable for development and small-scale deployment.

bash

STORAGE_SERVICE="local"
STORAGE_SETTINGS='{"local_storage_path": "./storage"}'

Cloudflare R2 Storage (Recommended for Production)

bash

STORAGE_SERVICE="r2"
STORAGE_SETTINGS='{
  "r2_account_id": "your_cloudflare_account_id",
  "r2_access_key_id": "your_r2_access_key_id",
  "r2_secret_access_key": "your_r2_secret_access_key",
  "r2_bucket_name": "your_bucket_name",
  "r2_public_url_base": "https://your-custom-domain.com"
}'

AWS S3 Storage

bash

STORAGE_SERVICE="s3"
STORAGE_SETTINGS='{
  "s3_access_key_id": "your_aws_access_key_id",
  "s3_secret_access_key": "your_aws_secret_access_key",
  "s3_bucket_name": "your_s3_bucket_name",
  "s3_region_name": "us-east-1",
  "s3_public_url_base": "https://your-custom-domain.com"
}'

Configuration	Description	Type	Default
`STORAGE_SERVICE`	Storage Service Type: local, r2, s3	enum(local, r2, s3)	`local`
`STORAGE_SETTINGS`	Storage Service Configuration (JSON)	LocalStorageSettings \| CloudflareR2Settings \| AWSS3StorageSettings	`{ "local_storage_path": "./storage" }`

Plugin Settings

Configuration	Description	Type	Default
`PLUGIN_DIRS`	Plugin Directory List	array<string>	`[ "./plugins" ]`
`DISABLED_PLUGINS`	Disabled Plugin List	array<string>	`[]`

Configurations ​

Database Settings

JWT Settings

OAuth Settings

Server Settings

Fetcher Settings

Log Settings

Verification Service Settings

Email Service Settings

smtp (Default) ​

Monitoring Settings

GeoIP Settings

Game Settings

Performance Calculation Settings

osu-performance-server (Default) ​

rosu-pp-py ​

Cache Settings

Asset Proxy Settings

Beatmap Sync Settings

Anti-Cheat Settings

Storage Service Settings

Local Storage (Recommended for Development) ​

Cloudflare R2 Storage (Recommended for Production) ​

AWS S3 Storage ​

Plugin Settings

Configurations

smtp (Default)

osu-performance-server (Default)

rosu-pp-py

Local Storage (Recommended for Development)

Cloudflare R2 Storage (Recommended for Production)

AWS S3 Storage