Deployment
Deploying Colyseus for a single-process environment is no different than deploying a regular Node.js application (see a good article here).
However, deploying Colyseus for a multi-process environment requires some extra steps.
Colyseus Cloud¶
The easiest way to deploy your Colyseus server is to use the Colyseus Cloud. It should take less than 15 minutes to get your server up and ready for production.
Colyseus Cloud uses NGINX, PM2, and requires you to use the @colyseus/tools
package for easy integration with its infrastructure.
See the configuration required for deploying on Colyseus Cloud:
The create-colyseus-app
templates are ready for deployment on Colyseus Cloud.
Nginx¶
When self-hosting, it is recommended to use nginx
and pm2
in your production environment.
PM2¶
Install pm2
in your environment.
Then start your server using it:
Nginx configuration¶
server {
listen 80;
server_name yourdomain.com;
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;
server_name yourdomain.com;
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;
}
}
Apache¶
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>
ServerName servername.xyz
# Redirect all requests received from port 80 to the HTTPS variant (force ssl)
RewriteEngine On
RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>
<VirtualHost *:443>
ServerName servername.xyz
# 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://127.0.0.1:APP-PORT-HERE%{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/"
</VirtualHost>
Docker¶
Prerequisite:
-
package.json
andpackage-lock.json
are in the project. -
Set up the
npm start
command so it starts the server
Steps:
Step 1 Install Docker
Step 2 Create Dockerfile
in the root of the colyseus project
FROM node:14
ENV PORT 8080
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 . .
EXPOSE 8080
CMD [ "npm", "start" ]
.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:
Step 5 Your image will now be listed by Docker with following command:
Output:# 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:
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:
Heroku¶
Heroku can be used for prototyping. You can deploy the colyseus-examples project on it by hitting this button:
Scaling Colyseus on Heroku is not practical. We do not recommend using Heroku with Colyseus in production.
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.