Page tree
Skip to end of metadata
Go to start of metadata

In order to use the multi user editing, the plug-in FrontEndMessageBus must be enabled in translate5 config and the socket server started and properly configured.

One Socket Server can be used by multiple translate5 installations on the same server.

Please follow the following steps to install and configure.

Configuration of the Socket Server (SSL enabled)

translate5 and the socket server must either run with SSL or both not. A mixture is not possible.

Apache proxy configuration

If you have an existing Apache Config for translate5, you have only to add the

LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so 
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so

and the

SSLProxyEngine on
ProxyPass /wss ws://example.translate5.net:9056/

to your HTTPS Vhost entry.

IMPORTANT: the domain in the ProxyPass command MUST match the configured domain in the Socket Server configuration in config.php (see below)



Example Apache configuration
# enable the proxy modules in main apache configuration
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so

#
# example configuration of virtual host running translate5
#
<VirtualHost *:80>
    ServerName  example.translate5.net
    DocumentRoot /usr/srv/example.translate5.net/public
    # HTTP access is forbidden by redirecting always to HTTPS
    Redirect permanent / https://example.translate5.net/
</VirtualHost>

<VirtualHost *:443>
    ServerName  example.translate5.net
    DocumentRoot /usr/srv/example.translate5.net/public
    SSLEngine on
    SSLProxyEngine on										# The SSLProxyEngine must be enabled, otherwise you will get errors from apache on reload
    ProxyPass /wss ws://example.translate5.net:9056/        # IMPORTANT: the domain here MUST match the configured domain in the Socket Server configuration in config.php (see below)
</VirtualHost>

<VirtualHost *:443>
    ServerName  anotherexample.translate5.net
    DocumentRoot /usr/srv/anotherexample.translate5.net/public
    SSLEngine on
        # IMPORTANT: Another translate5 installation may use the same socket server, 
        # BUT the socket server may be configured only with one domain!
		# Therefore for anotherexample no separate proxypass is needed because the 
		# GUI must then be configured to use also wss://example.translate5.net!
</VirtualHost>

Conclusion when using multiple Translate5 installations on one socket server

When using multiple translate5 installations on one server, they all can share one socket server. This is perfeclty possible due instance isolation in the socket server.

A separate virtualHost (for exmaple socketserver.translate5.net) may be configured then with the above proxy pass. All translate5 installations must be configured then to use socketserver.translate5.net as socket server.

Socket Server configuration in config.php

In application/modules/editor/Plugins/FrontEndMessageBus resides the file "config.php.example". Copy that file to config.php, and open it for editing.

Socket Server Config for above mentioned setup
$configuration = [
    'messageServer' => [
        //address: IP address to listen for connections of translate5 instances 
        // MUST match the server configured in messageServer config in the instance.  
        'address' => '127.0.0.1',
        
        //port:       Port to listen on.
        // MUST match the messagePort config in the instance. 
        'port' => '9057',
    ],
    'socketServer' => [
        //httpHost:   HTTP hostname clients intend to connect to. 
        // IMPORTANT MUST match the socketServer config in the translate5 instance and (if used) in Apache ProxyPass statement!
        //  In environments where an internal and external IP (AWS EC2 for example) is used, the ports must either mapped through, 
        //  or the httpHost should be set here to localhost where the proxypass points to too.
        // (MUST match JS `new WebSocket('ws://$httpHost');`)
        'httpHost' => 'example.translate5.net',
        
        //port:       Port to listen on.
        // MUST match the socketPort config in the instance. 
        'port' => '9056',
        
        //listen:    IP address to bind to. '0.0.0.0' for any interface.
        'listen' => '0.0.0.0',
        
        //route:    The URL path to be used for the socket server, defaults to /translate5 and should normally not to be changed.
        // When using SSL via ProxyPass, the proxy path (/tobedefined/ in the above example) MUST NOT added here!
        'route' => '/translate5', // IMPORTANT although the ProxyPass /wss is used in the example, this MUST NOT added here!
    ]
];

Translate5

In the translate5 the following lines should either added to installation.ini or should be changed in the DB table Zf_Configuration:

Configuration of translate5
runtimeOptions.plugins.active[] = "editor_Plugins_FrontEndMessageBus_Init"
runtimeOptions.plugins.FrontEndMessageBus.socketServer.httpHost = example.translate5.net ; MUST be set to the socketServer['httpHost'] in above config.php 
																						 ; MUST be set to the ProxyPass path target domain in above apache config
																						 ; regardless if the translate5 server name is different!
