Skip to main content

External Services Installation

External services mode runs only the four Soln products and the same-origin reverse proxy; PostgreSQL, Temporal, and object storage stay in the tenant's own systems. Choose it when those services must join existing backup, monitoring, and access-control systems.

Prerequisites and Execution Location​

This route is for operations teams with existing PostgreSQL, Temporal, MinIO, and document parsing services. For a first deployment without those services, use Single-Machine Installation. Your team owns provisioning, backups, certificates, and KMS for external dependencies.

Run commands in the same root shell on the Ubuntu 24.04 deployment server. Complete Server Environment and domain and HTTPS preparation, without running the single-machine data disk or installation steps.

Collect the actual Control Plane API address, tenant subdomain, member email with tenant.runtime.deployment.manage, access domain, and external service endpoints and credentials. Replace all example values.

Step 0: Log In, Register, and Prepare Files​

npm install -g @soln/cli@latest
sl version
sl deployment login --base-url https://api.solncn.com \
  --tenant example --email operator@example.com --method email
sl deployment status --json

Confirm the tenant is correct and has no registration before proceeding:

sl deployment register --dir /opt/soln-tenant-runtime \
  --deployment-target server --deployment-mode externalServices \
  --runtime-origin https://runtime.customer.example.com
sl deployment prepare --dir /opt/soln-tenant-runtime
cd /opt/soln-tenant-runtime
cp -n .env.example .env
chmod 0600 .env

Keep .soln-install-setup.json, which holds the Agent secret for installation. If registration or configuration already exists, inspect the original directory and unfinished installation first; do not overwrite with --force. Do not put secrets into command arguments or AI prompts.

Step 1: Prepare PostgreSQL​

Create a dedicated database and account for this tenant Runtime. The account needs the rights to create and alter tables, because the Database Migrator applies the tenant schema.

psql "postgresql://soln_user@db-host:5432/soln_customer_runtime?sslmode=verify-full" -c 'select 1'
  • Success: prints 1 and exits; replace the user, host, port, and database with your values
  • could not translate host name — DNS or the hostname is wrong
  • no pg_hba.conf entry for host — the database does not allow this host yet
  • password authentication failed — wrong credentials
  • FATAL: database "soln_customer_runtime" does not exist — create the database first

Write the connection string into .env. TLS is mandatory: soln doctor rejects every sslmode other than verify-full.

SOLN_DEPLOYMENT_MODE=externalServices
DATABASE_URL=postgresql://soln_user:strong_password@db-host:5432/soln_customer_runtime?sslmode=verify-full
  • sslmode=verify-full also verifies the certificate hostname; make sure the CA that signed the server certificate is trusted inside the deployment image, have your database administrator verify private-CA trust; copying a CA into the Temporal certificate directory does not configure PostgreSQL trust
  • The Database Migrator connects first and applies the schema; Runtime Service and the Workflow Worker never run DDL

Step 2: Prepare Temporal​

Create a namespace for this tenant and note the endpoint the Workflow Worker will use.

TEMPORAL_ADDRESS=temporal.customer.example.com:7233
  • Use the frontend address, not the Web UI, and keep the :7233 port
  • The Workflow Worker needs outbound access to that address from the host
  • For TLS or mTLS, mount the CA and the optional client key pair under /run/secrets and keep every certificate file at mode 0600
  • soln doctor fails with DEPLOYMENT_ENV_INCOMPLETE when TEMPORAL_ADDRESS is still a placeholder

The template mounts the deployment's secrets/ directory at /run/secrets in Runtime and Worker. Obtain actual certificates from your administrator and configure .env:

install -d -m 0700 /opt/soln-tenant-runtime/secrets
TEMPORAL_NAMESPACE=soln
TEMPORAL_TLS_ENABLED=true
TEMPORAL_TLS_SERVER_NAME=temporal.customer.example.com
TEMPORAL_TLS_CA_PATH=/run/secrets/temporal-ca.pem
TEMPORAL_TLS_CERT_PATH=/run/secrets/temporal-client.pem
TEMPORAL_TLS_KEY_PATH=/run/secrets/temporal-client-key.pem

Host files are secrets/temporal-ca.pem, secrets/temporal-client.pem, and secrets/temporal-client-key.pem, with mode 0600. Leave CERT and KEY empty for server TLS without client certificates. CA_PATH can be empty when the CA is publicly trusted. Create the namespace in Temporal first; use the authentication method supplied by its administrator.

