Configure multiple dispatchers

If you have multiple dispatchers on a host, you must specify unique ports and application data directories for each dispatcher to ensure dispatcher information does not get mixed up.

While multiple dispatchers are typically not needed, you might have multiple dispatchers to support different environments using the same version of the Genero Application Server on the same host. For example, you may wish to co-locate your production, training, and development environments.

To start multiple dispatchers on a single host, there are two options:

Have a separate application server configuration file for each dispatcher.
1. Make a copy of the default configuration file (as.xcf) for each dispatcher, giving each copy a unique name.
2. Specify different settings for the ports and application data directory in each configuration file. The elements you need to configure are shown in Table 1.
3. Start each dispatcher with the -f option to specify the configuration file to use:
```
$FGLASDIR/bin/httpdispatch -f $FGLASDIR/etc/mydispatcherx.xcf
```
Alternatively, you can share the default configuration file between all the dispatchers by starting dispatchers with the -E option to specify unique ports and application data directories for each dispatcher. For more information and a sample command, go to Dispatcher override option (-E).

In addition, you will also need to configure your web server for multiple dispatchers:

If using Apache web server, you must create different ProxyPass and ProxyPassReverse directives in the Apache configuration for each fastcgidispatch dispatcher, as Apache must deliver requests to the GAS with the corresponding port and path alias. For more information on configuring Apache, go to FastCGI GAS configuration on various web server.
If using Internet Information Services (IIS) web server, you must create a different application pool for each isapidispatch dispatcher, each with its own application root directory containing the isapidispatch.ini file. For more information on configuring IIS, go to Manual configuration for IIS 8.x and IIS 10.x.

Table 1. Configuration elements to define for each dispatcher
Elements	Resources	Setting values across dispatchers
`TCP_BASE_PORT` + `TCP_PORT_OFFSET`	`res.ic.base.port` + `res.ic.port.offset`	A GAS dispatcher listening port is set by adding the port offset to the base port. Each dispatcher on a server requires a unique listening port. In fact, all port numbers – both the computed listening ports and the set admin ports – must be unique between all the dispatchers. Tip: Giving a different `TCP_BASE_PORT` for each dispatcher will make dispatchers more recognisable to you from the address line of the apps they are running.
`TCP_ADMIN_PORT`	`res.ic.admin.port`	The admin port is for GAS administration tasks. Each dispatcher on a server requires a unique admin port. In fact, all port numbers – both the computed listening ports and the set admin ports – must be unique between all the dispatchers.
`res.appdata.path` (Application data directory)	`res.appdata.path`	The application data directory, or appdata, is where the application data files (log, tmp, session, and so on) managed by the GAS are located. It is recommended that this directory be unique between all the dispatchers. Tip: While not recommended, you can share the application data directory between dispatchers. For more information, see Shared application data directory.

Dispatcher override option (-E)

Instead of creating separate configuration files for each dispatcher, you can share the default configuration file (as.xcf) between all the dispatchers provided you override the following resources with different values on starting the dispatcher:

res.ic.base.port
res.ic.port.offset
res.ic.admin.port
res.appdata.path

In this example, the dispatcher is started with the -E option to override the settings for the server base port and offset, admin port, and the appdata path. (Line breaks have been added to improve readability.)

$FGLASDIR/bin/httpdispatch -E res.ic.base.port=dispatcherx-base-port
   -E res.ic.port.offset=myOffset 
   -E res.ic.admin.port=dispatcherx-admin-port 
   -E res.appdata.path=appdatax-path

Where:

dispatcherx-base-port defines a unique base port for this dispatcher.
myOffset defines a unique offset for this dispatcher.
dispatcherx-admin-port defines the unique admin port for this dispatcher.
appdatax-path defines the unique path to the appdata directory for this dispatcher.

Shared application data directory

Sharing the same application data directory (appdata) between all the dispatchers is not recommended. For more information on why you need to be cautious about this, see Why do my applications fail using multiple dispatchers? and Error taking session ownership.

However, if you want to use the same application data directory for each dispatcher, it is important to ensure that the log, tmp, and session directories located under the appdata directory remain independent and unique between all the dispatchers.

You can set resources for the log, tmp, and session directories directly in the application server configuration file (a copy of the default as.xcf) for each dispatcher, or run the dispatcher with the -E option to override the resource. For examples, go to Table 2

Table 2. Configure different log, tmp, and session directories per dispatcher
Elements	Resources	Configuration file (as1.xcf) example	Override example
`OUTPUT`	`res.log.output.path`	`<RESOURCE Id="res.log.output.path" Source="INTERNAL">$(res.appdata.path)/dispatcherx-log</RESOURCE>`	`httpdispatch -E res.log.output.path=/work/gas/appdata/dispatcherx-log`
`TEMPORARY_DIRECTORY`	`res.path.tmp`	`<RESOURCE Id="res.path.tmp" Source="INTERNAL">$(res.appdata.path)/dispatcherx-tmp</RESOURCE>`	`httpdispatch -E res.path.tmp=/work/gas/appdata/dispatcherx-tmp`
`SESSION_DIRECTORY`	No independent resource available; the path can only be set directly in the configuration file.	`<SESSION_DIRECTORY>$(res.appdata.path)/dispatcherx-session</SESSION_DIRECTORY>`	Not applicable

Default as.xcf appdata settings

In this example, the default settings for the appdata resources of the GAS are shown. The res.appdata.path resource specifies the appdata directory, which is the root directory for the log, tmp, and session directories. In the example, the appdata path is shown for a Windows® system.

<RESOURCE Id="res.appdata.path"
 Source="INTERNAL">C:\ProgramData\FourJs\gas\3.21</RESOURCE>

Resources for the log, tmp, and session directories are set within the appdata directory:

The res.log.output.path resource and the LOG element define the path to the log directory:

<RESOURCE Id="res.log.output.path"
 Source="INTERNAL">$(res.appdata.path)/log</RESOURCE>
#...
<LOG>
  <OUTPUT Type="$(res.log.output.type)">$(res.log.output.path)</OUTPUT>
  # ...
</LOG>

The res.path.tmp resource and the TEMPORARY_DIRECTORY element define the path to the temporary directory:

<RESOURCE Id="res.path.tmp"
 Source="INTERNAL">$(res.appdata.path)/tmp</RESOURCE>
# ...
<TEMPORARY_DIRECTORY>$(res.path.tmp)</TEMPORARY_DIRECTORY>

The SESSION_DIRECTORY element defines the path to the session directory:
```
<SESSION_DIRECTORY>$(res.appdata.path)/session</SESSION_DIRECTORY>
```