Studio’s Configuration Overrides

Crafter Studio comes with pre-configured settings that you may want to override. To view the pre-configured settings in Crafter Studio, in your Authoring installation, go to CRAFTER_HOME/bin/apache-tomcat/webapps/studio/WEB-INF/classes/crafter/studio and open the file studio-config.yaml.

To override any of the pre-configured settings, in your Authoring installation, go to CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension and add the settings you would like to configure in the file studio-config-override.yaml. The override file have some settings already listed that you may want to override in Crafter Studio:

Content Repository Configuration

The following section of Studio’s configuration overrides allows you to do the following:

  • studio.repo.basePath allows you to set your repository base

  • studio.repo.siteSandboxBranch allows you to set the default branch to be used by sandbox

  • studio.repo.published.live and studio.repo.published.staging allows you to set the branch for your publishing targets

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1##################################################
 2##              Content Repository              ##
 3##################################################
 4# Absolute or relative path to repository base (all actual repositories will be under this)
 5studio.repo.basePath: ../data/repos
 6# Sandbox Git repository branch for every site
 7# studio.repo.siteSandboxBranch: master
 8# Git repository branch for publishing targets are configured here
 9# Git repository branch for the `live` publishing target, default "live"
10# studio.repo.published.live: live
11# Git repository branch for the `staging` publishing target, default "staging"
12# studio.repo.published.staging: staging

Site Configuration

The following section of Studio’s configuration overrides allows you to setup your site configuration

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1############################################################
 2##                   Site Configuration                   ##
 3############################################################
 4# Destroy site context url for preview engine
 5studio.configuration.site.preview.destroy.context.url: ${env:ENGINE_URL}/api/1/site/context/destroy.json?crafterSite={siteName}&token=${studio.configuration.management.previewAuthorizationToken}
 6# Default preview URL
 7studio.configuration.site.defaultPreviewUrl: ^https?://localhost:8080/?
 8# Default authoring URL
 9studio.configuration.site.defaultAuthoringUrl: ^https?://localhost:8080/studio/?
10# Default GraphQL server URL
11studio.configuration.site.defaultGraphqlServerUrl: ^https?://localhost:8080/?
12# Studio management authorization token.
13studio.configuration.management.authorizationToken: ${env:STUDIO_MANAGEMENT_TOKEN}
14# Preview engine management authorization token.
15studio.configuration.management.previewAuthorizationToken: ${env:ENGINE_MANAGEMENT_TOKEN}
16# Protected URLs with preview engine management authorization token.
17# Coma separated list of preview engine urls
18studio.configuration.management.previewProtectedUrls: >-
19  /api/1/monitoring/log.json,
20  /api/1/monitoring/memory.json,
21  /api/1/monitoring/status.json,
22  /api/1/monitoring/version.json,
23  /api/1/site/context/id,
24  /api/1/site/context/destroy,
25  /api/1/site/context/rebuild,
26  /api/1/site/context/graphql/rebuild,
27  /api/1/site/cache/clear,
28  /api/1/site/cache/statistics

Preview Deployer Configuration

The following section of Studio’s configuration overrides allows you to setup your deployer urls

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1############################################################
 2##                    Preview Deployer                    ##
 3############################################################
 4
 5# Default preview deployer URL (can be overridden per site)
 6studio.preview.defaultPreviewDeployerUrl: ${env:DEPLOYER_URL}/api/1/target/deploy/{siteEnv}/{siteName}
 7# Default preview create target URL (can be overridden per site)
 8studio.preview.createTargetUrl: ${env:DEPLOYER_URL}/api/1/target/create_if_not_exists
 9# Default preview create target URL (can be overridden per site)
10studio.preview.deleteTargetUrl: ${env:DEPLOYER_URL}/api/1/target/delete-if-exists/{siteEnv}/{siteName}
11# URL to the preview repository (aka Sandbox) where authors save work-in-progress
12studio.preview.repoUrl: ${env:CRAFTER_DATA_DIR}/repos/sites/{siteName}/sandbox

Preview Search Configuration

The following section of Studio’s configuration overrides allows you to setup urls for search in preview

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
1############################################################
2##                   Preview Search                       ##
3############################################################
4
5studio.preview.search.createUrl: ${env:SEARCH_URL}/api/2/admin/index/create
6studio.preview.search.deleteUrl: ${env:SEARCH_URL}/api/2/admin/index/delete/{siteName}

Database Configuration

