Skip to content

docs: clarify setup instructions #947

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify setup instructions #947

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 67 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,23 +166,57 @@ sequenceDiagram
end
```

## Running Hyperion for testing in a development environment

## Running
First, clone this repostiory with:

```bash
git clone https://github.com/hyperion-mc/hyperion.git
```

Then enter the repository directory with:

```bash
cd hyperion
```

Then generate keys. This requires `openssl` to be installed. Note that `-days 365` specifies the the number of days until the certificate expires.

> [!WARNING]
> All private keys (`.pem` files) must be stored securely. Do not send these private keys to anyone.

```bash
openssl req -new -nodes -newkey rsa:4096 -keyout root_ca.pem -x509 -out root_ca.crt -days 365 -subj /
openssl req -nodes -newkey rsa:4096 -keyout game_private_key.pem -out game.csr -subj /
openssl x509 -req -in game.csr -CA root_ca.crt -CAkey root_ca.pem -CAcreateserial -out game.crt -days 365 -sha256 -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1")
rm game.csr
openssl req -nodes -newkey rsa:4096 -keyout proxy_private_key.pem -out proxy.csr -subj /
openssl x509 -req -in proxy.csr -CA root_ca.crt -CAkey root_ca.pem -CAcreateserial -out proxy.crt -days 365 -sha256 -extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1")
rm proxy.csr
```

Now run the game server. Note that the game server automatically starts the proxy.

```bash
cargo run --release --bin bedwars -- --ip 127.0.0.1 --root-ca-cert root_ca.crt --cert game.crt --private-key game_private_key.pem
```
Comment on lines +188 to +202
Copy link
Contributor

@dyc3 dyc3 Sep 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since these are for a dev environment, maybe it would be good to include some of these long commands in the justfile?

Copy link
Collaborator Author

@TestingPlant TestingPlant Sep 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to avoid relying on external programs like just that people usually don't have installed so that setting up Hyperion is simpler

Copy link
Contributor

@dyc3 dyc3 Sep 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not saying remove these instructions necessarily, merely providing the convenience of running a simple command.

My full opinion: installing just is not a hurdle, its a cargo install just and then wait. providing an easy way to have consistent dev environments is way more valuable than the time spent debugging differences in environments, multiplied by however many people start contributing.


You can now connect a 1.20.1 Minecraft client to the game server at port `25565`, such as through `127.0.0.1:25565` or `domain_name:25565`.

## Running Hyperion in a production environment

### Network topology

Hyperion uses one game server which runs all game-related code (e.g. physics, game events). One or more proxies can connect to the game server. Players connect to one of the proxies.

For development and testing purposes, it is okay to run one game server and one proxy on the same server. When generating keys, you will need to change the key and certificate file names used below to avoid file name conflicts.

On a production environment, the game server and each proxy should run on separate servers for performance.
On a production environment, the game server and each proxy should run on separate servers to improve performance.

### Generating keys and certificates

The connection between the game server and the proxies are encrypted through mTLS to ensure that the connection is secure and authenticate the proxies.

> [!WARNING]
> All private keys must be stored securely, and it is strongly recommended to generate the private keys on the server that will use them instead of transferring them over the Internet. Malicious proxies that have access to a private key can circumvent player authentication and can cause the game server to exhibit undefined behavior which can potentially lead to arbitrary code execution on the game server. If any private key has been compromised, redo this section to create new keys.
> All private keys (`.pem` files) must be stored securely, and it is strongly recommended to generate the private keys on the server that will use them instead of transferring them over the Internet. Do not send these private keys to anyone. Malicious proxies that have access to a private key can circumvent player authentication and can cause the game server to exhibit undefined behavior which can potentially lead to arbitrary code execution on the game server. If any private key has been compromised, redo this section to create new keys.

#### Create a private certificate authority (CA)

Expand All @@ -191,14 +225,12 @@ A server should be picked to store the certificate authority keys and will be re
On the certificate authority server, generate a key and certificate by running:

```bash
openssl req -new -nodes -newkey rsa:4096 -keyout root_ca.pem -x509 -out root_ca.crt -days 365
openssl req -new -nodes -newkey rsa:4096 -keyout root_ca.pem -x509 -out root_ca.crt -days 365 -subj /
```

OpenSSL will ask for information when running the command. All fields can be left empty.

The `-days` field specifies when the certificate will expire. It will expire in 365 days in the above command, but this can be modified as needed.

`root_ca.crt` is the root CA cert and should be copied to the game server and all proxy servers. When running the game server or the proxy, make sure to pass `--root-ca-cert root_ca.crt` as a command line flag.
`root_ca.crt` is the root CA cert and should be copied to the game server and all proxy servers.

#### Generate server keys and certificates

Expand All @@ -207,11 +239,9 @@ Follow these instructions for the game server and each proxy server. The server
On the target server, run:

```bash
openssl req -nodes -newkey rsa:4096 -keyout server_private_key.pem -out server.csr
openssl req -nodes -newkey rsa:4096 -keyout server_private_key.pem -out server.csr -subj /
```

OpenSSL will ask for information when running the command. All fields can be left empty.

Afterwards, transfer `server.csr` to the certificate authority server. On the certificate authority server, run:

```bash
Expand All @@ -227,24 +257,42 @@ Then, transfer `server.crt` to the target server.

`server.csr` and `server.crt` on the certificate authority server and `server.csr` on the target server are no longer needed and may be deleted.

`server.crt` is the target server's certificate and `server_private_key.pem` is the target server's private key. When running the game server or the proxy, make sure to pass `--cert server.crt --private-key server_private_key.pem` as a command line flag.
### With local build

#### Running the proxy

First, compile the proxy on a machine with Cargo installed:

### Without cloning
```bash
cargo build --release --bin hyperion-proxy
```

If the proxy servers are running on different targets (e.g. different CPU architectures, different OS, different libc), you will need to compile the proxy for each target.

Now, copy `target/release/hyperion-proxy` to each proxy server.

On each proxy server, run:

```bash
curl -L https://raw.githubusercontent.com/hyperion-mc/hyperion/main/docker-compose.yml | docker compose -f - up --pull always
./hyperion-proxy 0.0.0.0:25565 --server game_server_ip:35565 --root-ca-cert root_ca.crt --cert server.crt --private-key server_private_key.pem
```

### `main` branch
Replace `game_server_ip` with the IP or domain name of the game server. Note that this must match the `subjectAltName` used to generate the game server certificate above.

#### Running the game server

First, compile the game server on a machine with Cargo installed that is the same target as the game server (i.e. same CPU architecture, same OS, same libc). This can also be compiled directly on the game server.

```bash
docker compose up --pull always
cargo build --release --bin bedwars
```

### With local build (for development)
Now, copy `target/release/bedwars` to the game server.

On the game server, run:

```bash
docker compose up --build
./bedwars --root-ca-cert root_ca.crt --cert server.crt --private-key server_private_key.pem
```

## Features
Expand Down
Loading