pppy/osu-notification-server repository overview

⁠osu!notification server

⁠Requirements

• node 10+

⁠Setup

Either set up environment variables or copy/symlink following files from osu!web project to this project's root directory:

• oauth-public.key (if not using environment variable; located in storage in osu!web)
• .env

Configurations:

• Only through environment variable:
  • WEBSOCKET_BASEDIR: set if you need to explicitly specify path to the files above.
  • APP_ENV: defaults to development. The .env.${APP_ENV} file will be loaded first before .env.
• Either environment variable or in .env files:
  • Refer to src/config.ts.

Lastly, osu!web needs to be configured to use redis-based session.

⁠Run

1. yarn
2. yarn build
3. yarn serve

⁠Development

Watch and rebuild automatically with yarn watch. The server doesn't auto-restart though.

⁠Code linting (style check)

Run yarn lint --fix and additionally do manual fixes if needed.

⁠Testing

To be added.

⁠Docker

To build:

# repository should be username/repository when using docker hub for convenient push
docker build --tag <repository>:<tag> .

To run, the following items need to be passed to the container:

• environment variables: either directly using docker command or bind mount to /app/.env
• oauth public key: bind mount to /app/oauth-public.key
• listening port: for the host

Make sure the files are globally readable as the container process runs as limited privilege user

Example:

docker run \
  --rm \
  --publish 2345:2345 \
  -v /path/to/.env:/app/.env \
  -v /path/to/oauth-public.key:/app/oauth-public.key \
  -e NOTIFICATION_REDIS_HOST=redis \
  ppy/osu-notification-server:latest

⁠Deployment considerations

⁠Multiple cores

The process is single-threaded. Launch multiple containers to handle more connections.

⁠Connection limit

Each process is known to be able to handle over 3000 connections. Make sure to increase file descriptor limit for the container process (--ulimit nofile=10000 option in docker) otherwise it won't be able to accept enough connections.

⁠Process monitoring

There's currently no error handling. Any errors will stop the process. Make sure to always restart on exit.

⁠Reverse proxy

The server is supposed to be deployed behind a reverse proxy like nginx. Following is the proxying setting usually used for nginx:

proxy_pass http://notification-server;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_buffering off;
proxy_redirect off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
tcp_nodelay on;

Especially make sure to not forward X-Forwarded-For from external source because it's used for identifying connecting IP address.