The following section of Studio’s configuration overrides allows you to setup the database url, port number, connection string to initialize the database and path

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1##################################################
 2##                   Database                   ##
 3##################################################
 4# Crafter Studio uses an embedded MariaDB by default
 5# Crafter DB schema name
 6studio.db.schema: ${env:MARIADB_SCHEMA}
 7# Crafter DB connection string
 8studio.db.url: jdbc:mariadb://${env:MARIADB_HOST}:${env:MARIADB_PORT}/${env:MARIADB_SCHEMA}?user=${env:MARIADB_USER}&password=${env:MARIADB_PASSWD}&socketTimeout=${env:MARIADB_SOCKET_TIMEOUT}
 9# Connection string used to initialize database. This creates the `crafter` schema, the `crafter` user and/or upgrades the database
10studio.db.initializer.url: jdbc:mariadb://${env:MARIADB_HOST}:${env:MARIADB_PORT}?user=${env:MARIADB_ROOT_USER}&password=${env:MARIADB_ROOT_PASSWD}
11# Connection string if using a database with an already created schema and user (like AWS RDS)
12# studio.db.initializer.url: ${studio.db.url}
13# Port number for the embedded database (note this must match what's in the connection URLs in this config file)
14studio.db.port: ${env:MARIADB_PORT}
15# Data folder for the embedded database
16studio.db.dataPath: ${env:MARIADB_DATA_DIR}
17# Socket path for the embedded database
18studio.db.socket: /tmp/MariaDB4j.${env:MARIADB_PORT}.sock

Security Configuration

The following section of Studio’s configuration overrides allows you to randomize the admin password on a fresh install (for more information, see: Randomize “admin” Password for CrafterCMS Fresh Install), configure encryption and configure authentication method to be used (for more information, see: Configuring Studio Security), configure password requirements validation (for more information see: Configure Studio Password Requirements).

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
  1##################################################
  2##                   Security                   ##
  3##################################################
  4# Enable random admin password generation
  5# studio.db.initializer.randomAdminPassword.enabled: false
  6# Random admin password length
  7# studio.db.initializer.randomAdminPassword.length: 16
  8# Random admin password allowed chars
  9# studio.db.initializer.randomAdminPassword.chars: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*_=+-/
 10# HTTP Session timeout for studio (value is in minutes).
 11# studio.security.sessionTimeout: 60
 12# Defines security provider for accessing repository. Possible values
 13# - db (users are stored in database)
 14# - ldap (users are imported from LDAP into the database)
 15# - headers (use when authenticating via headers)
 16# studio.security.type: ldap
 17#
 18# Salt for encrypting
 19# studio.security.cipher.salt: ${env:CRAFTER_SYSTEM_ENCRYPTION_KEY}
 20# Key for encrypting
 21# studio.security.cipher.key: ${env:CRAFTER_SYSTEM_ENCRYPTION_SALT}
 22# Enable password requirements validation
 23# studio.security.passwordRequirements.enabled: false
 24# Password requirements validation regular expression
 25# The supported capture group keys are:
 26#   hasNumbers
 27#   hasLowercase
 28#   hasUppercase
 29#   hasSpecialChars
 30#   noSpaces
 31#   minLength
 32#   maxLength
 33#   minMaxLength
 34# studio.security.passwordRequirements.validationRegex: ^(?=(?<hasNumbers>.*[0-9]))(?=(?<hasLowercase>.*[a-z]))(?=(?<hasUppercase>.*[A-Z]))(?=(?<hasSpecialChars>.*[~|!`,;\/@#$%^&+=]))(?<minLength>.{8,})$
 35# Studio authentication chain configuration
 36# studio.authentication.chain:
 37  # Authentication provider type
 38  # - provider: HEADERS
 39    # Authentication via headers enabled
 40    # enabled: false
 41    # Authentication header for secure key
 42    # secureKeyHeader: secure_key
 43    # Authentication headers secure key that is expected to match secure key value from headers
 44    # Typically this is placed in the header by the authentication agent
 45    # secureKeyHeaderValue: secure
 46    # Authentication header for username
 47    # usernameHeader: username
 48    # Authentication header for first name
 49    # firstNameHeader: firstname
 50    # Authentication header for last name
 51    # lastNameHeader: lastname
 52    # Authentication header for email
 53    # emailHeader: email
 54    # Authentication header for groups: comma separated list of sites and groups
 55    #   Example:
 56    #   site_author,site_xyz_developer
 57    # groupsHeader: groups
 58    # Enable/disable logout for headers authenticated users (SSO)
 59    # logoutEnabled: false
 60    # If logout is enabled for headers authenticated users (SSO), set the endpoint of the SP or IdP logout, which should
 61    # be called after local logout. The {baseUrl} macro is provided so that the browser is redirected back to Studio
 62    # after logout (https://STUDIO_SERVER:STUDIO_PORT/studio)
 63    # logoutUrl: /YOUR_DOMAIN/logout?ReturnTo={baseUrl}
 64  # Authentication provider type
 65  # - provider: LDAP
 66    # Authentication via LDAP enabled
 67    # enabled: false
 68    # LDAP Server url
 69    # ldapUrl: ldap://localhost:389
 70    # LDAP bind DN (user)
 71    # ldapUsername: cn=Manager,dc=my-domain,dc=com
 72    # LDAP bind password
 73    # ldapPassword: secret
 74    # LDAP base context (directory root)
 75    # ldapBaseContext: dc=my-domain,dc=com
 76    # LDAP username attribute
 77    # usernameLdapAttribute: uid
 78    # LDAP first name attribute
 79    # firstNameLdapAttribute: cn
 80    # LDAP last name attribute
 81    # lastNameLdapAttribute: sn
 82    # Authentication header for email
 83    # emailLdapAttribute: mail
 84    # LDAP groups attribute
 85    # groupNameLdapAttribute: crafterGroup
 86    # LDAP groups attribute name regex
 87    # groupNameLdapAttributeRegex: .*
 88    # LDAP groups attribute match index
 89    # groupNameLdapAttributeMatchIndex: 0
 90  # Authentication provider type
 91  # - provider: DB
 92    # Authentication via DB enabled
 93    # enabled: true
 94
 95# The key used for encryption of configuration properties
 96studio.security.encryption.key: ${env:CRAFTER_ENCRYPTION_KEY}
 97# The salt used for encryption of configuration properties
 98studio.security.encryption.salt: ${env:CRAFTER_ENCRYPTION_SALT}
 99
