Skip to main content

Guide

You will start an osu! development server locally in minutes.

Install Rust​

linux or wsl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

windows guide:

https://www.rust-lang.org/learn/get-started

Clone from github​

git clone https://github.com/Pure-Peace/peace
cd peace

Prepare startup​

1. A Database​

info

Peace needs a database to store data such as user accounts, beatmaps, and scores.

There are currently three databases to choose from:

After choosing and installing a database, you need to create a database:

  1. Log into PostgreSQL:
psql -U <username>
  1. Create database:
CREATE DATABASE peace;
note

Now, we can initialize the database with db-peace-migrate, which will create the table structure and some basic data:

cargo run --bin db-peace-migrate up -u <postgresql|mysql|sqlite>://<username>:<password>@<address>:<port>/peace

PostgreSQL example:

cargo run --bin db-peace-migrate up -u postgresql://postgres:123456@localhost:5432/peace

SQLite example:

# We need create an empty `peace.db` file first like:
vim peace.db
cargo run --bin db-peace-migrate up -u sqlite://peace.db
tip

If you want to clear the test data, you can use the db-peace-migrate down subcommand, or delete the database directly DROP DATABASE peace;.

If you changed your database structure, generate new database entities with:

cargo run --bin db-cli generate entity -u postgresql://postgres:123456@localhost:5432/peace -o core/db/src/peace/entity

1-1. Create a test user​

After setting up the database, we need to create a test user, and we can use this account to log in to osu!

cargo run --bin db-peace-cli create-user -u postgresql://postgres:123456@localhost:5432/peace --username test --raw-password test --email [email protected]

2. Generate test ssl certificate​

info

The osu! client will use https to connect to the server, so we need to prepare some ssl certificates before starting.

Generate cert with openssl
./ext/self_signed_certs/generate.sh

This will generate cert.cer and key.pem in the current directory.

2-1. Install ssl certificate (optional)​

If you want to start osu! on your local machine and connect to the peace server, you need to install this certificate -> cert.cer.

Windows guide: installing-a-trusted-root-certificate (or double-click cert.cer, then install the certificate to the Trusted Root Certification Authorities store)

3. Set hosts​

info

We need to set some hosts for local machine, this is to be able to use osu! -devserver flag to connect to the local development server.

Edit hosts file

linux or wsl
sudo vim /etc/hosts
windows
# Press `CTRL + R` and run:
notepad C:\Windows\System32\drivers\etc\hosts

Add contents

hosts
# Add
127.0.0.1 osu.peace.local
127.0.0.1 c.peace.local
127.0.0.1 a.peace.local
127.0.0.1 peace.local
127.0.0.1 ce.peace.local
127.0.0.1 c1.peace.local
127.0.0.1 c2.peace.local
127.0.0.1 c3.peace.local
127.0.0.1 c4.peace.local
127.0.0.1 c5.peace.local
127.0.0.1 c6.peace.local
127.0.0.1 s.peace.local
127.0.0.1 i.peace.local

4. Create a shortcut to osu!.exe​

Finally, we need to create a shortcut to osu!.exe and set the target to:

<your osu path>\osu!.exe -devserver peace.local

Once we are ready, we proceed to start the local server.

Startup​

PEACE is a development framework that offers flexible service combinations, so you can choose how to run the services:

  1. Multi-service deployment: can be deployed in a distributed environment, but requires starting multiple services
  2. Standalone instance: lightweight and can be played on a single machine

1. Multi-service deployment​

Choosing this deployment method requires running multiple services, which can be distributed across different computers and networks.

1. Install protoc - The Protocol Buffer Compiler​

info

The multi-service deployment of Peace is a distributed architecture that consists of multiple services. These services communicate with each other using gRPC, so it requires the installation of protoc compiler to compile .proto files.

The easiest way to install protoc is to download the latest release zip file from github.com/google/protobuf/releases, extract it, and then add the directory containing the binary files to your environment variable.

