Site Configuration and Settings
The problem: every environment is different
Section titled “The problem: every environment is different”Your CMS runs in development, staging, and production. Each environment needs different URLs, different API keys, different feature toggles, and sometimes different content defaults. Hardcoding these values leads to deployments that break across environments. Missing a configuration change is one of the most common causes of failed launches.
Optimizely CMS separates configuration into layers so you can manage environment-specific settings without changing code.
Site definitions
Section titled “Site definitions”A site definition tells the CMS how to map incoming HTTP requests to content. At minimum, it specifies:
- Site name — A human-readable label for the site
- Site URL — The primary domain (e.g.,
https://www.example.com) - Start page — The content item that serves as the site root
When a request arrives, the CMS matches the hostname against configured site definitions. It then resolves the content tree starting from the site’s start page.
You can configure multiple site definitions for different domains or subdomains. This is the foundation of multi-site hosting.
Start page configuration
Section titled “Start page configuration”The start page is the most important content node in your site. It serves as:
- The homepage — Visitors hitting your root URL see this page
- The tree root — All site navigation and content hierarchy branches from here
- The settings anchor — Many site-wide properties (logo, footer, navigation labels) live on the start page type
Design your start page content type carefully. Include properties for global elements that authors need to control — site title, logo, contact information, social media links, and default metadata.
Global settings
Section titled “Global settings”Beyond the start page, Optimizely CMS supports several approaches to global settings:
Settings on the start page
Section titled “Settings on the start page”The simplest approach. Add properties to your start page type for site-wide values. Authors edit them alongside homepage content. This works well for small sites with few global settings.
Dedicated settings pages
Section titled “Dedicated settings pages”For complex sites, create a Settings content type that lives outside the main content tree. Store it under a non-public root node. This keeps global settings separate from page content and avoids cluttering the start page with dozens of properties.
CMS admin settings
Section titled “CMS admin settings”Some settings live in the CMS admin interface rather than in content. These include:
- Tool pane configuration
- Editor interface languages
- Content type visibility settings
- Scheduled job configurations
Environment-specific configuration
Section titled “Environment-specific configuration”What to configure per environment
Section titled “What to configure per environment”| Setting | Example values |
|---|---|
| Site URL | localhost:5000 (dev), staging.example.com, www.example.com |
| Database connection | Local SQL Server (dev), Azure SQL (staging/prod) |
| CDN URL | None (dev), CDN hostname (prod) |
| Search service | Local index (dev), cloud search service (prod) |
| Email settings | Disabled (dev), test mailbox (staging), production SMTP (prod) |
| Feature toggles | Experimental features on (dev), off (prod) |
| Logging level | Debug (dev), Warning (prod) |
Feature toggles
Section titled “Feature toggles”Feature toggles let you enable or disable functionality without deploying new code. Common uses in CMS projects:
- Content features — Show or hide a new content section while it is being prepared
- Integration features — Enable a third-party integration only when the credentials are ready
- Experimental features — Test a new editing workflow with a small group before rolling it out
Store feature toggle values in configuration, not in code. This lets you flip toggles per environment without redeployment.
Content defaults
Section titled “Content defaults”Some content behaviors need default values that differ by site or environment:
- Default language — Which language version shows when no match is found
- Content fallback — Whether missing translations fall back to the master language
- Image quality — Default compression settings for uploaded images
- Cache duration — How long rendered pages stay in the output cache
Configure these at the site level so different sites in a multi-site setup can have independent defaults.
Configuration best practices
Section titled “Configuration best practices”- Separate secrets from settings. Connection strings and API keys go in environment variables or a secrets vault. Everything else goes in configuration files.
- Document every setting. Maintain a configuration reference that lists each setting, its purpose, valid values, and which environments it applies to.
- Use configuration validation. Validate required settings at application startup. Fail fast with a clear error message rather than failing mysteriously at runtime.
- Version your configuration. Track configuration files in source control (excluding secrets). This gives you a history of what changed and when.
- Test environment parity. Keep staging as close to production as possible. Configuration differences between environments are a top source of deployment surprises.
1. Your CMS project stores database connection strings in appsettings.json, which is committed to source control. A security audit flags this as a risk. What is the recommended approach on CMS PaaS?
The best practice is to separate secrets from settings. Connection strings and API keys should go in environment variables or a secrets vault, never in source control. Non-secret settings remain in configuration files.
The best practice is to separate secrets from settings. Connection strings and API keys should go in environment variables or a secrets vault, never in source control. Non-secret settings remain in configuration files.
Review this topic →2. You are setting up a multi-site CMS deployment with two domains: www.brand-a.com and www.brand-b.com. Each site needs its own homepage and content tree. What CMS configuration makes this possible?
Site definitions map incoming HTTP hostnames to specific start pages. Each site definition creates an independent content tree root, allowing multiple domains to serve different content from the same CMS instance.
Site definitions map incoming HTTP hostnames to specific start pages. Each site definition creates an independent content tree root, allowing multiple domains to serve different content from the same CMS instance.
Review this topic →3. Your site has dozens of global settings — logo, footer links, social media URLs, default metadata, contact info. These are cluttering the start page content type. What approach better organizes these settings?
For complex sites with many global settings, a dedicated Settings content type stored outside the main content tree keeps settings separate from page content and avoids cluttering the start page.
For complex sites with many global settings, a dedicated Settings content type stored outside the main content tree keeps settings separate from page content and avoids cluttering the start page.
Review this topic →