100# Defines name used for environment specific configuration. It is used for environment overrides in studio. Default value is default.
101studio.configuration.environment.active: ${env:CRAFTER_ENVIRONMENT}

Mail Configuration

The following section of Studio’s configuration overrides allows you to setup the SMTP server to be used by CrafterCMS when sending emails

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1##################################################
 2##        SMTP Configuration (Email)            ##
 3##################################################
 4
 5# Default value for from header when sending emails.
 6# studio.mail.from.default: admin@example.com
 7# SMTP server name to send emails.
 8studio.mail.host: ${env:MAIL_HOST}
 9# SMTP port number to send emails.
10studio.mail.port: ${env:MAIL_PORT}
11# SMTP username for authenticated access when sending emails.
12# studio.mail.username:
13# SMTP password for authenticated access when sending emails.
14# studio.mail.password:
15# Turn on/off (value true/false) SMTP authenaticated access protocol.
16# studio.mail.smtp.auth: false
17# Enable/disable (value true/false) SMTP TLS protocol when sending emails.
18# studio.mail.smtp.starttls.enable: false
19# Enable/disable (value true/false) SMTP EHLO protocol when sending emails.
20# studio.mail.smtp.ehlo: true
21# Enable/disable (value true/false) debug mode for email service. Enabling debug mode allows tracking/debugging communication between email service and SMTP server.
22# studio.mail.debug: false

Clustering

The following section of Studio’s configuration overrides allows you to setup Studio for clustering. See Studio Clustering for more information

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1##################################################
 2##                 Clustering                   ##
 3##################################################
 4#-----------------------------------------------------------------------------
 5# IMPORTANT: To enable clustering, please specify the environment variable
 6# SPRING_PROFILES_ACTIVE=crafter.studio.dbCluster in your crafter-setenv.sh
 7# (or Docker/Kubernetes env variables).
 8# Also configure the appropriate MARIADB env variables
 9# -----------------------------------------------------------------------------
10
11# Cluster Git URL format for synching members.
12# - Typical SSH URL format: ssh://{username}@{localAddress}{absolutePath}
13# - Typical HTTPS URL format: https://{localAddress}/repos/sites
14# studio.clustering.sync.urlFormat: ssh://{username}@{localAddress}{absolutePath}
15
16# Cluster Syncers
17# Sandbox Sync Job interval in milliseconds which is how often to sync the work-area
18# studio.clustering.sandboxSyncJob.interval: 2000
19# Published Sync Job interval in milliseconds which is how often to sync the published repos
20# studio.clustering.publishedSyncJob.interval: 60000
21# Global Repo Sync Job interval in milliseconds which is how often to sync the global repo
22# studio.clustering.globalRepoSyncJob.interval: 45000
23# Cluster member after heartbeat stale for amount of minutes will be declared inactive
24# studio.clustering.heartbeatStale.timeLimit: 5
25# Cluster member after being inactive for amount of minutes will be removed from cluster
26# studio.clustering.inactivity.timeLimit: 5
27
28# Cluster member registration, this registers *this* server into the pool
29# Cluster node registration data, remember to uncomment the next line
30# studio.clustering.node.registration:
31#  This server's local address (reachable to other cluster members). You can also specify a different port by
32#  attaching :PORT to the adddress (e.g 192.168.1.200:2222)
33#  localAddress: ${env:CLUSTER_NODE_ADDRESS}
34#  Authentication type to access this server's local repository
35#  possible values
36#   - none (no authentication needed)
37#   - basic (username/password authentication)
38#   - key (ssh authentication)
39#  authenticationType: none
40#  Username to access this server's local repository
41#  username: user
42#  Password to access this server's local repository
43#  password: SuperSecurePassword
44#  Private key to access this server's local repository (multiline string)
45#  privateKey: |
46#    -----BEGIN PRIVATE KEY-----
47#    privateKey
48#    -----END PRIVATE KEY-----

