Docker agent (SaaS)

This topic describes how RAC/M Identity as a Service (SaaS) customers deploy the ICF connector server (ConnId) on their own infrastructure using the racm-icf-server-agent Docker image. The agent synchronizes connector artifacts from RAC/M, registers with RAC/M, and opens a secure tunnel so RAC/M can reach the connector server running in your environment.

SaaS only

The ICF server agent feature applies only to RAC/M Identity as a Service (SaaS). It is not supported for on-premises or private-cloud RAC/M Identity deployments.

Create the agent server in RAC/M

1. Sign in to the RAC/M Identity management console with an account that can manage ICF servers.
2. Open Configuration → Target system servers.

3. Click + to create a new ICF server.
4. Under Details, enter a Name for this server (for example, the environment or application it will serve).
5. Under Connection, set Connection type to Agent.
   Host, port, key, and secure communication settings for agent connections are managed by RAC/M and are not edited on this screen.

6. Click Save.

The Agent Docker command section does not show any command until you save.

Obtain the Docker command and bearer secret

1. After a successful save, locate Agent Docker command on the same page.
2. Click Copy command to copy the complete command.

3. Treat the command as highly confidential: it contains the bearer token RAC/M uses to authenticate your agent. Store it in a secrets manager or secure runbook, not in email or chat.
4. Note the warning shown in the console: the full bearer secret may not remain visible after you leave or refresh the page. Copy and secure the command before navigating away.
5. If you must invalidate a leaked secret, use Rotate bearer token on the server detail page. After rotation, restart your agent containers with the new command; the previous secret stops working immediately.

Run the agent in your environment

1. On the Linux host or cluster where ConnId should run, install Docker (or a compatible container runtime).

2. Load the agent image from the archive OKIOK provides. OKIOK supplies a gzip tarball of the Docker image (for example, icf-image.tar.gz). Load it into Docker:

   gunzip -c icf-image.tar.gz | docker load

3. Paste and run the command you copied from Agent Docker command, or translate it into Docker Compose, Kubernetes, or your standard deployment template while preserving all -e environment variables.

4. Allow the container to reach RAC/M over HTTPS. On startup, the image waits for the agent-files HTTP endpoint (unless you disable the wait), runs rclone sync, then registration and the tunnel.

5. Optionally monitor container logs for successful sync, registration, and tunnel startup.

6. In the console, check Last time the agent reached RAC/M on the ICF server detail page; it should update after the agent connects successfully.

7. Use Test on the ICF server (if available for your version) to validate connectivity from RAC/M to the connector server through the tunnel.

Agent image environment variables

The Agent Docker command from RAC/M supplies the required settings. The tables below list every environment variable the racm-icf-server-agent image recognizes if you need to add or override values (for example, in Compose or Kubernetes).

RAC/M connection

The container will not start unless these are set:

Variable	Description
RACM_HOST	RAC/M hostname, or bracketed IPv6. Do not include scheme or port here.
RACM_AGENT_ICF_SERVER_BEARER_TOKEN	Bearer secret for agent file access and registration; treat as confidential.

Optional:

Variable	Default	Description
RACM_SCHEME	https	HTTP scheme for RAC/M (http or https). Used for URLs and, when WSTUNNEL_SERVER_HOST is unset, to choose ws vs wss for the tunnel client.
RACM_PORT	(scheme default)	HTTP(S) port for RAC/M. If unset or blank, defaults to 443 when RACM_SCHEME is https (the default) and 80 when http. If set, use decimal digits only (1–65535).

HTTP readiness before agent-files sync (optional)

Before rclone runs, the image probes the RAC/M agent-files HTTP endpoint (bounded wait). Tune that behavior with:

Variable	Default	Description
RACM_SERVER_WAIT_SECS	120	Maximum seconds to wait for HTTP readiness; 0 skips the wait.
RACM_SERVER_PROGRESS_SECS	15	Emit a progress line every N seconds while waiting; 0 disables.
RACM_SERVER_READY_COUNT	3	After the first successful probe, require this many successive passes (1 s apart) before sync. Use 1 for “first success wins”.
RACM_SERVER_SETTLE_SECS	0	Extra sleep (seconds) after readiness and before sync.
RACM_SERVER_PROBE_DEBUG	(unset)	If 1, true, or yes (case-insensitive), failed probes use curl -S so stderr includes curl error detail.

rclone tuning for agent-files sync (optional)

Variable	Default	Description
RACM_ICF_FILES_RCLONE_TRANSFERS	4	rclone --transfers for agent-files sync.
RACM_ICF_FILES_RCLONE_CHECKERS	4	rclone --checkers.

Periodic sync and ConnId restart (optional)

Variable	Default	Description
RACM_ICF_SYNC_INTERVAL_SECS	300	Seconds between incremental sync attempts.
RACM_ICF_ICF_SIGTERM_WAIT_SECS	60	After SIGTERM to ConnId, seconds to wait before SIGKILL.

Wstunnel client (optional)

The reverse tunnel rule (-R) is not an environment variable; it comes from RAC/M registration. These variables control how the wstunnel client connects to the tunnel server:

Variable	Default	Description
WSTUNNEL_SERVER_HOST	(unset)	Hostname for the WebSocket control URL. If unset, RACM_HOST is used.
WSTUNNEL_SERVER_PORT	8000	TCP port for the WebSocket control connection.
WSTUNNEL_CLIENT_WS_SCHEME	(unset)	If set, must be ws or wss. If unset, behavior depends on WSTUNNEL_SERVER_HOST and RACM_SCHEME.
WSTUNNEL_EXTRA_ARGS	(unset)	Extra arguments appended to the wstunnel client command.
WSTUNNEL_SERVER_CONNECT_WAIT_SECS	120	Wait for the tunnel server TCP port before starting the client; 0 skips.
WSTUNNEL_WAIT_PROGRESS_SECS	15	Progress line interval while waiting; 0 disables.
WSTUNNEL_LOG_LEVEL	INFO	wstunnel log level (wstunnel.log under the agent logs directory).

Install paths (optional)

Variable	Default (image)	Description
ICF_AGENT_ROOT	/opt/icf-agent	Agent install root.
ICF_ROOT	/opt/icf-agent/icf-server	ConnId bundle directory.

Using connectors with this server

Configure your ICF connectors to use this ICF server instance like any other server: Configuration → ICF Connectors, choose the connector, and select this server under ICF Server. See Connectors for the general workflow.