Guide
You will start an osu! development server locally in minutes.
Install Rust
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:
PostgreSQL (recommended)
Sqlite (only local servers are recommended).
After choosing and installing a database, you need to create a database:
- PostgreSQL
- MySQL
- Sqlite
- Log into PostgreSQL:
psql -U <username>
- Create database:
CREATE DATABASE peace;
- Log into MySQL:
mysql -u <username>
- Create database:
CREATE DATABASE peace;
- Create a new empty file
peace.dbin the peace project directory.
cd peace
# Create an empty `peace.db`
vim peace.db
- Work with peace (Example):
--peace-db-url sqlite://peace.db
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.
- Linux or Wsl
- Windows
./ext/self_signed_certs/generate.sh
Download and install openssl: https://slproweb.com/products/Win32OpenSSL.html
Add the directory of the
openssl.exeto the environment variablepath.
./ext/self_signed_certs/generate.bat
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
sudo vim /etc/hosts
# Press `CTRL + R` and run:
notepad C:\Windows\System32\drivers\etc\hosts
Add contents
# 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:
- Multi-service deployment: can be deployed in a distributed environment, but requires starting multiple services
- 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.
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
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:
- https://grpc.io/docs/protoc-installation/#install-pre-compiled-binaries-any-os
- https://github.com/protocolbuffers/protobuf/releases
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.
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
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.
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
signatureservice:--signature-uri(default ishttp://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.
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.
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:
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
Run osu! through the created shortcut
You have started the PEACE development server locally and can connect via the osu! client, congratulations!