Configuration

Surfly supports extensive configuration options through environment variables defined in the ~/surfly/config.env file. This file is mounted as an environment file in all Surfly containers, making the configuration available across all services.

Configuration Structure

Environment variables in the config.env file follow standard shell environment format:

# Comments start with hash
VARIABLE_NAME=value

# No spaces around the equals sign
DATABASE_HOST=localhost

# Do not use quotes for values with spaces
CUSTOM_MESSAGE=Welcome to Surfly

# Boolean values use true/false
ENABLE_FEATURE=true

# Numeric values don't need quotes
PORT_NUMBER=8080

Required Configuration

At minimum, your config.env file must contain the following credentials and settings:

# Surfly client credentials
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

# Used in Dashboard and Studio to secure signed data. Must be kept secure.
SECRET_KEY=your_secret_key

# Authorization tokens for internal dashboard API.
DASHBOARD_AUTH_TOKEN=generated_random_value

# Authorization token for internal cobro API.
COBRO_AUTH_TOKEN=generated_random_value

# Space separated list of the DNS servers.
NGINX_DNS_RESOLVERS=1.1.1.1 8.8.8.8

Common Configuration Options

Database Configuration

Override default database connection settings:

# PostgreSQL configuration
DB_CONNECT_STRING=surfly = host=127.0.0.1 dbname=surfly user=surfly_app
CONSOLE_API_DB_CONNECT_STRING=console = host=127.0.0.1 dbname=console user=surfly_app

Redis Configuration

Configure Redis connection parameters:

# Redis server settings
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Configuration Validation

Syntax Validation

Validate your configuration file syntax:

# Check for syntax errors
bash -n ~/surfly/config.env

# Source file to test variable expansion
source ~/surfly/config.env && echo "Configuration loaded successfully"

Apply Configuration Changes

After modifying configuration:

Restart Services

# Restart all Surfly services to load new configuration
systemctl --user restart ss-surfly.target

# Or restart specific service
systemctl --user restart ss-haproxy

Debugging Configuration

Check how configuration is loaded in containers:

# View environment variables in running container
podman exec ss-django env | sort

# Check specific configuration values
podman exec ss-haproxy env | grep -E "(CLIENT_ID|SERVER_NAMES)"

Security Best Practices

File Permissions

Secure your configuration files:

# Restrict access to configuration file
chmod 600 ~/surfly/config.env

# Verify permissions
ls -la ~/surfly/config.env

Base Configuration Template

The following is the base default configuration template for Surfly, showing all available configuration parameters that can be customized:


# =============================================================================
# --- Mandatory Configuration
# =============================================================================

# The client ID and secret used to authenticate in Surfly build system and registry.
CLIENT_ID=
CLIENT_SECRET=

# Used in Dashboard and Studio to secure signed data. Must be kept secure.
SECRET_KEY=

# Authorization tokens for internal dashboard API.
DASHBOARD_AUTH_TOKEN=

# Authorization token for internal cobro API.
COBRO_AUTH_TOKEN=

# Space separated list of the DNS servers.
NGINX_DNS_RESOLVERS=1.1.1.1 8.8.8.8

# =============================================================================
# --- Security and Rate Limiting
# =============================================================================

# Rate limit REST API requests to Dashboard and Studio in haproxy, req/min.
REST_API_RATE_LIMIT=100

# Allows Surfly to create sessions on private resources.
# Note: If you enable this option, ensure your firewall configuration is strict
# and the server cannot be used by external users to request internal resources.
# This can also be a space-separated list of private IP addresses and subnets to
# allow.
ALLOW_PRIVATE_RESOURCES=

# HTTP header to use for agent IP checks configured in `agent_ips` or in
# Company settings, e.g. `X-Forwarded-For`. Set this if you have a hardware
# firewall in front of Surfly. Only the first comma-separated IP is considered
# when reading the header's value. If not set, the actual source IP is used.
CLIENT_IP_HEADER=


# =============================================================================
# --- Database Configuration
# =============================================================================

