Skip to content

Installing and running S-Filer Portal using Docker containers

This Manual

Who this guide is for

This guide is intended for S-Filer Portal administrators.

The purpose of this manual is to guide you through the installation of S-Filer Portal using Docker containers. There are several ways of using Docker containers, this guide will focus on the most common ones, such as using Docker Compose.

Prerequisites

System requirements

In order to use the S-Filer Portal solution with Docker containers, you will need the following tools:

  1. Docker for GNU/Linux, macOS or Docker Desktop on Windows
  2. The Amazon Web Services (AWS) CLI
  3. An up and running functional database (with MySQL, Microsoft SQL Server, MariaDB or Oracle DB management systems), whether it is deployed using Docker or not.
  4. Docker Compose (optional, depends on your choice of deployment)

Docker images

The S-Filer Portal solution for Docker works using 3 Docker images:

  1. sfiler-config-cli, which encapsulates the Configuration CLI for the database's setup
  2. sfiler-server, which encapsulates the S-Filer Portal's server
  3. sfiler-gateway, which encapsulates the S-Filer Portal's gateway
Pulling the images

The Docker images for S-Filer Portal are stored in Amazon Web Services Elastic Container Registry (ECR). In order to retrieve them, you will need to authenticate to the registry.

Authenticate to the registry

Once the AWS CLI is installed, you will need to configure it using the following command:

shell
aws configure

Once you provide the credentials, the AWS CLI will be able to generate the authentication token for you.

To authenticate to the registry, you will need to run the following command:

shell
aws ecr get-login-password --region ca-central-1 | docker login --username AWS --password-stdin 550720984821.dkr.ecr.ca-central-1.amazonaws.com

WARNING

Note that the AWS CLI generates a token that is valid for 12 hours. As such, you will have to generate a token again using aws ecr get-login-password at least every 12 hours.

Pull

The Docker images are extracted using the following commands:

shell
docker pull 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-config-cli:SFILER_4_19_0
shell
docker pull 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-server:SFILER_4_19_0
shell
docker pull 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-gateway:SFILER_4_19_0

TIP

The images are tagged with the version number of the release. In this example, the version number is 4.19.0.

JDBC Driver

The S-Filer Portal solution is compatible with multiple Database Management Services (DBMS), such as MySQL, MariaDB or Oracle Database.

Hence, you need to provide a Java Database Connectivity (JDBC) driver in the form of .jar archive. Ensure you retrieve the JDBC for your DBMS in order to provide it to the S-Filer's configuration CLI and server.

Compatible JDBC Drivers

Here is a list of download links for JDBC compatible with S-Filer Portal

Database management systemLink to download JDBC Driver
MySQLhttps://dev.mysql.com/downloads/connector/j/
MariaDBhttps://mariadb.com/kb/en/about-mariadb-connector-j/
Microsoft SQL Serverhttps://docs.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15
Oracle DBhttps://www.oracle.com/database/technologies/appdev/jdbc-downloads.html

In this guide, the MySQL DBMS will be used.

Setup

Environment variables

sfiler-config-cli

CONFIG_CLI_COMMAND

A single command to be executed by the configuration CLI.

If you also provide a script, the command you provide as an environment variable will be executed first.

CONFIG_DB_USER

Username used to authenticate to the administrative interface and which also happens to be the user who will be used to access the database.

CONFIG_DB_PASSWORD

Password to authenticate to the administrative interface, which happens to be the same as the database password.

CONFIG_DB_URL

URL of the database. The format of the URL is: jdbc:mysql://[host]:[port]/[database]. The port is the database's port that is visible by the container.

CONFIG_DB_DRIVER

Driver used to communicate with the database.

CONFIG_DB_HIBERNATE_DIALECT

Dialect used by Hibernate to communicate with the database.
sfiler-server

LOGS

When set to "silent", server's container will not emit log to the standard output but only to its log file.

SFILER_SERVER_INSTANCE_NAME

S-Filer Portal server instance name. This name must be unique for each server instance. For the time being, it is not possible to have more than one server running at the same time.

CONFIGURATOR_START

If the value is true, the server will start with its administrative console. If set to false, only the server will be started.

