Docker installation

The Docker installation runs the lsFusion platform — the database server, the application server, and the web client — as three containers described by a single compose.yaml file, without installing the platform components on the host. A project that inherits the Maven module of the platform can also build its own Docker image of the application and generate its own compose.yaml.

info

To work with Docker containers, you need to install Docker and Docker Compose.

Launching the lsFusion platform using Docker Compose

• Download the compose.yaml file from central server to a folder of your choice (we'll call it $FUSION_DIR$). This file contains the settings for running the three containers:

  • PostgreSQL
  • Application Server
  • Web client

• The compose.yaml setting (optional):

  • If you want to change the startup settings (e.g., use a different container version or customize environment variables), edit the compose.yaml file according to the Docker documentation.
  • Application server startup parameters can also be set using the container's environment variables - in the environment attribute. For example, to change the server locale to Russian and set custom Xmx value, write:

    environment:
      - USER_SETLANGUAGE=ru
      - USER_SETCOUNTRY=RU 
      - JAVA_OPTS=-Xmx10g

    When searching for startup parameters in environment variables, Spring automatically converts them to uppercase and replaces dots with underscores. In the example above, the values of the environment variables will be substituted into the appropriate parameters: user.setLanguage and user.setCountry.
  • Available lsFusion container images:
    • Server
    • Client

• Starting the containers:

  Navigate to the $FUSION_DIR$ folder and run the command:

  docker-compose up -d

  Once the launch is complete, the web client will be available at http://localhost:8080/.

• Working with project files:

  • After the first run, subfolders will be created in the $FUSION_DIR$ folder:

    • docker-client-conf - client configuration.
    • docker-db - database data.
    • docker-server - server files.

    These directories are bind-mounted into their respective containers.

  • In the docker-server folder put the lsFusion language modules (.lsf files or folders with them), as well as additional resources (reports, Java files, images, CSS, JS, etc.). The server logs and the settings.properties file are also in the same folder.

---

Creating and running a Docker image of your project

If your project inherits the Maven module of the lsFusion platform logics, you can use the built-in tools to create a Docker image and generate a compose.yaml file.

Creating a Docker image

• Building the image:

  Building a Docker image is tied to Maven phases and is activated by the docker profile.

  • In the install phase, the image is built and loaded into the local storage.
  • In the deploy phase, the image is uploaded to a public registry (e.g. Docker Hub).

  To build the image, run the command in the project folder:

  mvn install -P assemble,docker

  If you want to build an image based on uber-jar with the lsFusion server included, add the embed-server profile:

  mvn install -P assemble,embed-server,docker

  By default, an image specific to the architecture and operating system of the Docker daemon. To build a multi-architecture image (linux/amd64 and linux/arm64), you need to add the multiarch profile. This only works during the deploy phase:

  mvn deploy -P assemble,docker,multiarch

• Uploading the image to the public registry:

  To assemble an image and upload it to Docker Hub execute:

  mvn deploy -P assemble,docker

  Or (for uber-jar with server):

  mvn deploy -P assemble,embed-server,docker

• Configuring the image name:

  The default image name is: local/<artifactId>:<version> (artifactId, version are the values of the corresponding tags in the pom.xml file of the project module). You can override part of the name or the whole name via Maven properties in pom.xml:

  <properties>.
      <docker.image.namespace>foo</docker.image.namespace>
      <docker.image.repository>bar</docker.image.repository>
      <docker.image.tag>1.0</docker.image.tag>
      <!-- or -->
      <docker.image.fullName>foo/bar:1.0</docker.image.fullName>
  </properties>

Generating and using compose.yaml

• Automatic generation:

  • When you build a project with one of the above commands with the docker profile, Maven automatically generates a compose.yaml file.
  • The file is generated with the substituted lsFusion platform version and the name of your project's Docker image.
  • The file is saved in the target folder or in the path specified in Maven's docker.compose.outputDirectory property. Also, the contents of the file are printed to the console after building.

• Running the generated compose.yaml:

  Startup and configuration are similar to the steps described in Launching the lsFusion platform with some specifics:

  • The Docker Compose project name defaults to artifactId tag value. To generate a different project name, override the Maven property docker.compose.projectName.

---

Upgrading PostgreSQL

The compose.yaml file pins the major PostgreSQL version. Major PostgreSQL versions are incompatible with each other in the on-disk data format, so after changing the image version the DB container will not start until the database is migrated.

Starting with version 18, the PostgreSQL image stores the data of each version in a separate subfolder (e.g. 18/docker) and mounts the data folder at /var/lib/postgresql (details). In versions before 18, the data was located in the root of the docker-db folder, which was mounted at /var/lib/postgresql/data. Therefore, when upgrading from version 17 or lower, both the image version and the mount path change in compose.yaml:

  db:
    image: postgres:18
    volumes:
      - ./docker-db:/var/lib/postgresql

For subsequent upgrades between versions 18 and higher the mount path no longer changes — only the image version.

warning

Before migrating by either method, make sure you have a fresh backup of the database (for example, a copy of the docker-db folder taken while the containers are stopped).

The database can be migrated in one of the following ways:

• Dump and restore — the recommended method for most installations: the new cluster is initialized by the image in the normal way, and the data is loaded into it with the standard pg_dumpall:

  docker compose exec db pg_dumpall -U postgres > backup.sql   # while the old version is still running;
                                                               # the file is created next to compose.yaml
  docker compose down
  # rename the docker-db folder (e.g. to docker-db-old) - the old data remains
  # as a backup while the new container creates a fresh cluster; update compose.yaml
  docker compose up -d db
  docker compose exec -T db psql -U postgres < backup.sql
  docker compose up -d

• Migration script — for large databases, when dump and restore takes too much time. The script is intended for the standard installation described on this page. Download the pg-migrate.bat (Windows) or pg-migrate.sh (Linux) script together with pg-migrate-container.sh from the central server to the $FUSION_DIR$ folder. Set the new image version in compose.yaml (and, when upgrading from 17 or lower, the new mount path), then run the script. The script automates the steps specific to the Docker image: it stops the containers, makes a backup copy of the docker-db folder (in docker-db-backup), detects the source version and data layout, and starts the containers again after the migration. The migration itself is performed by the standard pg_upgrade. The script does not carry over custom postgresql.conf settings. The old cluster remains in the docker-db subfolder with the old version — delete it together with the backup copy after making sure everything works.

For non-standard configurations (replication, modified images or data layout), use the standard PostgreSQL upgrade procedure.