Skip to content



Heroku is recommended just for prototyping. You can deploy the colyseus-examples project on it by hitting this button:


Important: Make sure to set the environment variable NPM_CONFIG_PRODUCTION=false in order to use dev-dependencies in your deployment, such as ts-node, ts-node-dev, etc.

It's recommended to use pm2 and nginx in your production environment.


Install pm2 in your environment.

npm install -g pm2

Then start your server using it:

pm2 start your-server.js

Nginx configuration

server {
    listen 80;

    location / {
        proxy_pass http://localhost:2567;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;

Nginx configuration with SSL

It's recommended to acquire your certificate from LetsEncrypt.

server {
    listen 80;
    listen 443 ssl;

    ssl_certificate /path/to/your/cert.crt;
    ssl_certificate_key /path/to/your/cert.key;

    location / {
        proxy_pass http://localhost:2567;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;


Here's how to use Apache as a proxy to your Node.js Colyseus app. (Thanks tomkleine!)

Install the required Apache modules:

sudo a2enmod ssl
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_html
sudo a2enmod proxy_wstunnel

Virtual host configuration:

<VirtualHost *:80>

    # Redirect all requests received from port 80 to the HTTPS variant (force ssl)
    RewriteEngine On
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]


<VirtualHost *:443>

    # enable SSL
    SSLEngine On
    SSLCertificateFile          /PATH/TO/CERT/FILE
    SSLCertificateKeyFile       /PATH/TO/PRIVATE/KEY/FILE

    # setup the proxy to forward websocket requests properly to a normal websocket
    # and vice versa, so there's no need to change the colyseus library or the
    # server for that matter)
    # (note: this proxy automatically converts the secure websocket (wss)

    RewriteEngine On
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$           [NC,OR]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$          [NC]
    RewriteRule .* ws://{REQUEST_URI}  [P,QSA,L]

    # setup the proxy to forward all https requests to http backend
    # (also automatic conversion from https to http and vice versa)

    ProxyPass "/" "http://localhost:APP-PORT-HERE/"
    ProxyPassReverse "/" "http://localhost:APP-PORT-HERE/"



Greenlock is a great tool if you want to quickly have SSL configured on your server, without the need to configure a reverse-proxy.

When using greenlock-express, you should not have any reverse-proxy configured behind it, such as Nginx or Apache.

npm install --save greenlock-express

Please follow greenlock-express's README section first.

Here's the recommended way to handle both development and production environments:

import http from "http";
import express from "express";
import { Server } from "colyseus";

function setup(app: express.Application, server: http.Server) {
  const gameServer = new Server({ server });

  // TODO: configure `app` and `gameServer` accourding to your needs.
  // gameServer.define("room", YourRoom);

  return app;

if (process.env.NODE_ENV === "production") {
    .init(function () {
      return {
        greenlock: require('./greenlock'),
        cluster: false
    .ready(function (glx) {
      const app = express();

      // Serves on 80 and 443
      // Get's SSL certificates magically!
      glx.serveApp(setup(app, glx.httpsServer(undefined, app)));

} else {
  // development port
  const PORT = process.env.PORT || 2567;

  const app = express();
  const server = http.createServer(app);

  setup(app, server);
  server.listen(PORT, () => console.log(`Listening on http://localhost:${PORT}`));



  • package.json and package-lock.json are in the project.

  • Set up the npm start command so it starts the server


Step 1 Install Docker

Step 2 Create Dockerfile in the root of the colyseus project

FROM node:14


WORKDIR /usr/src/app

# A wildcard is used to ensure both package.json AND package-lock.json are copied
COPY package*.json ./

RUN npm ci
# run this for production
# npm ci --only=production

COPY . .


CMD [ "npm", "start" ]

Step 3 Create .dockerignore file in the same directory


This will prevent your local modules and debug logs from being copied onto your Docker image and possibly overwriting modules installed within your image.

Step 4 Go to the directory that has your Dockerfile and run the following command to build the Docker image. The -t flag lets you tag your image so it's easier to find later using the docker images command:

docker build -t <your username>/colyseus-server .

Step 5 Your image will now be listed by Docker with following command:

docker images


# Example
REPOSITORY                      TAG        ID              CREATED
node                            14         1934b0b038d1    About a minute ago
<your username>/colseus-server    latest     d64d3505b0d2    About a minute ago

Step 6 Run the Docker Image wiht following command:

docker run -p 8080:8080 -d <your username>/colyseus-server

Running your image with -d runs the container in detached mode, leaving the container running in the background. The -p flag redirects a public port to a private port inside the container.

Step 7 Done, now you can connect to the server with localhost:8080

More informations:

Back to top