跳到主要内容

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

信息

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;
备注

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
提示

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

信息

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

信息

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

信息

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
备注

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

信息

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
提示

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.

警告

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
提示

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

信息

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

提示

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.

警告

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.

备注

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

信息

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
备注

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
提示

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.

警告

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

信息

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
提示

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
提示

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!