The following documentation is for setting up a local development environment for Corsace.
Please make sure to first fork the repository
To clone the repository, run the following command in your terminal/console:
git clone https://github.com/Corsace/Corsace
git clone -c core.symlinks=true https://github.com/Corsace/Corsace
*Use admin privileges in your console when running the command.
For your forked repository instead, you can change the github link as needed.
Note: Please ensure that your node version is 16.6.0 or higher in order to use any of the discord features in this repository.
For the curious, the project primarily uses the following technologies and versions that are installed by the above command:
- TypeORM (v0.3.11)
- Koa (v2.13.1)
- Discord.js (v14.9.0)
- Bancho.js (v0.11.3)
- Nuxt 2 (v2.16.3)
- Astro/Starlight (v0.10.0)
$USER being your system username (accessible via node’s
In a terminal, run
node, then type
process.env.USER to find out your username.
The values in your personal
config/user/$USER.json config file will be referred to as
config from now on.
You can obtain your osu! API V1 key here
You will need to create a “New OAuth Application” at the bottom of https://osu.ppy.sh/home/account/edit.
config.corsace.publicUrl + /api/login/osu/callback to the
Application Callback URLs section in the popup.
For example, if your
http://localhost:5000, then the callback URL should be
Afterwards, you will be given a
Client ID and
Client Secret which you will need to add to your config to the respective fields.
You can obtain your osu! IRC password from the same place as the osu OAuth Application at https://osu.ppy.sh/home/account/edit#irc.
If your account is a bot account, then make sure to have
botAccount set to true; otherwise, make set it to false.
There are 2 ways to setup the database, either via Docker or manually.
Via Docker (Recommended)
We are shipping a production-like
docker-compose.yml file. You can start only the database service using:
docker-compose up -d database or
npm run database.
The database will listen on
corsace being the database name, username and password.
Manual MariaDB Setup
If you do not want to use Docker, you will need to install MariaDB and create an empty database, named whatever you like.
It can be as simple as running:
mysql -u root -p
MySQL> create database <new_db_name>;
Make sure to update
config.database to reflect your choice of database name and credentials.
Seeding the Database
Seed the whole Corsace database using:
NODE_ENV=development npm run -- typeorm migration:run -d ormconfig
We use S3-compatible object storage for storing and serving mappacks, configured in
While we target Cloudflare R2, any S3 provider should work as long as they support multipart uploads and pre-signed URLs.
We use three buckets:
team-avatarsis a public bucket that stores team avatars, can be served by a CDN without authentication
mappacksis a public bucket that stores public mappacks, can be served by a CDN without authentication
mappacks-tempis a private bucket that stores private mappacks that should not have public access
Generated mappacks are first uploaded to this bucket, users are given access through pre-signed URLs.
Private mappacks are not meant to be permanently stored, a lifecycle policy should be added to that bucket to automatically delete objects after 1 day.
Mappacks that should become public get moved to the
Go to the Cloudflare R2 dashboard page. Enable your plan if you haven’t already (good luck exceeding free limits).
team-avatars buckets and enable their R2.dev subdomains, or associate a custom domain for each.
mappacks-temp bucket and add an object lifecycle rule to delete objects after 7 days (leave prefix empty).
Set hostname to
<cloudflare account id>.r2.cloudflarestorage.com, and obtain S3 credentials from https://dash.cloudflare.com/?to=/:account/r2/api-tokens. Make sure you give the token
Edit permissions instead of the default
This is the most time-consuming part of the setup. You will need the following:
Enable Developer Mode
Check the option at
User Settings > Appearance > Advanced > Developer Mode
This will allow you to right click users, roles, channels, etc to copy their IDs.
A Discord Server
Create a new Discord Server if you don’t have one already. All it needs to have is a single channel. Create a “staff” role and give it to yourself.
Right-click your server name and “Copy ID”. Paste this into
Right-click your staff role and “Copy ID”. You can either create a role for each corresponding role in the config, OR paste that role ID into the following config values to give yourself god-tier permissions.
and then into every other “staff” role in the config.
Go to https://discord.com/developers/applications and create a “New Application”.
You will need to add the “Client ID” and “Client Secret” to the config as follows:
clientId: "<Client ID>",
clientSecret: "<Client Secret>",
The client ID and secret are found in the discord application’s
Head to the OAuth2 section of the bot and add the following redirect URL:
config.corsace.publicUrl + /api/login/discord/callback
Also add a redirect URL with your bot’s specific Client ID that looks like:
Follow this link to add your bot to your server.
Head to the
Bot section of the Discord application and copy your bot token.
Paste it into
Ensure you enable the
Server Members and
Message Content intents under the Privileged Gateway Intents subsection before usage, the bot will not start otherwise, and you will be provided a
[DISALLOWED INTENTS] error.
Completely optional, and only if you really want to track your GitHub fork’s events on discord and want to utilize Corsace’s Github Webhook.
In the discord channel you want to obtain GitHub notifications from, create a webhook from
settings -> Integrations -> Create Webhook, copy its Webhook URL, and place it into your config in
Create a password and place it in
On GitHub, go to the repository’s settings, and create a new webhook. Place the following URL in:
config.corsace.publicUrl + /api/github
Set the content type to
application/json, and the secret to the password you created earlier.
We use Centrifugo for real-time notifications. You can find the documentation here.
npm run centrifugo to start the centrifugo server. It will be available at
http://localhost:8001 by default, unless you change the port in the config files.
On WSL/Windows OR if the above doesn’t work:
Download the binary from latest releases, and add it to the root folder of this project.
npm run centrifugo:local to start the centrifugo server. If you want to change the port, change the
-p flag in the respective script in
package.json, and your config file’s api URL.
For frontend web development, it’s suggested to go through the following documents in order:
For docs development, you can simply go here
For any specific backend development, you can go to their respective
Running Environment pages in
Server/Guide from the sidebar.