runtimeOptions.plugins.FrontEndMessageBus.socketServer.schema = wss						 ; MUST be set to the ProxyPass alias path in above apache config
runtimeOptions.plugins.FrontEndMessageBus.socketServer.port = 443						 ; MUST be set to your apache SSL port, normally 443
runtimeOptions.plugins.FrontEndMessageBus.socketServer.route = /wss/translate5           ; MUST match the ProxyPass Alias + the route configured in config.php

Trouble-shooting (TODO)

  • Possible problems: using HTTPS but no wss schema: must be defined as error in MessageBus.js!
  • Browser Error: WebSocket connection to 'wss://example.translate5.net/wss/translate5?serverId=xxx&sessionId=xxx' failed: Error during WebSocket handshake: Unexpected response code: 503
    • Either the socket server is down, or the proxy is configured wrong. Apache can not route the request to the socket server.
  • Browser Error: WebSocket connection to 'wss://example.translate5.net/wss/translate5?serverId=xxx&sessionId=xxx' failed: Error during WebSocket handshake: Unexpected response code: 404
    • The 404 is coming from the socket server. This means the basic proxy config is correct, but one of the 3 configurable hostnames (config.php / ProxyPass / installation.ini) does not match.

Configuration of the Socket Server (without SSL, for development only!)

Since no SSL is used in this configuration, no Apache WSS Proxy is needed, the configuration is easy then. Mostly the default values can be used.

Socket Server

# in config.php all default values can be used unchanged, only httpHost must be set to your needs:

        'httpHost' => 'SET.A.VALID.HOSTNAME.HERE',

Translate5

installation.ini
; add the following lines to the installation.ini
runtimeOptions.plugins.active[] = "editor_Plugins_FrontEndMessageBus_Init"
runtimeOptions.plugins.FrontEndMessageBus.socketServer.httpHost = SET.A.VALID.HOSTNAME.HERE   ; MUST be the same as above in httpHost

Starting the socket server

Basic usage and testing

For basic usage and testing the socket server can be run directly via commandline by calling the server.php in the FrontendMessageBus directory:

php server.php

Productive usage - start the socket server via supervisord

For productive usage the server.php should be run as daemon, for example with supervisord as recommended in the documentation of the used ratchet library.

supervisord installation

For installation of supervisord see http://supervisord.org/installing.html and for running http://supervisord.org/running.html.

Under Ubuntu a "apt install supervisor" should do the job.

For integration of supervisord in boot up, either a start script was provided by your linux distribution or follow the instructions in: https://serverfault.com/questions/96499/how-to-automatically-start-supervisord-on-linux-ubuntu

If installed via apt under Ubuntu, just call "systemctl enable --now supervisor"

supervisord configuration

Follow the supervisor installation instructions to create proper config templates, or if installed with apt just create the following file in /etc/supervisor/conf.d/

Create a program section for translate5 messagebus:

/etc/supervisord/conf.d/translate5_message_bus.conf
[program:t5socketserver]
command                 = bash -c "exec /usr/bin/php /pathToMessageBus/server.php"
process_name            = Translate5SocketServer
numprocs                = 1
autostart               = true
autorestart             = true
user                    = t5messagebus
stdout_logfile          = /var/log/supervisor/t5-messagebus.log
stdout_logfile_maxbytes = 1MB
stderr_logfile          = /var/log/supervisor/t5-messagebus-error.log
stderr_logfile_maxbytes = 1MB

Important: restart supervisord after creating the above configuration file.

sudo systemctl restart supervisor

After the restart the messagebus server should have been started automatically. To verify this do:

sudo supervisorctl status
# this should output then something similar to:
t5socketserver:Translate5SocketServer   RUNNING   pid 979, uptime 4:37:43

Important supervisord commands

First start the supervisorctl console:

sudo supervisorctl

This offers you the supervisor prompt showing you the status of all cofigured programs.

The following commands can be helpful:

commanddescription
help [command]prints all available commands
statusprints all configured commands and their status information
startstarts a single configured program, tab can be used to complete programs
restart [all | progname]restarts all or a single program
update [all]Reload program ini config and add/remove as necessary, and will restart affected programs
reloadreloads the whole supervisord, if the main config changed for example.
tailshows the logged output of the program
  • No labels