Skip to content

Docker test environment

The test environment runs, in containers, complete Riversoft STCP Gemini and Riversoft STCP DirectLink installations, with the database, the Riversoft STCP Gemini API and the Riversoft Console Portal. Use it to evaluate the products, train teams, reproduce problems and validate new versions before upgrading production.

For testing only

The environment runs without TLS, keeps passwords and secrets in the .env file and exposes the database on the host. Do not use these files as the basis for a production environment. For production, follow Installation and Security.

Download

Download the package with the environment files: stcp-test-environment.zip.

FileContents
DockerfileOracle Linux 9 base image with the Riversoft repository and one target per service.
docker-compose.ymlServices, volumes, ports and profiles of the environment.
.env.exampleVariable template: instance, database, secrets, licenses, ports and portal version.
entrypoints/Scripts that generate each component’s configuration from the package template and start the process in the foreground.
db/init/ and scripts/download-db-scripts.sh (Linux and macOS) or scripts/download-db-scripts.ps1 (Windows)Database creation with the Riversoft scripts for MariaDB and creation of the products’ database user. The Linux and macOS script uses unzip, bsdtar, python3 or, if none is available, a temporary container.
README.mdEnvironment summary, commands and links to this page in the three languages.

The environment was tested with Oracle Linux 9, MariaDB 10.11 and stcpdirectlink-portal 3.12.1-0.

What the environment runs

ServiceContentsHost port
dbMariaDB 10.11, with the configuration database and the log database.3306
stcpgemini-apiRiversoft STCP Gemini API and Riversoft Console Portal (-lite mode).33070
stcpgemini-serverRiversoft STCP Gemini Server and Riversoft STCP Gemini Rename.3305 (OFTP)
stcpdirectlinkRiversoft STCP DirectLink, Riversoft STCP DirectLink Portal and Riversoft STCP Gemini Rename.8080
    flowchart LR
    NAV[Browser] -->|33070| API[stcpgemini-api<br/>Gemini API and Console Portal]
    NAV -->|8080| DL[stcpdirectlink<br/>DirectLink and DirectLink Portal]
    PARC[OFTP partner] -->|3305| SRV[stcpgemini-server<br/>Gemini Server and Rename]
    API -->|Supervision 33050| SRV
    API -->|Supervision 33060| DL
    API --> DB[(db<br/>MariaDB)]
    SRV --> DB
    DL --> DB
    SRV --- CP[(Volume<br/>mailboxes)]
    DL --- CP
  

Riversoft STCP Gemini Server and Riversoft STCP DirectLink share the mailbox volume (/usr/local/stcp/data). The supervision ports are reachable only on the compose internal network, for the Riversoft STCP Gemini API.

Prerequisites

  • Docker with the Compose plugin.
  • On ARM computers, such as Macs with Apple Silicon, amd64 emulation enabled. Riversoft packages are distributed for x86_64, and the product services use platform: linux/amd64.
  • Access to repo.riversoft.com.br and www.riversoft.com.br during the build.
  • License file for Riversoft STCP DirectLink and, if applicable, for Riversoft STCP Gemini Rename, provided by Riversoft.
  • On Windows, Docker Desktop and PowerShell 5.1 or later. If the execution policy blocks the script, run powershell -ExecutionPolicy Bypass -File .\scripts\download-db-scripts.ps1.
  • The password encryption key (STCP_CONFIG_PASSPHRASE), used by all components. See Password encryption key.

Step by step

Prepare the files

unzip stcp-test-environment.zip && cd stcp-test-environment
cp .env.example .env
./scripts/download-db-scripts.sh
cp <license>.jwt licenses/stcpdirectlink-license.jwt

In .env, set the passwords, the secrets and the encryption key (STCP_CONFIG_PASSPHRASE). All components use the same value. Check in the 0-STCPGeminiCreateDatabase_*.sql script the names of the databases it creates and, if they differ, adjust STCP_DB_CONFIG and STCP_DB_LOG.

