On this page
settings
Configuration Reference
Complete reference for all environment variables used to configure a self-hosted rtCloud deployment.
All configuration is done through environment variables in the .env file at the root of your deployment directory. Docker Compose reads this file automatically — no --env-file flag is needed.
Variables marked required must be set before starting the containers. All others have defaults and are optional.
Project
These variables define the identity and access point of your rtCloud instance.
| Variable | Default | Required | Description |
|---|---|---|---|
PROJECT_ID | — | Yes | Unique identifier for this deployment. No spaces or special characters. Used as a prefix for internal naming. |
PROJECT_URL | — | Yes | Domain name or IP address where users access the app (e.g., rtcloud.example.com or 192.168.1.100). |
PROJECT_TYPE | rtsurvey | No | Platform variant to activate. Options: rtwork, rtsurvey, rthome. |
PROJECT_PORT | 80 | No | Port the application listens on inside the container. Do not change unless you know what you are doing. |
HTTP_PROTOCOL | https | No | Protocol used to construct internal URLs. Set to http if you are not using SSL. |
Database
MySQL connection credentials. The database is managed automatically by the MySQL container — you only need to set strong passwords.
| Variable | Default | Required | Description |
|---|---|---|---|
MYSQL_DATABASE | smartsurvey | No | Name of the application database. |
MYSQL_USER | smartsurvey | No | MySQL user for the application. |
MYSQL_PASSWORD | — | Yes | Password for MYSQL_USER. Use a strong, unique value. |
MYSQL_ROOT_PASSWORD | — | Yes | MySQL root password. Required for database initialization and admin operations. |
MYSQL_HOST | mysql | No | MySQL hostname. Use the default unless you are connecting to an external database. |
MYSQL_PORT | 3306 | No | MySQL port. |
Admin Account
The admin account is created automatically on the first boot of a fresh database.
| Variable | Default | Required | Description |
|---|---|---|---|
ADMIN_PASSWORD | admin | Yes | Password for the built-in admin user. Set this before first boot. Has no effect if the database already exists. |
After first login, change the admin password from the Account Settings page in the web UI.
Ports
Control which host ports the application binds to.
| Variable | Default | Description |
|---|---|---|
APP_PORT | 8080 | Host port for the main web UI. Change this if port 8080 is already in use on your server. |
SHINY_PORT | 3838 | Host port for the Shiny analytics server. |
Runtime
| Variable | Default | Description |
|---|---|---|
RUN_ENV | prod | Runtime environment. Use prod for production deployments, dev for local development. |
RUN_MODE | admin | Container role. admin runs the full stack (web + queue + cron). worker runs background processing only (for horizontal scaling). |
TZ | Asia/Ho_Chi_Minh | Server timezone. Affects log timestamps, cron schedules, and date display. Use a TZ database name (e.g., UTC, America/New_York, Europe/London). |
LOG_LEVEL | info | Application log verbosity. Options: debug, info, warning, error. |
COMPOSE_PROJECT_NAME | rtcloud | Prefix applied to all Docker container and volume names. Change this when running multiple rtCloud instances on the same host. |
RESTART_POLICY | unless-stopped | Docker container restart behavior. Options: no, always, on-failure, unless-stopped. |
RTCLOUD_IMAGE | rtawebteam/rta-smartsurvey:survey-dockerize | Docker image to use. Change the tag to pin a specific version. |
REQUIRE_LICENSE | false | Enable license key validation on startup. Contact RTA for license information. |
Security
| Variable | Default | Description |
|---|---|---|
CSRF_VALIDATION_ENABLED | true | Enable CSRF token validation. Keep this true in production. Set to false only in local development if you encounter 400 CSRF token could not be verified errors. |
GII_ENABLED | false | Enable the Yii framework code generator tool. Never enable in production. |
SSO — Embedded Keycloak
Enable the bundled Keycloak container for full-featured enterprise SSO. Requires a domain with HTTPS.
| Variable | Default | Description |
|---|---|---|
EMBED_KEYCLOAK | false | Set to true to start the embedded Keycloak container. Activates the embed-keycloak Docker Compose profile. |
KEYCLOAK_URL | — | Full URL of the Keycloak server (e.g., https://rtcloud.example.com/auth). |
KEYCLOAK_REALM | — | Keycloak realm name (e.g., rtsurvey). |
KEYCLOAK_CLIENT_ID | — | Keycloak client ID for the rtCloud application. |
KEYCLOAK_CLIENT_SECRET | — | Keycloak client secret. Generate this from the Keycloak admin console. |
KEYCLOAK_ADMIN_USER | admin | Keycloak administrator username. |
KEYCLOAK_ADMIN_PASSWORD | — | Keycloak administrator password. |
KEYCLOAK_DB | keycloak | Database name for Keycloak. Created automatically on first boot. |
KEYCLOAK_DB_USER | keycloak | Database user for Keycloak. |
KEYCLOAK_DB_PASSWORD | — | Database password for the Keycloak user. |
KC_HOSTNAME | — | Keycloak frontend URL (e.g., https://rtcloud.example.com/auth). |
KC_HOSTNAME_STRICT | false | Enforce strict hostname matching. Set to true in production with a fixed domain. |
See SSO Authentication for the complete setup guide.
SSO — External OIDC Provider
Connect to an existing OIDC-compatible identity provider (Supabase, Auth0, Authentik, Okta, etc.).
| Variable | Default | Description |
|---|---|---|
OIDC_ISSUER_URL | — | OIDC issuer discovery URL (e.g., https://accounts.google.com). |
OIDC_CLIENT_ID | — | Client ID registered in your identity provider. |
OIDC_CLIENT_SECRET | — | Client secret from your identity provider. |
OIDC_SCOPE | openid profile email | Space-separated list of OIDC scopes to request. |
OIDC_REDIRECT_URI | — | Callback URL for the web app (e.g., https://rtcloud.example.com/auth/callback). |
OIDC_MOBILE_CLIENT_ID | — | Separate client ID for the rtSurvey mobile app. |
OIDC_MOBILE_REDIRECT_URI | — | Mobile app callback URI (e.g., vn.rta.rtsurvey.auth://callback). |
OPEN_REGISTRATION | false | Automatically create rtCloud accounts for users who authenticate via OIDC for the first time. |
OIDC_AUTHORIZATION_ENDPOINT | — | Override the authorization endpoint URL (leave blank to use discovery). |
OIDC_TOKEN_ENDPOINT | — | Override the token endpoint URL (leave blank to use discovery). |
OIDC_USERINFO_ENDPOINT | — | Override the userinfo endpoint URL (leave blank to use discovery). |
SSO — Azure Active Directory
| Variable | Description |
|---|---|
AZURE_CLIENT_ID | Azure AD application (client) ID. |
AZURE_TENANT_ID | Azure AD directory (tenant) ID. |
Optional Integrations
Stata
| Variable | Default | Description |
|---|---|---|
STATA_ENABLED | false | Enable Stata statistical software integration for data analysis. |
STATA_BIN_PATH | /usr/bin/stata | Absolute path to the Stata binary inside the container. |
Elasticsearch
| Variable | Description |
|---|---|
ES_HOST | Elasticsearch host (e.g., http://elasticsearch:9200). |
ES_PORT | Elasticsearch port. |
Matomo Analytics
| Variable | Description |
|---|---|
PIWIK_URL | Matomo (Piwik) server URL. |
PIWIK_ID | Matomo site ID. |
PIWIK_SECRET | Matomo authentication token. |
OpenCPU (R Computation)
| Variable | Description |
|---|---|
OCPU_HOST | OpenCPU server URL for R-based statistical computation. |
RtBox Integration
| Variable | Description |
|---|---|
RTBOX_HOST | RtBox service host URL. |
RTBOX_USER_API | RtBox user API key. |
RTBOX_BASIC_AUTH | Basic authentication credentials for RtBox. |
Matrix Messaging
| Variable | Description |
|---|---|
MATRIX_HOMESERVER_HOST | Matrix homeserver host. |
MATRIX_HOMESERVER_PORT | Matrix homeserver port. |
Data Volumes
All application data is stored in named Docker volumes. Volumes are automatically created on first startup and persist across container restarts and updates.
| Volume | Mount Point | Contents |
|---|---|---|
rtcloud_mysql_data | /var/lib/mysql | MySQL database files |
rtcloud_uploads | …/uploads | Files uploaded by survey respondents |
rtcloud_audios | …/audios | Audio recordings |
rtcloud_downloads | …/downloads | Generated export files |
rtcloud_gallery | …/gallery | Gallery images |
rtcloud_voicemail | …/voicemail | Voicemail recordings |
rtcloud_analytics | …/analytics | Analytics data |
rtcloud_aggregate | …/aggregate | Aggregated survey results |
rtcloud_converter | …/converter | Data conversion outputs |
rtcloud_shiny_data | /srv/shiny-server/smartsurvey | Shiny server R scripts |
rtcloud_shiny_logs | /var/log/shiny-server | Shiny server logs |
rtcloud_assets | …/assets | Web assets (CSS, JS) |
rtcloud_runtime | …/protected/runtime | Application runtime cache |
rtcloud_cache | …/cache | Application cache |
rtcloud_tmp | …/tmp | Temporary files |
Volume names are prefixed by the value of COMPOSE_PROJECT_NAME (default: rtcloud).
List all volumes for your deployment:
docker volume ls | grep rtcloud
Was this page helpful?