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:
- Docker for GNU/Linux, macOS or Docker Desktop on Windows
- The Amazon Web Services (AWS) CLI
- 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.
- Docker Compose (optional, depends on your choice of deployment)
Docker images
The S-Filer Portal solution for Docker works using 3 Docker images:
sfiler-config-cli
, which encapsulates the Configuration CLI for the database's setupsfiler-server
, which encapsulates the S-Filer Portal's serversfiler-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:
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:
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:
docker pull 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-config-cli:SFILER_4_19_0
docker pull 550720984821.dkr.ecr.ca-central-1.amazonaws.com/sfiler-server:SFILER_4_19_0
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 system | Link to download JDBC Driver |
---|---|
MySQL | https://dev.mysql.com/downloads/connector/j/ |
MariaDB | https://mariadb.com/kb/en/about-mariadb-connector-j/ |
Microsoft SQL Server | https://docs.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15 |
Oracle DB | https://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_MODE | Description |
---|---|
AUTOMATIC | The 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. |
CUSTOM | The server will use the cipher suites specified in the CONFIGURATOR_SSL_CUSTOM_CIPHERS parameter. |
JVM_DEFAULT_CIPHERS | The 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
# 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.
Service | Path | Usage |
---|---|---|
cli | /app/script.sfiler | The script to be executed the configuration CLI (optional if the CONFIG_CLI_COMMAND is set) |
cli | /app/license.txt | A text file containing the S-Filer Portal license |
cli | /app/ext/lib | Contains the JDBC driver |
cli | /app/configs | Contains basic conf files |
server | /app/logs | Contains the server's logs |
server | /app/ext/lib | Contains the JDBC driver |
gateway | /app/logs | Contains the gateways' logs |
gateway | /app/configs | Contains 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
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
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.
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.
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:
- Change the
CONFIG_DB_URL
,CONFIG_DB_DRIVER
, andCONFIG_DB_HIBERNATE_DIALECT
environment variables to the appropriate values for your DBMS. - Either change the Docker image and the respective environment variables used by the
db
service provided in thedocker-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.
Service | Usage |
---|---|
db | The database used by the S-Filer Portal configuration |
cli | The S-Filer Portal configuration CLI. Sets up the database to be used by the environment |
server | The S-Filer Portal's server |
gateway | The S-Filer Portal's gateway |
Usage
Launching Docker Compose Stack
- Launch the database and the configuration CLI.
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.
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
- Launch the database, the server and the gateway
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:
Endpoint | Service |
---|---|
https://sfilerServerDemo:28088/api/v2/docs/ | RESTful API (Documentation) |
http://sfilerServerDemo:28090/ | Administrative Console |
http://sfilerGatewayDemo:28081/ | End user GUI |
sfilerGatewayDemo:222 | SSH |
sfilerGatewayDemo:2112 | File Transfer Protocol (FTP) |
sfilerGatewayDemo:221 | FTP Explicit port |
sfilerGatewayDemo:2990 | FTP Implicit port |