Step 3: Prepare Object Storage​

Prepare a bucket, an access key pair, a server endpoint that Runtime Service can reach, a browser endpoint that users can reach, and KMS-backed encryption.

FILES_STORAGE_BACKEND=minio
FILES_MINIO_ENDPOINT=https://s3.customer.example.com
FILES_MINIO_BROWSER_ENDPOINT=https://files.customer.example.com
FILES_MINIO_BUCKET=soln
FILES_MINIO_ACCESS_KEY=your-access-key
FILES_MINIO_SECRET_KEY=your-secret-key
FILES_MINIO_REGION=us-east-1
FILES_MINIO_FORCE_PATH_STYLE=true
FILES_MINIO_SERVER_SIDE_ENCRYPTION=AES256
  • Both endpoints must use HTTPS, and they may be different hostnames: one is called server to server, the other is signed for the browser
  • FILES_MINIO_SERVER_SIDE_ENCRYPTION must be AES256; soln doctor rejects anything else. Configure the tenant-owned MinIO KES backend with Google Cloud KMS before installation; Soln cannot verify that external KES configuration.
  • soln prepare writes storage-iam-policy.example.json into the deployment directory as a starting point for the bucket policy

Check the endpoints from the host before installing:

curl -fsS -o /dev/null -w '%{http_code}\n' https://s3.customer.example.com
  • Any HTTP status means the endpoint is reachable; 000 means it is not
  • Could not resolve host — DNS problem; SSL certificate problem — certificate problem

Step 4: Complete Configuration and Confirm Encryption​

Edit .env with a text editor on the server. Fill in the actual values from steps 1–3 and keep the generated identity configuration; do not recreate the entire file.

External mode also requires a document parser reachable from Runtime. The template uses the docling-serve-v1.30.0 protocol:

DOCUMENT_PARSER_URL=https://docling.customer.internal
DOCUMENT_PARSER_VERSION=docling-serve-v1.30.0

Have the service administrator confirm the endpoint and compatible API; do not leave the example hostname. After confirming at-rest encryption for the database, Temporal persistence, and object storage, set:

SOLN_DATA_AT_REST_ENCRYPTED=true

This is an administrator's confirmation, not an action that enables encryption. Confirm .env has mode 0600, database TLS is valid, the Temporal namespace exists, and storage keys have bucket permissions. Stop if these checks fail.

Step 5: Install with the Private Setup File​

sl install --dir /opt/soln-tenant-runtime \
  --setup-file /opt/soln-tenant-runtime/.soln-install-setup.json --yes

The command preserves configured .env values, populates identity and internal secrets, and runs doctor first. A manual doctor before first installation may fail because internal secrets have not yet been generated; do not use example secrets to bypass checks. If doctor fails, installation stops before migrations.

After checks pass, the CLI verifies signed releases and images, pulls images, runs Database Migrator, starts products and the proxy, waits for /health/ready, and writes .soln/deployment.json.

  • Success: Soln Tenant Runtime <version> is ready.
  • DEPLOYMENT_SETUP_FILE_MISMATCH: inspect identity, target, and mode in .env and the setup file; do not change identity to fit a wrong directory.
  • DEPLOYMENT_ENV_INCOMPLETE: fill in the listed missing values and retry the same installation command; do not re-register.

Step 6: Verify​

soln status --dir /opt/soln-tenant-runtime
  • Success: the installed release, the four products, and ready
curl -fsS -o /dev/null -w '%{http_code}\n' \
  https://runtime.customer.example.com/health/ready

Confirm HTTP 200, open the tenant address, and test login, then run:

(
  set -e
  sl doctor --dir /opt/soln-tenant-runtime --json
  sl status --dir /opt/soln-tenant-runtime --check --json
  rm /opt/soln-tenant-runtime/.soln-install-setup.json
  sl deployment logout
)

Only remove the setup file after the checks succeed. Keep .env, secrets/, and .soln/deployment.json.

Operations Notes​

  • Backup the tenant database with the tenant's own tools; soln upgrade writes its own pre-migration dump to <deployment>/.soln/backups, and soln rollback restores it
  • Rotating the database, Temporal, or object storage credentials means updating .env and running a lifecycle operation, so plan the rotation window
  • Keep .env at mode 0600 and never commit it; it holds the database password and the Agent secret

Next: Server Upgrade and Rollback.

To change an installed Runtime’s public address, see Change the Tenant Domain.