CONFIGURATOR_SSL

If the value is true, the configurator will be started with an SSL certificate. Currently, the SSL certificate is automatically self-signed and it is not possible to supply one.

CONFIGURATOR_PORT

This is the port on which the administrative interface will be accessible.

CONFIG_DB_USER

Username used to authenticate to the administrative interface and which also happens to be the user who will be used to access the database.

CONFIG_DB_PASSWORD

Password to authenticate to the administrative interface, which happens to be the same as the database password.

CONFIG_DB_URL

URL of the database. The format of the URL is: jdbc:mysql://[host]:[port]/[database]. The port is the database's port that is visible by the container.

CONFIG_DB_DRIVER

Driver used to communicate with the database.

CONFIG_DB_HIBERNATE_DIALECT

Dialect used by Hibernate to communicate with the database.

CONFIGURATOR_SSL_CIPHER_MANAGEMENT_MODE

This configuration parameter determine which cipher suites are enabled for use on the server. The default value is Automatic. The following values are supported:
CONFIGURATOR_SSL_CIPHER_MANAGEMENT_MODEDescription
AUTOMATICThe server will automatically select the cipher suites to use based on the enabled protocols. When using this mode, only the strong ciphers will be enabled. This is the default value.
CUSTOMThe server will use the cipher suites specified in the CONFIGURATOR_SSL_CUSTOM_CIPHERS parameter.
JVM_DEFAULT_CIPHERSThe server will use the default cipher suites supported by the JVM.

CONFIGURATOR_SSL_CUSTOM_CIPHERS

This represents the list of Ciphers that are allowed to be used.

CONFIGURATOR_CLICKJACKING_PROTECTION

If set to "true", the X-Frame-Options header will be set on all responses to prevent clickjacking attacks. The default value is "true".

CONFIGURATOR_HSTS_HEADER_SUPPORT

If set to "true", the Strict-Transport-Security header will be set on all responses. The default value is "true".

CONFIGURATOR_HSTS_HEADER_SUPPORT_MAX_AGE

This represents the value of the Strict-Transport-Security header max-age directive.
sfiler-gateway

LOGS

When set to "silent", gateway's container will not emit log to the standard output but only to its log file.

SFILER_GATEWAY_INSTANCE_NAME

Name of the S-Filer Portal gateway instance. This name must be unique for each gateway instance.

SFILER_GUI_INSTANCE_NAME

Name of the GUI instance deployed on the gateway. This name must be unique for each gateway instance.

CONFIG_URL

S-Filer Portal's server URL. The URL's format is https://[host]:[port]. The port is the S-Filer Portal server's port that is visible by the container.

DOCKER_COMPOSE_WAIT

When set to "true", will programatically wait for S-Filer Portal's server to be up and running.

The .env environment file

In order to define the environment variables for each container in the S-Filer Portal for Docker, you can use a .env file.

.env

shell
# Database config
DATABASE_HOSTNAME=db
DATABASE_PORT=3306
DATABASE_NAME=sfiler
CONFIG_DB_USER=sfiler-user
CONFIG_DB_PASSWORD_FILE=/run/secrets/db_password

CONFIG_DB_URL="jdbc:mysql://db:3306/sfiler?useUnicode=true&characterEncoding=utf8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
CONFIG_DB_DRIVER=com.mysql.cj.jdbc.Driver
CONFIG_DB_HIBERNATE_DIALECT=org.hibernate.dialect.MySQL5InnoDBDialect

## Environment variables for MariaDB DBMS
# CONFIG_DB_URL="jdbc:mariadb://db:3306/sfiler"
# CONFIG_DB_DRIVER=org.mariadb.jdbc.Driver
# CONFIG_DB_HIBERNATE_DIALECT=org.hibernate.dialect.MariaDB103Dialect

## Environment variables for Microsoft SQL Server DBMS
# CONFIG_DB_URL="jdbc:sqlserver://db:1433;DatabaseName=sfiler;encrypt=false;sendStringParametersAsUnicode=false"
# CONFIG_DB_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
# CONFIG_DB_HIBERNATE_DIALECT=org.hibernate.dialect.SQLServer2012Dialect

