Deploy multi player on self-hosted Docker

🧑‍💻 Retool Tips & Tricks
1

Set up Multiplayer on Self-hosted Docker Deployment

Overview

Retool's multiplayer feature enables real-time collaboration between users working on the same application. The following example is for setting it up on your Docker Deployment in your production environment. Start with Retool’s template for Docker Deployment on our on-premise repo and follow the instructions for Docker deployment. Follow these instructions to connect to Retool with HTTPS and configure custom certificates for Docker-based deployments.

Setting up multiplayer with Docker requires adding a dedicated multiplayer service and configuring nginx as a reverse proxy to handle WebSocket connections.

Configuration Steps

1. Add the Multiplayer Service

First, you'll need to add a new service to your docker compose.yaml file. This service handles the real-time collaboration features.

Add the following service definition to your compose file:

multiplayer:
  build: .
  env_file: docker.env
  environment:
    - SERVICE_TYPE=MULTIPLAYER
    - WEBSOCKET_ALLOWED_ORIGIN=retool.your_company.com
  networks:
    - backend
  ports:
    - 3009:3009
  restart: always

Key configuration notes:

  • SERVICE_TYPE=MULTIPLAYER tells the Retool container to run in multiplayer mode

  • WEBSOCKET_ALLOWED_ORIGIN should be set to your Retool domain (retool.your_compoany.com)

  • The service runs on port 3009 by default

2. Add the Nginx Service

Next, add an nginx service to act as a reverse proxy. This is essential for routing WebSocket connections properly.

Add this service to your docker-compose.yaml:

nginx:
  image: nginx:latest
  ports:
    - "80:80"
    - "433:433"
  volumes:
    - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    - ./ssl:/etc/nginx/ssl:ro
  networks:
    - frontend
    - backend
  depends_on:
    - api
    - multiplayer
  restart: always

This configuration mounts your nginx configuration file and ensures the service starts after both the api and multiplayer services are ready.

Note that Retool’s docker-compose.yaml template file uses an https-portal service for handling the reverse proxy and TLS. For multiplayer, replace this with the above nginx service.

3. Create the Nginx Configuration

Create a new directory called nginx in your Docker repository root, then create an nginx.conf file inside it with the following content:

events {
       worker_connections 1024;
}

http {

   # multiplayer websocket headers
   map $http_upgrade $connection_upgrade {
       default upgrade;
       '' close;
   }

   # http -> https
   server {
       listen 80;
       server_name retool.your_company.com;

       location / {
           return 301 https://$host$request_uri;
       }
   }

   # https
   server {
       listen 443 ssl;
       server_name retool.your_company.com;
       ssl_certificate /etc/nginx/ssl/your_cert.pem;
       ssl_certificate_key /etc/nginx/ssl/your_cert-key.pem;
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_prefer_server_ciphers on;
       client_max_body_size 40M;

       # multiplayer
       location /api/multiplayer/ {
         proxy_pass http://multiplayer:3009/api/multiplayer/;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection $connection_upgrade;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         pr
oxy_set_header X-Forwarded-Proto $scheme;

         proxy_connect_timeout 600s;
         proxy_send_timeout 600s;
         proxy_read_timeout 600s;
         proxy_buffering off;
       }

       # everything else
       location / {
         proxy_pass http://api:3000/;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection $connection_upgrade;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $scheme;
      
       # WebSocket timeouts
         proxy_connect_timeout 600s;
         proxy_send_timeout 600s;
         proxy_read_timeout 600s;
         proxy_buffering off;
       }
   }
}

Important details:

  • The map directive handles WebSocket upgrade requests

  • The /api/multiplayer/ location block must come before the main / location to ensure proper routing

  • WebSocket headers (Upgrade and Connection) are required for the multiplayer service to function correctly

4**. Deploy the Changes**

Once you've made these changes, restart your Retool deployment:

docker-compose down
docker-compose up -d

Feature Flags

Contact Retool support to make sure that your license key has the necessary multiplayer feature flags enabled.

Enable multiplayer in your Beta settings.

Verification

After deployment, you can verify that multiplayer is working by opening the same Retool application in two different browser windows in edit mode. You should see real-time cursor positions and edits from other users.

2 Likes