# Connection strings to PostgreSQL database
# Examples:
# - Connect over Unix socket:
#   surfly =
#
# - Remote database:
#   surfly = host=1.2.3.4 port=5432 user=surfly_app password=secret
# Documentation: http://www.pgbouncer.org/config.html .
DB_CONNECT_STRING="surfly = host=127.0.0.1 dbname=surfly user=surfly_app"
CONSOLE_API_DB_CONNECT_STRING="console = host=127.0.0.1 dbname=console"

# Redis connection configuration.
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# =============================================================================
# --- Registration & Access Control
# =============================================================================

# Whether to allow registration of new users in Dashboard.
DASHBOARD_REGISTRATION_OPEN=false

# Whether to allow registration of new users in Studio.
CONSOLE_REGISTRATION_OPEN=false

# Reports attempts to violate the Content Security Policy to this URL
CSP_REPORT_URI=

# =============================================================================
# --- External Login Providers (Dashboard, Studio, Session)
# =============================================================================

# GitHub OAuth2 configuration.
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Google OAuth2 configuration.
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Domain name used for OAuth2.
OAUTH_SERVER_NAME=

# =============================================================================
# --- Email Configuration
# =============================================================================

# The default from email.
DEFAULT_FROM_EMAIL=

# By default Surfly prints the content of the all outgoing emails to syslog.
EMAIL_BACKEND="surflyapp.email_backends.ConsoleBackend"

# SMTP configuration:
# Use `surflyapp.email_backends.SMTPBackend` as EMAIL_BACKEND to send emails via
# your own SMTP server (https://docs.djangoproject.com/en/5.2/topics/email/#smtp-backend).
EMAIL_HOST=
EMAIL_HOST_PASSWORD=
EMAIL_HOST_USER=
EMAIL_PORT=
EMAIL_USE_SSL=
EMAIL_USE_TLS=

# To use your own Mandrill account, set EMAIL_BACKEND to `surflyapp.email_backends.MandrillBackend`
# and the following key.
MANDRILL_API_KEY=

# =============================================================================
# --- Configure Session Invitations via SMS
# =============================================================================

# Configuration for the Vonage SMS API
SMS_ENDPOINT=
VONAGE_COM_API_KEY=
VONAGE_COM_API_SECRET=
VONAGE_US_PHONE_NUMBER=

# =============================================================================
# --- Server-Wide Screenshot Configuration
# =============================================================================

# Enable screenshot functionality on the server by providing credentials to
# S3 bucket to upload screenshots to.
SCREENSHOT_S3_BUCKET=
SCREENSHOT_AWS_ACCESS_KEY_ID=
SCREENSHOT_AWS_SECRET_ACCESS_KEY=

# =============================================================================
# --- Configure exporting session history as CSV (Dashboard)
# =============================================================================

# Enable async session history CSV extraction by providing credentials to
# S3 bucket to upload CSVs to (link to uploaded file will be sent via e-mail).
CSV_UPLOAD_AWS_ACCESS_KEY_ID=
CSV_UPLOAD_AWS_SECRET_ACCESS_KEY=
CSV_UPLOAD_AWS_BUCKET=

# =============================================================================
# --- Document Editor
# =============================================================================

# License key for Pdftron document editor, without it default pdf.js viewer is used.
PDFTRON_KEY=

# If specified, it enables server-side rendering mode in Pdftron document editor.
PDFTRON_SERVER=

# =============================================================================
# --- Dashboard Configuration
# =============================================================================

# The number of processes serving Dashboard requests.
DASHBOARD_WORKERS=4

# The log level for Dashboard.
DASHBOARD_LOGLEVEL=info

# The number of seconds to wait for a worker to finish serving requests before
# it is terminated.
DASHBOARD_WORKERS_TIMEOUT=30

# Use the branding settings of the company with this ID to style the login
# page. These settings also serve as a default for users in companies
# without custom branding.
DEFAULT_BRANDING_COMPANY=

# Set to true to use Single Sign-On as the default login page instead of
# password-based login.
DEFAULT_LOGIN_SSO=false