## Environment variables for Oracle DB DBMS
# CONFIG_DB_URL="jdbc:oracle:thin:@db:1521:orcl"
# CONFIG_DB_DRIVER=oracle.jdbc.OracleDriver
# CONFIG_DB_HIBERNATE_DIALECT=org.hibernate.dialect.Oracle10gDialect

# Config CLI config
SFILER_CONFIG_CLI_HOSTNAME=sfilerConfigCliDemo

# Server config
CONFIGURATOR_START='true'
CONFIGURATOR_SSL='false'
SFILER_SERVER_PROTOCOL=http
SFILER_SERVER_HOSTNAME=sfilerServerDemo
SFILER_SERVER_INSTANCE_NAME=${SFILER_SERVER_HOSTNAME}
SFILER_SERVER_PORT=8088
CONFIGURATOR_PORT=8090
SFILER_ADMIN_EMAIL=admin@okiok.com
CONFIGURATOR_CLICKJACKING_PROTECTION='true'
CONFIGURATOR_HSTS_HEADER_SUPPORT='true'
CONFIGURATOR_HSTS_HEADER_SUPPORT_MAX_AGE=3600
CONFIGURATOR_SSL_CIPHER_MANAGEMENT_MODE=AUTOMATIC

# Gateway config
SFILER_GATEWAY_HOSTNAME=sfilerGatewayDemo
SFILER_GATEWAY_INSTANCE_NAME=${SFILER_GATEWAY_HOSTNAME}
SFILER_GUI_INSTANCE_NAME=${SFILER_GATEWAY_HOSTNAME}-GUI
SFILER_GATEWAY_PORT=8081
SFILER_GATEWAY_SSH_PORT=22
SFILER_GATEWAY_FTP_PORT=112
SFILER_GATEWAY_FTPS_EXPLICIT_PORT=21
SFILER_GATEWAY_FTPS_IMPLICIT_PORT=990
CONFIG_URL=https://${SFILER_SERVER_HOSTNAME}:${SFILER_SERVER_PORT}/
DOCKER_COMPOSE_WAIT="true"

# Gui config
SFILER_GUI_PROTOCOL=http
SFILER_GUI_PORT=8080

LOGS=silent

Volumes

The database driver must be supplied to both the server container and the CLI container. To do this, you need to link a directory containing the JDBC driver .jar file to the /app/ext/lib directories of both containers.

TIP

You can bind the same folder containing the database driver for both the configuration CLI and the server

The following table describes the Docker volumes declared in the docker-compose.yml file.

ServicePathUsage
cli/app/script.sfilerThe script to be executed the configuration CLI (optional if the CONFIG_CLI_COMMAND is set)
cli/app/license.txtA text file containing the S-Filer Portal license
cli/app/ext/libContains the JDBC driver
cli/app/configsContains basic conf files
server/app/logsContains the server's logs
server/app/ext/libContains the JDBC driver
gateway/app/logsContains the gateways' logs
gateway/app/configsContains basic conf files
License file

You must create a license.txt file containing your S-Filer Portal license and bind it to the /app/license.txt file inside of the config CLI container.

Configuration CLI Script

If you wish to provide multiple commands for the SFiler Configuration CLI to execute all at once, bind a script file to the /app/script.sfiler file.

The following script can setup the database for a whole S-Filer Portal environment.

WARNING

You need to provide at least either a single command to the CLI using an environment variable or a script file.

script.sfiler

shell
update-db-schema
generate-key-pair -a ${SFILER_SERVER_HOSTNAME}-key -d 10 -h ${SFILER_SERVER_HOSTNAME} -ks 4096

generate-key-pair -a gui-https-key -d 10 -h ${SFILER_GATEWAY_HOSTNAME} -ks 4096
generate-key-pair -a ftps-key -d 10 -h ${SFILER_GATEWAY_HOSTNAME} -ks 4096
generate-ssh-key -a sftp-ssh-key -ks 3072

add-server -n ${SFILER_SERVER_HOSTNAME} -h ${SFILER_SERVER_HOSTNAME} -lf /app/license.txt -e admin@test.com -s ${SFILER_SERVER_HOSTNAME}-key