CORS

The following section of Studio’s configuration overrides allows you to setup CORS

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1################################################################
 2##                             CORS                           ##
 3################################################################
 4# This is configured as permissive by default for ease of deployment
 5# Remember to tighten this up for production
 6
 7# Disable CORS headers completely
 8# studio.cors.disable: false
 9# Value for the Access-Control-Allow-Origin header
10# studio.cors.origins: '*'
11# Value for the Access-Control-Allow-Headers header
12# studio.cors.headers: '*'
13# Value for the Access-Control-Allow-Methods header
14# studio.cors.methods: '*'
15# Value for the Access-Control-Allow-Credentials header
16# studio.cors.credentials: true
17# Value for the Access-Control-Max-Age header
18# studio.cors.maxage: -1

Serverless Delivery

The following section of Studio’s configuration overrides allows you to setup serverless delivery

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
 1##########################################################
 2##                 Serverless Delivery                  ##
 3##########################################################
 4# Indicates if serverless delivery is enabled
 5# studio.serverless.delivery.enabled: false
 6# The URL for the serverless delivery deployer create URL
 7# studio.serverless.delivery.deployer.target.createUrl: ${studio.preview.createTargetUrl}
 8# The URL for the serverless delivery deployer delete URL
 9# studio.serverless.delivery.deployer.target.deleteUrl: ${studio.preview.deleteTargetUrl}
10# The template name for serverless deployer targets
11# studio.serverless.delivery.deployer.target.template: aws-cloudformed-s3
12# Replace existing target configuration if one exists?
13# studio.serverless.delivery.deployer.target.replace: false
14# The URL the deployer will use to clone/pull the site's published repo. When the deployer is in a separate node
15# (because of clustering), this URL should be an SSH/HTTP URL to the load balancer in front of the Studios
16# studio.serverless.delivery.deployer.target.remoteRepoUrl: ${env:CRAFTER_DATA_DIR}/repos/sites/{siteName}/published
17# The deployer's local path where it will store the clone of the published site. This property is not needed if
18# the deployer is not the preview deployer, so you can leave an empty string ('') instead
19# studio.serverless.delivery.deployer.target.localRepoPath: ${env:CRAFTER_DATA_DIR}/repos/aws/{siteName}
20# Parameters for the target template. Please check the deployer template documentation for the possible parameters.
21# The following parameters will be sent automatically, and you don't need to specify them: env, site_name, replace,
22# disable_deploy_cron, local_repo_path, repo_url, use_crafter_search
23# studio.serverless.delivery.deployer.target.template.params:
24#   # The delivery Elasticsearch endpoint (optional is authoring is using the same one, specified in the ES_URL env variable)
25#   elastic_search_url:
26#   aws:
27#     # AWS region (optional if specified through default AWS chain)
28#     region: us-east-1
29#     # AWS access key (optional if specified through default AWS chain)
30#     default_access_key:
31#     # AWS secret key (optional if specified through default AWS chain)
32#     default_secret_key:
33#     cloudformation:
34#       # AWS access key (optional if aws.accessKey is specified)
35#       access_key:
36#       # AWS secret key (optional if aws.secretKey is specified)
37#       secret_key:
38#       # Namespace to use for CloudFormation resources (required when target template is aws-cloudformed-s3)
39#       namespace: myorganization
40#       # The domain name of the serverless delivery LB (required when target template is aws-cloudformed-s3)
41#       deliveryLBDomainName:
42#       # The SSL certificate ARN the CloudFront CDN should use (optional when target template is aws-cloudformed-s3)
43#       cloudfrontCertificateArn:
44#       # The alternate domains names (besides *.cloudfront.net) for the CloudFront CDN (optional when target template is aws-cloudformed-s3)
45#       alternateCloudFrontDomainNames:

Forwarded Headers

The following section of Studio’s configuration overrides allows you to configure forwarded headers to resolve the actual hostname and protocol when it is behind a load balancer or reverse proxy.

CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml
1##################################################
2##             Forwarded Headers                ##
3##################################################
4# Indicates if Forwarded or X-Forwarded headers should be used when resolving the client-originated protocol and
5# address. Enable when Studio is behind a reverse proxy or load balancer that sends these
6studio.forwarded.headers.enabled: false