# Specifies dashboard session cookie timeout, in seconds.
SESSION_COOKIE_AGE=1209600

# =============================================================================
# --- Cobro API Configuration
# =============================================================================

# The number of processes serving Session API requests.
API_APP_WORKERS=2

# The number of seconds to wait for a worker to finish serving requests before it
# is terminated.
API_APP_WORKERS_TIMEOUT=30

# =============================================================================
# --- Studio Configuration
# =============================================================================

# The number of processes serving Console API requests.
CONSOLE_API_WORKERS=2

# The number of seconds to wait for a worker to finish serving requests before it
# is terminated.
CONSOLE_API_WORKERS_TIMEOUT=30

# The log level for Console API requests.
CONSOLE_API_LOGLEVEL=info

# Token used to copy repositories from GitHub to StorageApp when exporting or
# importing spaces and templates.
GITHUB_COPY_TO_STORAGE_TOKEN=

# We send compressed payloads in Studio Webhooks, however some of the endpoints
# do not support it. This variable allows to disable compression for specific
# domains (space separated list).
STUDIO_WEBHOOK_TEXT_PAYLOAD_DOMAINS=hooks.zapier.com

# =============================================================================
# --- Maintenance service configuration
# =============================================================================

# The time period (in seconds) after which a session with no activity is
# classified as a 'zombie' and terminated.
COLLECT_ZOMBIE_PERIOD=120

# The time period (in seconds) after which a session with no connected users is
# terminated.
INACTIVE_SESSION_END_TIMEOUT=15

# Indicate the time period (in seconds) after which a Solo space session with no
# connected users is terminated.
SOLO_INACTIVE_SESSION_END_TIMEOUT=900

# =============================================================================
# --- Proxy Configuration
# =============================================================================

# Timeout for retrieving the resource. Should be synced between haproxy,
# varnish, proxy and cmproxy (seconds).
PROXY_TIMEOUT=180

# Timeout used for long-running requests (POST, PUT). Should be synced between
# haproxy, varnish, proxy and cmproxy (seconds).
PROXY_TIMEOUT_LONG=1800

# The number of processes serving proxy requests.
PROXY_WORKERS=4

# =============================================================================
# --- HTML parser
# =============================================================================

# Number of processes for HTML parser. Supported values are:
# - auto: automatically determine the number of processes based on available CPU cores
# - <number>: fixed number of processes.
PROCESSHTML_WORKERS=auto

# =============================================================================
# --- JavaScript parser
# =============================================================================

# Number of processes for JavaScript parser. Supported values are:
# - auto: automatically determine the number of processes based on available CPU cores
# - <number>: fixed number of processes.
PROCESSJS_WORKERS=auto

# =============================================================================
# --- Trafficserver (ATS) Configuration
# =============================================================================

# Size of RAM cache used by trafficserver. If left empty, trafficserver forwards
# all requests without caching them. Note: trafficserver automatically defines
# RAM cache size for the most popular objects.
ATS_SIZE=128M

# =============================================================================
# --- CMProxy Configuration
# =============================================================================

# Maximum amount of memory in megabytes that cmproxy can use specifically for caching.
# 0 means that caching is disabled. The limit is soft and cmproxy may use more memory.
CMPROXY_MEM=100

# CMPROXY_CA_BUNDLE is path to a PEM encoded CA bundle, normally with root and
# intermediate certificates.
CMPROXY_CA_BUNDLE=/ats_certs.pem

# CMPROXY_RESIDENTIAL_PROXIES is a space separated list of residential proxies
# HTTP and SOCKS5 proxies are supported: socks5://username:password@host:port or
# http://username:password@host:port .
CMPROXY_RESIDENTIAL_PROXIES=

# Enables CMPROXY debug logs if set to true.
CMPROXY_DEBUG=

# Enables HAR recording in CMPROXY. If set to true, it will save all requests
# and responses in HAR format to RAM. Calling /har endpoint will return the HAR file
# and clear the RAM cache.
CMPROXY_ENABLE_HAR_RECORDING=

