Docker Compose

Docker Compose is a tool for defining and running multi-container Docker applications. In FNZ Studio's context, this allows running multiple nodes.

Prerequisites

To use FNZ Studio with Docker Compose, you need the following:

  • A laptop or any other machine with Docker installed.

  • Access to a FNZ Studio Docker image. You can use the standard FNZ Studio Docker images, or build your own images.

  • A multi-node FNZ Studio license file.

  • The DefaultUser Extension matching your FNZ Studio version. This creates a default user which allows you to log in.

Resources

To run FNZ Studio using Docker Compose:

  1. Create a configuration file called compose.yaml where the FNZ Studio instances are configured. See Docker Compose Configuration
  2. Configure a load balancer that serves as the main entry point when accessing FNZ Studio. The load balancer forwards the requests to the FNZ Studio nodes. See Load Balancer Configuration

  3. Prepare the required directory structure, and add the license file and the DefaultUser Extension. See License File and Default User Extension

 

Docker Compose Configuration

The following example of the compose.yaml file shows a possible configuration for an Appway cluster:

Note: For simplicity, the Cluster Storage is configured to use the filesystem and the folder is mounted as a Docker volume; but this can be customized and replaced by any Cluster Storage extension (e.g. AzureHazelcastStore, AWSHazelcast Store, CassandraHazelcast Store, RelationalDbHazelcastStore).
Copy 
# file name: compose.yaml

name: awcluster
services:
  appway:
    image: ${APPWAY_IMAGE}
    expose:
      - "8080"
    environment:
      - NM_CLUSTER_NETWORK_JOIN_MULTICAST_ENABLED=true
      - NM_CLUSTER_PERSISTENCE_FILESYSTEM_PATH=/appway/cluster-storage
      - NM_BLOB_STORAGE_FILESYSTEM_SILOS=blob-storage=/appway/blob-storage
      - NM_DDWS_BLOBSTORAGESILO=blob-storage
      - NM_CLUSTER_STARTUP_FILE_SYNC_ENABLED=true
      - APPWAY_DEFAULTUSER_DEFAULT_USER_PASSWORD=master
      - JAVA_OPTS=-Xmx2g -Duser.language=en -Dfile.encoding=UTF8
    volumes:
      - ${CLUSTER_STORAGE_DIRECTORY}:/appway/cluster-storage
      - ${BLOB_STORAGE_DIRECTORY}:/appway/blob-storage
      - ${ADDITIONAL_EXTENSIONS_DIRECTORY}:/appway/additional-extensions
      - ${ADDITIONAL_PACKAGES_DIRECTORY}:/appway/additional-packages
      - ${ADDITIONAL_LIBS_DIRECTORY}:/appway/additional-libs
      - ${LICENSE_FILE_PATH}:/appway/data-home/conf/license.properties
  nginx:
    depends_on:
      - appway
    image: nginx:1
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    ports:
      - "8080:80"

Load Balancer Configuration

In the following example, a Nginx server is configured:

Copy 
# file name: nginx.conf

worker_processes 1;

events { worker_connections 1024; }

http {
    access_log off;
    sendfile on;

    # Add Docker's internal DNS resolver.
    # 127.0.0.11 is the standard address for Docker's embedded DNS server.
    # 'valid=5s' means Nginx will re-resolve the names every 5 seconds,
    # picking up changes if appway instances are added or removed.
    resolver 127.0.0.11 valid=5s;

    upstream app_servers {
        # sticky sessions
        ip_hash;

        # Use the service name 'appway'.
        # Nginx will resolve 'appway' to the IP addresses of all
        # running 'appway' service instances.
        server appway:8080;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://app_servers;
            proxy_redirect     off;
            proxy_set_header   Host $http_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-Host $server_name;
        }
    }
}

License File

A multi-node FNZ Studio license file is required to use multiple nodes in the FNZ Studio cluster.

Configuration property nm.license.cluster.maxsize defines how many nodes are allowed:

Copy 
# file name: license.properties
...
nm.license.cluster.maxsize = 8
...

You can get such a license file from FNZ Studio Support.

Default User Extension

To log in, a user needs to exist in FNZ Studio.

The DefaultUser Extension creates the NM user with a configured password. To set the password, use the APPWAY_DEFAULTUSER_DEFAULT_USER_PASSWORD environment variable as shown in compose.yaml above.

After you have created the first user, remove the DefaultUser Extension from additional-extensions; otherwise FNZ Studio fails to start on subsequent startups.

You can get the DefaultUser Extension from FNZ Studio Support.

Start

  1. Create configuration files nginx.conf and compose.yaml as described above.

  2. Create the following script to start FNZ Studio:

    Copy 
    # file name: start-cluster.sh

    #!/bin/bash

    # parameters
    appwayVersion=$1
    numNodes=$2
    dockerRepository=$3

    # check that none of the parameters are unset
    if [ -z "$appwayVersion" ] || [ -z "$numNodes" ] || [ -z "$dockerRepository" ]; then
      echo "Required parameters: <appwayVersion> <numNodes> <dockerRepository>"
      return 1 2>/dev/null || exit 1
    fi

    # run Appway cluster
    export APPWAY_IMAGE="${dockerRepository}":"${appwayVersion}"
    export CLUSTER_STORAGE_DIRECTORY="$(pwd)/cluster-storage"
    export BLOB_STORAGE_DIRECTORY="$(pwd)/blob-storage"
    export ADDITIONAL_EXTENSIONS_DIRECTORY="$(pwd)/additional-extensions"
    export ADDITIONAL_PACKAGES_DIRECTORY="$(pwd)/additional-packages"
    export ADDITIONAL_LIBS_DIRECTORY="$(pwd)/additional-libs"
    export LICENSE_FILE_PATH="$(pwd)/license.properties"
    docker compose up \
      --scale appway="${numNodes}" \
      --pull always

  3. Prepare the required directory structure and add the license file and the DefaultUser Extension:

    Copy 
    mkdir -p cluster-storage blob-storage \
             additional-extensions additional-packages additional-libs
    cp .../license.properties .
    cp .../DefaultUser.jar ./additional-extensions/

  4. Your working directory should now look like this:

    Copy 
    tree
    .
    ├── additional-extensions/
    │   └── DefaultUser.jar
    ├── additional-libs/
    ├── additional-packages/
    ├── blob-storage/
    ├── cluster-storage/
    ├── compose.yaml
    ├── license.properties
    ├── nginx.conf
    └── start-cluster.sh

  5. Start. To do so, log in to Docker first and then start:

    Copy 
    # login to Docker
    docker login

    # start
    # (use source such that docker compose can be used afterwards)
    appwayVersion=2025.5.3
    numNodes=2
    dockerRepository=appwayag/platform
    source ./start-cluster.sh $appwayVersion $numNodes $dockerRepository

  6. You should now be able to log in at http://localhost:8080/admin. Use docker compose scale to scale the FNZ Studio cluster up or down:

    Copy 
    docker compose scale appway=3

Stop

To shut down the FNZ Studio cluster:

Copy 
docker compose down

Shutdown and Scaling without Data Loss

Warning! In order to avoid data loss, it is very important that you shut down or scale the FNZ Studio cluster according to the following instructions.

Make sure that you use the timeout parameter of the docker-compose command. Set a sufficiently large value for this timeout to ensure that the Appway nodes have enough time to shut down correctly, otherwise data loss can occur.

We recommend setting a timeout of 60s to begin with, but it is very important to test how long your Solution actually takes to shut down, and increase the timeout accordingly if your Solution needs more time to stop.

Copy 
docker compose down -t 60

Docker Standalone Tool

All the above configuration also exists as a packaged tool called Docker Standalone.

You can get Docker Standalone from FNZ Studio Support.