Linux example
curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v23.4/protoc-23.4-linux-x86_64.zip
unzip protoc-23.4-linux-x86_64.zip -d $HOME/.local
export PATH="$PATH:$HOME/.local/bin"
protoc --version
Windows
https://github.com/protocolbuffers/protobuf/releases/download/v23.4/protoc-23.4-win64.zip
note

Peace only supports protoc v3.14 and above, so please make sure to check the version of protoc you have installed using protoc --version.

Reference links:

2. Start PEACE gateway service​

info

The gateway is a stateless http(s) service, it will directly receive and process requests from osu! clients, you can customize it and specify different processing functions for different uris.

Start gateway server
cargo run --bin gateway-server -- --tls --ssl-cert=./cert.cer --ssl-key=./key.pem --admin-endpoints --bancho-uri http://127.0.0.1:5010 --bancho-state-uri http://127.0.0.1:5011 --chat-uri http://127.0.0.1:5012 --bancho-lazy-connect --bancho-state-lazy-connect --chat-lazy-connect

Now we can see some information, which means the startup is successful:

    ____  _________   ____________                      _           __
   / __ \/ ____/   | / ____/ ____/  ____  _________    (_)__  _____/ /_
  / /_/ / __/ / /| |/ /   / __/    / __ \/ ___/ __ \  / / _ \/ ___/ __/
 / ____/ /___/ ___ / /___/ /___   / /_/ / /  / /_/ / / /  __/ /__/ /_
/_/   /_____/_/  |_\____/_____/  / .___/_/   \____/_/ /\___/\___/\__/
                                /_/              /___/


>> PEACE PROJECT @ 2023
>> Running gateway-server v0.1.0
  | authors: Pure-Peace <[email protected]>
  | git repository: https://github.com/pure-peace/peace
  | docs website: https://peace.osu.icu/

