WebSocket Migration Guide

Release 2024.07.12 adds self-hosted WebSockets functionality. The Pusher integration is replaced by an extra Docker container that handles WebSockets. The following steps are required to upgrade to this new version. If you are doing a fresh install on this version, you can ignore this migration guide and simply follow the installation instructions in the documentation.

1. Make a backup

As usual, before upgrading to a new version of Reporter, ensure that you have a backup.

2. Add an extra container

If you are using Docker Compose, have a look at our latest example docker-compose.yml configuration file. You can find this by downloading the latest release archive.

If you are using our example Docker Compose setup and haven't made any changes to your docker-compose.yml file, simply replace your existing docker-compose.yml file with the one from the archive. If you have made changes, proceed as follows.

In addition to the three existing containers that use our Reporter image, a fourth container using the same image must be added. This fourth container does not require access to the MySQL, ElasticSearch, and Redis containers. It does need to be accessible by the Reporter worker, scheduler, Horizon, and Nginx containers.

Reporter architecture

 

The new Reverb container should have the CONTAINER_ROLE environment variable set to reverb. Additionally, the depends_on list of the main Reporter container should be updated to also include the Reverb container.

The new Reverb container does not need access to any shared volumes.

3. Update environment variables

The following environment variables should be set in all four Reporter containers:

  • REVERB_HOST: Hostname of the Reverb container that is used by the Reporter container to communicate with Reverb. When the Reporter container and the Reverb container are part of the same docker-compose setup, REVERB_HOST is typically set to the hostname of the Reverb container. In our example docker-compose setup, this should be equal to reporter-php-reverb.

  • REVERB_PORT: Port that the Reverb container listens to (optional, default 8080).

  • REVERB_SCHEME: Scheme that is used for communication between containers (optional, default http).

  • REVERB_APP_ID: ID for the application, used internally by Reporter and Reverb. Example: reporter.

  • REVERB_APP_KEY: Used by the front-end client to connect to Reverb. Will be visible to users. Example: reporter.

  • REVERB_APP_SECRET: Used to verify requests from the client. Will not be visible to users and should be kept secret. Should be a long randomly generated password. Generate one by running the command openssl rand -base64 32.

If you are using our example docker-compose configuration, the following script can be used to update php.env and php_secret.env with these environment variables:

echo -e "\nREVERB_HOST=reporter-php-reverb\nREVERB_APP_ID=reporter\nREVERB_APP_KEY=reporter\n" >> php.env
echo -e "\nREVERB_APP_SECRET=$(openssl rand -base64 32)\n" >> php_secret.env

Additionally, all environment variables related to Pusher can be removed. If you have set the BROADCAST_CONNECTION environment variable to pusher, remove it as well.

4. Update Nginx configuration

Add a section to the configuration of your Nginx reverse proxy to proxy all requests to <app url>/ws/<...> to <reverb container>:8080/<...> and upgrade the connection to a WebSocket connection. Example:

       http {
            # Note: existing settings have been omitted from this example.
            server {
                listen 443 ssl http2;
                listen [::]:443 ssl http2;
                # Note: existing settings have been omitted from this example.
                location /ws/ {
                    proxy_http_version 1.1;
                    proxy_set_header Host $http_host;
                    proxy_set_header Scheme $scheme;
                    proxy_set_header SERVER_PORT $server_port;
                    proxy_set_header REMOTE_ADDR $remote_addr;
                    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                    proxy_set_header Upgrade $http_upgrade;
                    proxy_set_header Connection "Upgrade";
                    rewrite ^/ws/(.*)$ /$1 break;
                    proxy_pass http://reporter-php-reverb:8080;
                }
            }
        }

If you are using our example docker-compose configuration and haven't changed the Nginx configuration file, you can simply download the latest release archive and replace your Nginx configuration file with the one in the archive.

5. Update images

Run the following command to pull the latest images and apply your updated configuration:

docker-compose pull
docker-compose down
docker-compose up -d