Start the database, the API and the Console Portal

docker compose up -d --build

On first startup, MariaDB runs the Riversoft scripts and creates the products’ database user.

Create the instance in the Riversoft Console Portal

Open http://localhost:33070, sign in with the default administrator operator (stcpadmin) and change the password. Then:

  1. Create the instance with the name set in STCP_INSTANCE.
  2. Register the network services for OFTP (port 3305) and for the Riversoft STCP DirectLink API (port 8080). When you create the API service, the Console Portal fills in the default paths for static pages and templates.
  3. Register the Supervision (gemini) service, on port 33050, and the Supervision (directlink) service, on port 33060, with the address 0.0.0.0 and a supervision credential for each one.
  4. In the API/Supervision registration, enter stcpgemini-server, port 33050, and stcpdirectlink, port 33060, with the supervision credentials.
  5. Register a test user.

See Supervision services.

Start Gemini Server and DirectLink

docker compose --profile transfer up -d --build

The two services do not start without the instance. See Instance creation.

Test

  • Riversoft STCP DirectLink Portal: http://localhost:8080/portal, with the test user.
  • Riversoft STCP DirectLink API: follow the Riversoft STCP DirectLink API quick start with http://localhost:8080/directlink/v2.
  • OFTP: configure a partner pointing to port 3305 on the host.

Remove the environment

When you finish testing, stop the containers and delete the volumes, the images created by the build and the environment network:

docker compose --profile transfer down -v --rmi local

Warning

-v deletes the environment database and mailboxes, including the instance and the registrations made in the Console Portal. To keep the data and only stop the environment, use docker compose --profile transfer down.

Then delete the stcp-test-environment folder, which contains the .env file with the passwords and the license file.

Generated configuration

On first startup, each container generates its configuration file from the template installed by the package (example-*.json), with the values from .env. This way, the configuration follows the installed version. To use your own file, mount it as a volume at the same path: if the file exists, it is kept.

ComponentFile
Riversoft STCP Gemini API/usr/local/stcpgemini-api/configs/config.json
Riversoft Console Portal/usr/local/stcpgemini-api/portal/app/configs/config.json
Riversoft STCP Gemini Server/usr/local/stcp/configs/stcpserver.config.json
Riversoft STCP DirectLink/usr/local/stcpdirectlink/configs/config.json
Riversoft STCP DirectLink Portal/usr/local/stcpdirectlink/static/portal/assets/configs/config.json
Riversoft STCP Gemini Rename/usr/local/stcpren/configs/config.json
docker-compose.yml
# Riversoft STCP Gemini and Riversoft STCP DirectLink test environment.
# Step 1:  docker compose up -d --build                    (database + API + Console Portal)
# Step 2:  create the instance and a test user in the Riversoft Console Portal
# Step 3:  docker compose --profile transfer up -d --build (Gemini Server + DirectLink)
name: stcp-test

x-stcp-env: &stcp-env
  STCP_INSTANCE: ${STCP_INSTANCE:?set STCP_INSTANCE in .env}
  STCP_DB_HOST: db
  STCP_DB_PORT: "3306"
  STCP_DB_USER: ${STCP_DB_USER:-stcp}
  STCP_DB_PASSWORD: ${STCP_DB_PASSWORD:?set STCP_DB_PASSWORD in .env}
  STCP_DB_CONFIG: ${STCP_DB_CONFIG:-GEMINI_DBConfig}
  STCP_DB_LOG: ${STCP_DB_LOG:-GEMINI_DBLog}
  STCP_CONFIG_PASSPHRASE: ${STCP_CONFIG_PASSPHRASE:?set STCP_CONFIG_PASSPHRASE in .env}
  STCPREN_LICENSE: ${STCPREN_LICENSE:-}
  TZ: ${TZ:-America/Sao_Paulo}

