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.
| File | Contents |
|---|---|
Dockerfile | Oracle Linux 9 base image with the Riversoft repository and one target per service. |
docker-compose.yml | Services, volumes, ports and profiles of the environment. |
.env.example | Variable 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.md | Environment 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
| Service | Contents | Host port |
|---|---|---|
db | MariaDB 10.11, with the configuration database and the log database. | 3306 |
stcpgemini-api | Riversoft STCP Gemini API and Riversoft Console Portal (-lite mode). | 33070 |
stcpgemini-server | Riversoft STCP Gemini Server and Riversoft STCP Gemini Rename. | 3305 (OFTP) |
stcpdirectlink | Riversoft 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,
amd64emulation enabled. Riversoft packages are distributed forx86_64, and the product services useplatform: linux/amd64. - Access to
repo.riversoft.com.brandwww.riversoft.com.brduring 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.jwtIn .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 --buildOn 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:
- Create the instance with the name set in
STCP_INSTANCE. - Register the network services for OFTP (port
3305) and for the Riversoft STCP DirectLink API (port8080). When you create the API service, the Console Portal fills in the default paths for static pages and templates. - Register the Supervision (gemini) service, on port
33050, and the Supervision (directlink) service, on port33060, with the address0.0.0.0and a supervision credential for each one. - In the API/Supervision registration, enter
stcpgemini-server, port33050, andstcpdirectlink, port33060, with the supervision credentials. - Register a test user.
See Supervision services.
Start Gemini Server and DirectLink
docker compose --profile transfer up -d --buildThe 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
3305on 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 localWarning
-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.
| Component | File |
|---|---|
| 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 mailboxesTroubleshooting
| Symptom | Probable cause | Solution |
|---|---|---|
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. |