add-gateway -n ${SFILER_GATEWAY_HOSTNAME}
add-gui -n ${SFILER_GATEWAY_HOSTNAME}-GUI

set-config -n ${SFILER_SERVER_HOSTNAME} -k cfg.server.transfer.service.rest.share.enabled -v true

set-config -n ${SFILER_GATEWAY_HOSTNAME} -k http.server.private.key -v gui-https-key
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k cfg.babelone.gateway.gui.interface.deploy -v true

set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftps.cipher.management.mode -v ${CONFIGURATOR_SSL_CIPHER_MANAGEMENT_MODE}

set-config -n ${SFILER_GATEWAY_HOSTNAME} -k http.server.enable -v true
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k http.server.port -v 8081
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k http.ssl -v false

set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftp.server.enable -v true
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftp.server.port -v ${SFILER_GATEWAY_FTP_PORT}

set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftps.server.enable -v true
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftps.server.private.key -v ftps-key

set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ssh.server.enable -v true
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ssh.server.key -v sftp-ssh-key
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ssh.server.port -v ${SFILER_GATEWAY_SSH_PORT}

set-config -n ${SFILER_GATEWAY_HOSTNAME}-GUI -k cfg.java.gui.sfiler.http.transfer.allowed -v true
set-config -n ${SFILER_GATEWAY_HOSTNAME}-GUI -k cfg.java.gui.portal.tree.share.enabled -v true

export-config -n ${SFILER_GATEWAY_HOSTNAME} -ccf ./configs/sfiler.conf
export-config -n ${SFILER_GATEWAY_HOSTNAME}-GUI -ccf ./configs/gui.conf

WARNING

The provided script.sfiler file will configure a working S-Filer Portal for Docker environment. However, you may not need to use your instance with all possible protocols such as FTP, SFTP, SSH etc. For example, if you do not need the FTPS protocol, remove the following lines:

script.sfiler

shell
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftps.server.enable -v true
set-config -n ${SFILER_GATEWAY_HOSTNAME} -k ftps.server.private.key -v ftps-key

Once the script has been executed, retrieve the configuration files of the various components. The files will be in the folder you linked to the sfiler-config-cli/configs directory of the container.

Secrets

As an alternative to convey sensitive information via environment variables, _FILE can be added to the end of certain environment variables, their value will then be read from a file. In this case, it is not necessary to define the corresponding environment variable.

Currently this is only possible for CONFIG_DB_PASSWORD variables.

Create a db_password.txt file containing the database's password in the same directory as the docker-compose.yml file

Docker Compose

Docker Compose is a Docker tool used to simplify the creation of a container stack. One can define containers as services, specify the containers' names, their images, their environment variables etc. Those options are specified in a file usually named docker-compose.yml.

Refer to the Docker Compose documentation for information about how to use Compose files.

Hereby is a docker-compose.yml file that describes a Docker container stack for the S-Filer Portal solution.

yaml
version: '3.9'
services:
  cli:
    image: 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-config-cli:SFILER_4_19_0
    container_name: ${SFILER_CONFIG_CLI_HOSTNAME}
    hostname: ${SFILER_CONFIG_CLI_HOSTNAME}
    volumes:
      - ./license.txt:/app/license.txt
      - ./script.sfiler:/app/script.sfiler
      - ./lib:/app/ext/lib
      - ./configs:/app/configs
    env_file: .env
    depends_on:
      db:
        condition: service_started
    networks:
      - docker_network_test
    secrets:
      - db_password

  server:
    image: 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-server:SFILER_4_19_0
    container_name: ${SFILER_SERVER_HOSTNAME}
    hostname: ${SFILER_SERVER_HOSTNAME}
    networks:
      - docker_network_test
    ports:
      - "28088:8088"
      - "28090:8090"
    volumes:
      - server-data:/app/logs
      - ./lib:/app/ext/lib
    env_file: .env
    secrets:
      - db_password
    depends_on:
      db:
        condition: service_healthy

  gateway:
    image: 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-gateway:SFILER_4_19_0
    container_name: ${SFILER_GATEWAY_HOSTNAME}
    hostname: ${SFILER_GATEWAY_HOSTNAME}
    networks:
      - docker_network_test
    ports:
      - "28081:8081"
      - "222:22"
      - "2112:112"
      - "221:21"
      - "2990:990"
    volumes:
      - gateway-data:/app/logs
      - ./configs:/app/configs
    env_file: .env
    depends_on:
      server:
        condition: service_started
      db:
        condition: service_healthy

  db:
    container_name: mysql
    hostname: ${DATABASE_HOSTNAME}
    image: mysql:latest
    networks:
      - docker_network_test
    restart: always
    volumes:
      - db-data:/var/lib/mysql:rw
    secrets:
      - db_password
    environment:
      MYSQL_ROOT_PASSWORD_FILE: ${CONFIG_DB_PASSWORD_FILE}
      MYSQL_DATABASE: ${DATABASE_NAME}
      MYSQL_USER: ${CONFIG_DB_USER}
      MYSQL_PASSWORD_FILE: ${CONFIG_DB_PASSWORD_FILE}
    healthcheck:
      test: [ "CMD", "mysqladmin" ,"ping", "-h", "localhost" ]
      retries: 99