>> Log level: Info (debug_mode: false)
>> Runtime: single thread
2023-07-24T15:16:39.774912Z  INFO peace_services::rpc_config: [Config] bancho gRPC service endpoint: http://127.0.0.1:5010
2023-07-24T15:16:39.775283Z  INFO peace_services::rpc_config: [Config] bancho_state gRPC service endpoint: http://127.0.0.1:5011
2023-07-24T15:16:39.775368Z  INFO peace_services::rpc_config: [Config] chat gRPC service endpoint: http://127.0.0.1:5012


    ____  _________   ____________               _
   / __ \/ ____/   | / ____/ ____/  ____ _____  (_)
  / /_/ / __/ / /| |/ /   / __/    / __ `/ __ \/ /
 / ____/ /___/ ___ / /___/ /___   / /_/ / /_/ / /
/_/   /_____/_/  |_\____/_____/   \__,_/ .___/_/
                                      /_/

>> Runs on framework peace_api v0.1.0
>> Starting service...
2023-07-24T15:16:39.777661Z  INFO peace_api::components::http: >> [Swagger UI]: https://127.0.0.1:443/swagger-ui
2023-07-24T15:16:39.777719Z  INFO peace_api::components::http: >> [openapi.json]: https://127.0.0.1:443/api-doc/openapi.json
2023-07-24T15:16:39.777919Z  INFO peace_api::components::http: >> [HTTP SERVER] listening on: http://127.0.0.1:8000
2023-07-24T15:16:39.779927Z  INFO peace_api::components::http::tls: >> [HTTPS SERVER] listening on: https://127.0.0.1:443
tip

Now we can access swagger ui via https://127.0.0.1:443/swagger-ui/.

After setting --log-env-filter=tower_http=debug, the server will print information when receiving a request.

Since we passed in a --admin-endpoints flags, there are some APIs available to the administrator (such as dynamically changing the log levels, etc.).

By default, the server will try to connect to the bancho service when it starts, passing --bancho-lazy-connect flags will make the server not connect to bancho at startup.

caution

In the production environment, please do not directly expose the service with the administrator api, or pass --admin-token <ADMIN_TOKEN> to set a token for the administrator api.

View all available flags:

cargo run --bin gateway-server -- --help
tip

If you want to allow friends in the LAN to log in to your server, you can use the parameter --https-addr 0.0.0.0:443 to start the service, and then let other users install the certificate on their computers and set up hosts and create shortcuts (repeat previous steps 2-1, 3, 4).

3. Start PEACE bancho state service​

info

The bancho-state is a stateful gRPC service that provides the ability to store bancho server state, user sessions, bancho packets in memory, and provide rpc resources to other services.

In fact, bancho-state should be considered as the state singleton of bancho. We can deploy multiple bancho services in different geographical locations, and connect them to the same bancho-state service through the intranet to complete the distributed deployment and improve the user's network experience.

Moreover, the server design of data and logic separation allows us to modify the logic of the game server at any time without causing loss of user sessions, multiplayer games, and data packets, and does not require a real "restart" of the entire server.

Start bancho state server
cargo run --bin bancho-state-server -- --rpc-reflection --rpc-admin-endpoints --bancho-state-snapshot --bancho-state-load-snapshot

Now we can see some information, which means the startup is successful:

    ____  _________   ____________                      _           __
   / __ \/ ____/   | / ____/ ____/  ____  _________    (_)__  _____/ /_
  / /_/ / __/ / /| |/ /   / __/    / __ \/ ___/ __ \  / / _ \/ ___/ __/
 / ____/ /___/ ___ / /___/ /___   / /_/ / /  / /_/ / / /  __/ /__/ /_
/_/   /_____/_/  |_\____/_____/  / .___/_/   \____/_/ /\___/\___/\__/
                                /_/              /___/


>> PEACE PROJECT @ 2023
>> Running bancho-state-server v0.1.0
  | authors: Pure-Peace <[email protected]>
  | git repository: https://github.com/pure-peace/peace
  | docs website: https://peace.osu.icu/

>> Log level: Info (debug_mode: false)
>> Runtime: single thread
2023-07-24T15:17:54.155222Z  INFO peace_services::signature::services: initializing Signature service...
2023-07-24T15:17:54.155685Z  INFO peace_services::signature::services: Signature service init successful, type: "Local"
2023-07-24T15:17:54.155786Z  INFO peace_services::bancho_state::services::bancho_state: [BanchoStateSnapshot] Snapshot file not found, path: "./.snapshots/bancho_state.snapshot"
2023-07-24T15:17:54.155910Z  INFO bancho_state::background_tasks::user_sessions_recycling: Service started! (deactive=180s, sleep=180s)
2023-07-24T15:17:54.156004Z  INFO bancho_state::background_tasks::notify_messages_recycling: Service started! (sleep=300s)


    ____  _________   ____________
   / __ \/ ____/   | / ____/ ____/  _________  _____
  / /_/ / __/ / /| |/ /   / __/    / ___/ __ \/ ___/
 / ____/ /___/ ___ / /___/ /___   / /  / /_/ / /__
/_/   /_____/_/  |_\____/_____/  /_/  / .___/\___/
                                     /_/

>> Runs on framework peace_rpc v0.1.0
>> Starting service...
2023-07-24T15:17:54.157865Z  INFO peace_rpc::components::server: >> [gRPC SERVER] listening on: http://127.0.0.1:5011

tip

Since --grpc-reflection flags are passed in, the server will provide gRPC reflection services, you can get a list of rpc functions provided by this service through network requests or debugging tools such as postman, which is convenient for debugging and calling services.

The --rpc-admin-endpoints flags will provide a set of RPC functions available to administrators (such as dynamically changing log levels, etc.).

The --bancho-state-snapshot parameter allows the Bancho state service to store the service instance in memory to the hard disk when it terminates.

By passing the --bancho-state-load-snapshot parameter at startup, the service can be restored to the state it was in when it was last closed, without losing user sessions, and users will not feel that the service has restarted.

It is worth noting that the --bancho-state-snapshot-expired-secs parameter can control the expiration time (in seconds) of the snapshot. If the snapshot expires, it will not be loaded.

caution

In the production environment, please do not directly expose the gRPC service, and pass --rpc-admin-token <ADMIN_TOKEN> to set a token for the administrator rpc functions.

note

The bancho-state service requires the use of the signature service to distribute ED25519 signatures as part of tokens for successfully logged-in users to ensure security. Therefore, when bancho-state is launched, it will attempt to connect to a remote gRPC channel for the signature service. If it cannot connect, an internal signature service will be started within the bancho-state service, and an ED25519 private key will be generated for signing.

  • Specify the URI for the signature service: --signature-uri (default is http://127.0.0.1:5014)

View all available flags:

cargo run --bin bancho-state-server -- --help

4. Start PEACE bancho service​

info

The bancho is a stateless gRPC service that contains the logic of the bancho server. You can customize the logic of the server according to your needs.

It requires a bancho-state and chat services to store and process server state.

Start bancho service
cargo run --bin bancho-server -- --peace-db-url sqlite://peace.db --bancho-state-uri http://127.0.0.1:5011 --chat-uri http://127.0.0.1:5012 --bancho-state-lazy-connect --chat-lazy-connect --rpc-reflection --rpc-admin-endpoints
note

You should set --peace-db-url to your own database url! We have talked about it in the previous steps.

Now we can see some information, which means the startup is successful:

    ____  _________   ____________                      _           __
   / __ \/ ____/   | / ____/ ____/  ____  _________    (_)__  _____/ /_
  / /_/ / __/ / /| |/ /   / __/    / __ \/ ___/ __ \  / / _ \/ ___/ __/
 / ____/ /___/ ___ / /___/ /___   / /_/ / /  / /_/ / / /  __/ /__/ /_
/_/   /_____/_/  |_\____/_____/  / .___/_/   \____/_/ /\___/\___/\__/
                                /_/              /___/


>> PEACE PROJECT @ 2023
>> Running bancho-server v0.1.0
  | authors: Pure-Peace <[email protected]>
  | git repository: https://github.com/pure-peace/peace
  | docs website: https://peace.osu.icu/

>> Log level: Info (debug_mode: false)
>> Runtime: single thread
2023-07-24T15:18:21.908580Z  INFO peace_services::rpc_config: [Config] bancho_state gRPC service endpoint: http://127.0.0.1:5011
2023-07-24T15:18:21.908933Z  INFO peace_services::rpc_config: [Config] chat gRPC service endpoint: http://127.0.0.1:5012
2023-07-24T15:18:21.909031Z  INFO peace_services::geoip::services: initializing Geoip service...
2023-07-24T15:18:21.909406Z  INFO peace_services::geoip::services: Geoip service init successful, type: "Local"
2023-07-24T15:18:21.909543Z  INFO bancho::background_tasks::password_caches_recycling: Service started! (deactive=86400s, sleep=43200s)


    ____  _________   ____________
   / __ \/ ____/   | / ____/ ____/  _________  _____
  / /_/ / __/ / /| |/ /   / __/    / ___/ __ \/ ___/
 / ____/ /___/ ___ / /___/ /___   / /  / /_/ / /__
/_/   /_____/_/  |_\____/_____/  /_/  / .___/\___/
                                     /_/

>> Runs on framework peace_rpc v0.1.0
>> Starting service...
2023-07-24T15:18:21.912105Z  INFO peace_rpc::components::server: >> [gRPC SERVER] listening on: http://127.0.0.1:5010
tip

Since --grpc-reflection flags are passed in, the server will provide gRPC reflection services, you can get a list of rpc functions provided by this service through network requests or debugging tools such as postman, which is convenient for debugging and calling services.

The --rpc-admin-endpoints flags will provide a set of RPC functions available to administrators (such as dynamically changing log levels, etc.).

By default, the server will try to connect to the bancho-state and chat services when it starts, passing --<service>-lazy-connect flags will make the server not connect to <service> at startup.

caution

In the production environment, please do not directly expose the gRPC service, and pass --rpc-admin-token <ADMIN_TOKEN> to set a token for the administrator rpc functions.

View all available flags:

cargo run --bin bancho-state-server -- --help

5. Start PEACE chat service​

info

chat is a stateful gRPC service that currently includes chat channels and message queues for bancho users, and can be used to send messages directly to users of bancho, lazer, and web clients through the API exposed by this service.

Start chat service
cargo run --bin chat-server -- --peace-db-url sqlite://peace.db --rpc-reflection --rpc-admin-endpoints --chat-snapshot --chat-load-snapshot

Now we can see some information, which means the startup is successful:

    ____  _________   ____________                      _           __
   / __ \/ ____/   | / ____/ ____/  ____  _________    (_)__  _____/ /_
  / /_/ / __/ / /| |/ /   / __/    / __ \/ ___/ __ \  / / _ \/ ___/ __/
 / ____/ /___/ ___ / /___/ /___   / /_/ / /  / /_/ / / /  __/ /__/ /_
/_/   /_____/_/  |_\____/_____/  / .___/_/   \____/_/ /\___/\___/\__/
                                /_/              /___/


>> PEACE PROJECT @ 2023
>> Running chat-server v0.1.0
  | authors: Pure-Peace <[email protected]>
  | git repository: https://github.com/pure-peace/peace
  | docs website: https://peace.osu.icu/

>> Log level: Info (debug_mode: false)
>> Runtime: single thread
2023-07-24T15:19:16.783822Z  INFO peace_services::chat::services::chat: [ChatSnapshot] Snapshot file not found, path: "./.snapshots/chat.snapshot"
2023-07-24T15:19:16.784230Z  INFO chat::channel::initialize_public_channels: Public channels successfully initialized.
2023-07-24T15:19:16.784312Z  INFO chat::background_tasks::user_sessions_recycling: Service started! (deactive=180s, sleep=180s)
2023-07-24T15:19:16.784403Z  INFO chat::background_tasks::notify_messages_recycling: Service started! (sleep=300s)
2023-07-24T15:19:16.784460Z  INFO chat::background_tasks::channel_messages_recycling: Service started! (sleep=300s)


    ____  _________   ____________
   / __ \/ ____/   | / ____/ ____/  _________  _____
  / /_/ / __/ / /| |/ /   / __/    / ___/ __ \/ ___/
 / ____/ /___/ ___ / /___/ /___   / /  / /_/ / /__
/_/   /_____/_/  |_\____/_____/  /_/  / .___/\___/
                                     /_/

>> Runs on framework peace_rpc v0.1.0
>> Starting service...
2023-07-24T15:19:16.786971Z  INFO peace_rpc::components::server: >> [gRPC SERVER] listening on: http://127.0.0.1:5012
tip

The --chat-snapshot parameter allows the Chat service to store the service instance in memory to the hard disk when it terminates.

By passing the --chat-load-snapshot parameter at startup, the service can be restored to the state it was in when it was last closed, without losing user sessions, and users will not feel that the service has restarted.

It is worth noting that the --chat-snapshot-expired-secs parameter can control the expiration time (in seconds) of the snapshot. If the snapshot expires, it will not be loaded.

View all available flags:

cargo run --bin chat-server -- --help

2. Standalone Bancho instance​

If you wish to run a standalone instance, please refer to the following commands:

Start bancho standalone server
cargo run --bin bancho-standalone-server -- --admin-endpoints --tls --ssl-cert=./cert.cer --ssl-key=./key.pem --peace-db-url sqlite://peace.db --chat-snapshot --chat-load-snapshot --bancho-state-snapshot --bancho-state-load-snapshot

Now we can see some information, which means the startup is successful:


    ____  _________   ____________                      _           __
   / __ \/ ____/   | / ____/ ____/  ____  _________    (_)__  _____/ /_
  / /_/ / __/ / /| |/ /   / __/    / __ \/ ___/ __ \  / / _ \/ ___/ __/
 / ____/ /___/ ___ / /___/ /___   / /_/ / /  / /_/ / / /  __/ /__/ /_
/_/   /_____/_/  |_\____/_____/  / .___/_/   \____/_/ /\___/\___/\__/
                                /_/              /___/


>> PEACE PROJECT @ 2023
>> Running bancho-standalone v0.1.0
  | authors: Pure-Peace <[email protected]>
  | git repository: https://github.com/pure-peace/peace
  | docs website: https://peace.osu.icu/

>> Log level: Info (debug_mode: false)
>> Runtime: single thread
2023-08-03T17:59:22.091560Z  INFO core_signature::signature: initializing Signature service...
2023-08-03T17:59:22.092333Z  INFO core_signature::signature: Signature service init successful, type: "Local"
2023-08-03T17:59:22.092460Z  INFO core_bancho_state::services::bancho_state: [BanchoStateSnapshot] Snapshot file not found, path: "./.snapshots/bancho_state.snapshot"
2023-08-03T17:59:22.092585Z  INFO core_geoip::geoip: initializing Geoip service...
2023-08-03T17:59:22.093154Z  INFO core_geoip::geoip: Geoip service init successful, type: "Local"
2023-08-03T17:59:22.093250Z  INFO core_chat::services::chat: [ChatSnapshot] Snapshot file not found, path: "./.snapshots/chat.snapshot"
2023-08-03T17:59:22.093540Z  INFO chat::channel::initialize_public_channels: Public channels successfully initialized.
2023-08-03T17:59:22.093633Z  INFO chat::background_tasks::user_sessions_recycling: Service started! (deactive=180s, sleep=180s)
2023-08-03T17:59:22.093711Z  INFO chat::background_tasks::notify_messages_recycling: Service started! (sleep=300s)
2023-08-03T17:59:22.093765Z  INFO chat::background_tasks::channel_messages_recycling: Service started! (sleep=300s)
2023-08-03T17:59:22.093816Z  INFO bancho::background_tasks::password_caches_recycling: Service started! (deactive=86400s, sleep=43200s)
2023-08-03T17:59:22.093889Z  INFO bancho_state::background_tasks::user_sessions_recycling: Service started! (deactive=180s, sleep=180s)
2023-08-03T17:59:22.093952Z  INFO bancho_state::background_tasks::notify_messages_recycling: Service started! (sleep=300s)


    ____  _________   ____________               _
   / __ \/ ____/   | / ____/ ____/  ____ _____  (_)
  / /_/ / __/ / /| |/ /   / __/    / __ `/ __ \/ /
 / ____/ /___/ ___ / /___/ /___   / /_/ / /_/ / /
/_/   /_____/_/  |_\____/_____/   \__,_/ .___/_/
                                      /_/

>> Runs on framework peace_api v0.1.0
>> Starting service...
2023-08-03T17:59:22.096400Z  INFO peace_api::components::http: >> [Swagger UI]: https://127.0.0.1:443/swagger-ui
2023-08-03T17:59:22.096463Z  INFO peace_api::components::http: >> [openapi.json]: https://127.0.0.1:443/api-doc/openapi.json
2023-08-03T17:59:22.096664Z  INFO peace_api::components::http: >> [HTTP SERVER] listening on: http://127.0.0.1:8000
2023-08-03T17:59:22.098853Z  INFO peace_api::components::http::tls: >> [HTTPS SERVER] listening on: https://127.0.0.1:443

View all available flags:

cargo run --bin bancho-standalone-server -- --help
tip

If you want to allow friends in the LAN to log in to your server, you can use the parameter --https-addr 0.0.0.0:443 to start the service, and then let other users install the certificate on their computers and set up hosts and create shortcuts (repeat previous steps 2-1, 3, 4).

Run osu! through the created shortcut​

You have started the PEACE development server locally and can connect via the osu! client, congratulations!