# Maximum allowed content length for proxied files, in bytes. Prevents the
# download of large files (e.g., movies).
PROXY_MAX_CONTENT_LENGTH=250000000

# =============================================================================
# --- HAProxy Configuration
# =============================================================================

# Specifies bind address for haproxy. More information is available here
# https://www.haproxy.com/documentation/hapee/latest/configuration/binds/syntax/
HAPROXY_LISTEN_ON=::

# Specify allowed HTTP methods for proxy application (default: all allowed
# (when empty)).
VALID_HTTP_METHODS=

# =============================================================================
# --- Nginx Configuration
# =============================================================================

# Max number of connections per nginx process (both frontend and backend).
NGINX_MAX_CONNECTIONS=1024

# Controls whether modesecurity module is enabled in nginx (Note: there is a
# significant performance impact!).
NGINX_ENABLE_WAF=true

# =============================================================================
# --- Varnish Configuration
# =============================================================================

# Size of Varnish cache (default: 1G).
VARNISH_SIZE=1000M

# Varnish secret. If unset, will be generated automatically during container startup.
VARNISH_SECRET=

# Size of short-lived Varnish cache (default: 1G).
VARNISH_TRANSIENT_SIZE=1000M

# Varnish storage backend. Usually "malloc" or "file,<filepath>".
VARNISH_STORAGE_BACKEND=malloc

# Minimum number of threads in varnish (default: 100).
VARNISH_MIN_THREADS=100

# =============================================================================
# --- CF App Configuration
# =============================================================================

# Number of worker processes for CF app
CF_WORKERS=4

# =============================================================================
# --- Customize documentation, home page, and other links
# =============================================================================

# Override redirect URLs for specific domains, specify favicon and tab title of
# the dashboard for specific domains
# Example:
# {
#   "surfly.com": {
#     "contact": "https://www.surfly.com/contact/",
#     "dashboard_favicon": "https://docs.surfly.com/installation/favicon.ico",
#     "dashboard_title": "Surfly",
#     "docs": "https://docs.surfly.com",
#     "error404": "https://some-other-404-page.example.com",
#     "home": "https://www.surfly.com",
#     "register": "https://some-other-register-page.example.com",
#     "successful_session_start": "http://help.surfly.com/en/articles/5342170-what-defines-the-successful-start-of-a-session",
#     "videochat_docs": "https://docs.surfly.com/surfly-options.html#header-video"
#   }
# }
# Should be formatted as single line JSON string.
DOMAIN_REDIRECTS={}

# =============================================================================
# --- Videochat
# =============================================================================

# Opentok API key
OPENTOK_API_KEY=

# Opentok API secret
OPENTOK_SECRET=

# Designates whether archiving is allowed, (bool)
OPENTOK_ALLOW_ARCHIVING=false

# DeepAR key to enable video chat filters
DEEPAR_API_KEY=

# =============================================================================
# --- Multiserver configuration
# =============================================================================

# Space separated list of dashboard URLs for a cobro server to register in.
DASHBOARD_URLS=http://localhost:8010

# Unique cobro server id.
COBRO_SERVER_ID=00

# Description of the server. Used in `/v2/servers/` REST API endpoint.
COBRO_SERVER_DESCRIPTION=

# Comma separated list of server's public IP addresses which is used in
# /v2/servers/ API endpoint.
COBRO_SERVER_IPS=

# Region of the server. The value is a valid session option for preferred region
# to start a session on.
COBRO_SERVER_REGION=

# Server installation type for multi-server setup.
# When omitted or set to an empty value, installation includes all functionality.
# Otherwise, it can be set to "dashboard" or "cobro" to split functionality
# between nodes and specify a particular server deployment type.
DEPLOYMENT_TYPE=

# Mapping of server IDs to their public IP addresses and ports as JSON string.
# Format: {"server_id":"ip:port","server_id":"ip:port",...}
# Example: primary server (00) and one cobro node (10) where 00 is defined as
# empty string.
MULTISERVER={}

# Designates whether the server is a backup server in multi-server setup. Mostly
# affects huey periodic tasks.
IS_BACKUP_SERVER=
# =============================================================================