secrets:
  db_password:
    file: db_password.txt

volumes:
  db-data:
  server-data:
  gateway-data:

networks:
  docker_network_test:
    driver: bridge

Once you have defined the .env environment file, you can provide it to Docker Compose in the docker-compose.yml file or by using the command line.

shell
docker-compose --env-file /path/to/.env up

Although this docker-compose.yml example includes the configuration CLI as one of its services, you can also run it as a container on its own. Simply ensure that your database is up and running.

TIP

In order to use other DBMS, change the following settings:

  1. Change the CONFIG_DB_URL, CONFIG_DB_DRIVER, and CONFIG_DB_HIBERNATE_DIALECT environment variables to the appropriate values for your DBMS.
  2. Either change the Docker image and the respective environment variables used by the db service provided in the docker-compose.yml file, or simply remove it if your database will be hosted outside of the Compose Stack.
Services

The following table describe the services defined in the provided Docker Compose file.

ServiceUsage
dbThe database used by the S-Filer Portal configuration
cliThe S-Filer Portal configuration CLI. Sets up the database to be used by the environment
serverThe S-Filer Portal's server
gatewayThe S-Filer Portal's gateway

Usage

Launching Docker Compose Stack

  1. Launch the database and the configuration CLI.
shell
docker-compose up --abort-on-container-exit db cli

This command will run the database and the configuration CLI Docker services. First, the database will start and configure itself to be ready to receive connections. Meanwhile, the configuration CLI will wait until the database is ready, and then proceed to configure it using the script that has been provided. The --abort-on-container-exit ensures that once the configuration CLI container exits, the database will shutdown by itself.

TIP

If you are using an another database than the one defined in the docker-compose.yml file provided, make sure to configure it accordingly. You can ensure that your database contains the user used by S-Filer Portal and the database to which he will be connecting by running the following command.

sql
CREATE USER 'sfiler-user'@'%' IDENTIFIED BY 'Passw0rd';
GRANT ALL PRIVILEGES ON *.* TO 'sfiler-user'@'%'WITH GRANT OPTION;
create database sfiler;

However, make sure these values match the one you declared in your .env file

  1. Launch the database, the server and the gateway
shell
docker-compose up -d db server gateway

Once the database is configured, there is no need to run the configuration CLI anymore, the command will restart the database. Afterwards, both the server and the gateway will be started. Once all containers are up and running, connections to the S-Filer Portal for Docker environment will work.

Endpoints

Once your S-Filer Portal for Docker environment is up and running, you can access it using the following endpoints:

EndpointService
https://sfilerServerDemo:28088/api/v2/docs/RESTful API (Documentation)
http://sfilerServerDemo:28090/Administrative Console
http://sfilerGatewayDemo:28081/End user GUI
sfilerGatewayDemo:222SSH
sfilerGatewayDemo:2112File Transfer Protocol (FTP)
sfilerGatewayDemo:221FTP Explicit port
sfilerGatewayDemo:2990FTP Implicit port