services:

  db:
    image: mariadb:10.11
    environment:
      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD:?set MARIADB_ROOT_PASSWORD in .env}
      STCP_DB_USER: ${STCP_DB_USER:-stcp}
      STCP_DB_PASSWORD: ${STCP_DB_PASSWORD}
      STCP_DB_CONFIG: ${STCP_DB_CONFIG:-GEMINI_DBConfig}
      STCP_DB_LOG: ${STCP_DB_LOG:-GEMINI_DBLog}
      TZ: ${TZ:-America/Sao_Paulo}
    command: ["--character-set-server=utf8mb4", "--collation-server=utf8mb4_unicode_ci"]
    volumes:
      - db-data:/var/lib/mysql
      - ./db/init:/docker-entrypoint-initdb.d:ro
    ports:
      - "${DB_PORT:-3306}:3306"
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 30s

  stcpgemini-api:
    platform: linux/amd64
    build:
      context: .
      target: stcpgemini-api
    environment:
      <<: *stcp-env
      STCP_API_PORT: "33070"
      STCP_PORTAL_API_URL: http://localhost:${API_PORT:-33070}
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "${API_PORT:-33070}:33070"
    restart: unless-stopped

  stcpgemini-server:
    platform: linux/amd64
    profiles: ["transfer"]
    build:
      context: .
      target: stcpgemini-server
    environment:
      <<: *stcp-env
    depends_on:
      db:
        condition: service_healthy
      stcpgemini-api:
        condition: service_started
    volumes:
      - mailboxes:/usr/local/stcp/data
      - ./licenses:/licenses:ro
    # Gemini supervision: reached only by stcpgemini-api, on the compose internal network.
    expose:
      - "33050"
    ports:
      - "${OFTP_PORT:-3305}:${OFTP_PORT:-3305}"
    restart: unless-stopped

  stcpdirectlink:
    platform: linux/amd64
    profiles: ["transfer"]
    build:
      context: .
      target: stcpdirectlink
      args:
        STCPDIRECTLINK_PORTAL_VERSION: ${STCPDIRECTLINK_PORTAL_VERSION:-3.12.1-0}
    environment:
      <<: *stcp-env
      STCPDIRECTLINK_SECRET: ${STCPDIRECTLINK_SECRET:?set STCPDIRECTLINK_SECRET in .env}
      STCPDIRECTLINK_LICENSE_FILE: /licenses/${STCPDIRECTLINK_LICENSE:-stcpdirectlink-license.jwt}
      STCPDIRECTLINK_PORTAL_API_URL: http://localhost:${DIRECTLINK_PORT:-8080}/directlink/v2
    depends_on:
      db:
        condition: service_healthy
      stcpgemini-api:
        condition: service_started
    volumes:
      - mailboxes:/usr/local/stcp/data
      - ./licenses:/licenses:ro
    # DirectLink supervision: reached only by stcpgemini-api, on the compose internal network.
    expose:
      - "33060"
    ports:
      - "${DIRECTLINK_PORT:-8080}:${DIRECTLINK_PORT:-8080}"
    restart: unless-stopped

volumes:
  db-data:
  mailboxes:

Useful commands

docker compose --profile transfer ps
docker compose --profile transfer logs -f stcpgemini-server stcpdirectlink
docker compose --profile transfer down       # stops, keeping the volumes
docker compose --profile transfer down -v    # stops and deletes database and mailboxes

Troubleshooting

SymptomProbable causeSolution
stcpgemini-server or stcpdirectlink keeps restarting.The instance does not exist or its name differs from STCP_INSTANCE.Create the instance in the Console Portal with the same name and start the transfer profile again.
The Console Portal does not show supervision.The supervision services or the API/Supervision registration are not configured.Check the services in the instance and use the container names in the API/Supervision registration.
Riversoft STCP DirectLink Portal does not open.The static pages path of the API service is not the default.Check that the path is /usr/local/stcpdirectlink/static, with no trailing slash.
The build fails when installing packages on an ARM computer.amd64 emulation is not enabled.Enable emulation in Docker.