Skip to content

installation.mdx

Latest commit

聽

History

History
241 lines (158 loc) 路 7.79 KB

installation.mdx

File metadata and controls

241 lines (158 loc) 路 7.79 KB
Raw
title Installation - Production Setup
sidebar
order
2

This section will help you set up Sunrise server on your local environment.

We are going to set up "Production" ready environment, for this we are going to use Solar System Orchestrator.

Solar System is an orchestration tool that simplifies the deployment and management of Sunrise and its related components using Docker. It provides easy setup and configuration for server administrators with versioning support.

If you are more interested in development setup, please refer to the Contributing section.

:::tip 馃憖 We recommend watching the installation video guide for a step-by-step walkthrough.

<iframe src="https://www.youtube.com/embed/ukVc4anmtIs" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen ></iframe>

From it you will learn how to set up Solar-System and how to customize it for your branding. :::

Prerequisites

Before you start, make sure you have the following installed on your machine:

  • Docker: For running the server and other components.
  • Git: For cloning the repositories.
  • Text Editor: Optional, but recommended. But you can use any text editor you like.

Docker will do the heavy lifting for you, so you don't need to worry about installing any technologies like Redis, MySQL, Grafana, etc.

Setting up the Server

1. Cloning the Repositories

First, we need to clone the Solar System repository with submodules. Open your terminal and run the following commands:

git clone --recursive https://github.com/SunriseCommunity/Solar-System.git
cd Solar-System

Or if you've already cloned without submodules:

git submodule update --init --recursive --remote

2. Configuring Sunrise

Solar System uses a single .env file (for infrastructure + ports + domains) and a single Sunrise config file.

Create copies of the example configuration files:

cp .env.example .env
cp Sunrise.Config.Production.json.example Sunrise.Config.Production.json

Fill in the required parameters in both files.

:::tip If you are on Windows and don't have cp, you can just copy/rename the files in File Explorer. :::

:::caution Make sure to edit WEB_DOMAIN= in .env to your actual domain that you plan to host on (for local setups, sunrise.local is a common choice). :::

:::tip You can customize the configuration files to match your requirements. For example, in Sunrise.Config.Production.json you can change the bot username:

"Bot": {
  "Username": "Librarian Bot",
  ...
}

:::

3. Generate API keys

Sunrise needs a token secret for API requests, and Observatory uses an API key so Sunrise can request it without internal rate limits.

Generate the token secret for Sunrise API requests:

chmod +x lib/scripts/generate-api-sunrise-key.sh
./lib/scripts/generate-api-sunrise-key.sh

Generate the Observatory API key:

chmod +x lib/scripts/generate-observatory-api-key.sh
./lib/scripts/generate-observatory-api-key.sh

:::tip You may be prompted to run multiple scripts during setup. If you are using Windows, use the .bat equivalent scripts located in the same folder. :::

:::note If you want Sunrise to use the Bancho API (highly recommended), fill OBSERVATORY_BANCHO_CLIENT_ID and OBSERVATORY_BANCHO_CLIENT_SECRET in .env.

If you don't know how to get these values, follow the instructions in the FAQ section. :::

4. Running the Server

:::caution You are going to start your server for the first time, make sure to double-check your configuration files before proceeding to avoid any issues later on.

Additionally check that you have firewall (ufw for Linux) rules set up to allow incoming traffic for and only ports 22/80/443 (for Caddy).

As we are using Docker, it is known issue that it can interfere with existing firewall rules. We recommend setting up ufw-docker to manage this. You can find the instructions in the ufw-docker repository.

We are not responsible for any misconfigurations that can lead to security issues and will not provide support for such issues, so please be careful and double-check everything before starting the server.

The best way to confirm that everything is set up correctly is to test that you can't connect to the database ports (3306 for MySQL, 6379 for Redis) from outside the server.

You can use online port checkers for this or try to connect using telnet <your IP> 3306 and telnet <your IP> 6379 from another machine. The connection should be refused. :::

Now that we have everything set up, we can run the server.

Start the stack:

chmod +x ./start.sh
./start.sh

:::tip If you are on Windows, use .\start.bat instead. :::

You can check that all containers are running with:

docker ps

Accessing the Server

To make your server accessible on the internet:

1. Configure DNS records

Make sure you have DNS records pointing the following subdomains to your server's IP address:

  • * (wildcard)
  • api
  • osu
  • a
  • c
  • assets
  • cho
  • c4
  • b
  • grafana

These subdomains are required for the server to function properly.

2. Start Caddy reverse proxy

For simplicity, we use Caddy as a reverse proxy. By default, the Caddyfile is configured to host the website, server, and Grafana. You can uncomment additional configurations in the Caddyfile if needed.

Start Caddy by running in the Solar-System directory:

sudo caddy start --envfile .env

:::caution After starting Caddy, make sure to visit grafana.* subdomain and change the default password for the admin account!

On the first login, use admin as the username and admin as the password. After that you will be prompted to change the password. :::

Now, you should be able to test connection to the server using https://cho.<your WEB_DOMAIN> in your browser.

peppy shown on cho domain

You should see the face of a beautiful mister. :) 馃帀

3. Test if the server is accessible

Connecting to the Server using osu! client

Add a launch argument -devserver <your WEB_DOMAIN> to your osu! shortcut.

For example:

-devserver <your WEB_DOMAIN>

After that, you can launch the osu! client and should be able to connect to the server.

Opening the Website using web browser

Sunset is included in Solar System and should start automatically with the stack.

By default you can access the website at https://<your WEB_DOMAIN>.

Something went wrong?

If you encounter any issues during the setup process, please check the following:

  • Make sure you have followed all the steps correctly.
  • Check the logs of the Docker containers for any errors.
  • If you are still having issues, feel free to open an issue on the Sunrise repository or ask for help in the Sunrise Discord server.

What's next?

Now that you have the server up and running, you can start exploring its features and capabilities.

Please follow the Configuration section to learn how to manage the server.

You will learn how to:

  • Update website branding (logo, colors, etc.)
  • Recieve admin privileges
  • Manage beatmaps (rank, love, derank beatmaps, etc.)
  • View player statistics
  • And more!