# Configuration reference
# Sample configuration file
The sample comofiguration file shows all possible configuration options with their defaults for the ymir.yml
file:
id: 1
name: project-name
type: wordpress
environments:
environment-name:
build:
commands: []
include: []
cdn:
caching: enabled
cookies_whitelist: ['comment_*', 'wordpress_*', 'wp-settings-*']
default_expiry: 300
excluded_paths: ['/wp-admin/*', '/wp-login.php']
invalidate_paths: []
concurrency: 10
cron: true
database:
server: database-server
name: database-name
user: database-user
domain: []
log_retention_period: 7
php: 7.4
warmup: true
website:
memory: 256
timeout: 30
console:
memory: 1028
timeout: 60
# Project configuration
Project configuration options are global to a project and apply to all environments.
# id
type: int
required
The ID of the project in Ymir.
# name
type: string
required
The name of the project.
# type
type: string
required
The project type.
The possible values are:
bedrock
for Bedrock (opens new window) projectswordpress
for WordPress projects
# environments
type: array
required
All the project environments. Configuration values for environments are covered in the next section.
# Environment configuration
Each key under the environments
option is the name of the environment. Everything under that key is the configuration options for that environment.
# build
type: array
This is the array of values to configure the environment build. If the database value is a simple array, it'll be used as the commands
value.
# commands
type: array
This is an array of build commands that the Ymir CLI will run when building your project. These commands are executed on the computer performing the build and not on the Ymir platform. If your build commands generate files, they'll get packaged along with the rest of your project files during deployment.
# include
type: array
This is an array of paths that you want to include in the environment build artifact. By default, Ymir will only add .mo
and .php
files to the build artifact to ensure a small build artifact. This lets you specify additional files or folders to add the build artifact besides the defaults.
# cdn
type: array | string
This is the array of values to configure the environment's CloudFront distribution. If the cdn
value is a string, it'll be used as the caching
value.
# caching
type: string
default: enabled
This option controls the CloudFront distribution.
The possible values are:
enabled
enables CloudFront distribution cachingassets
only caches assetsdisabled
disables CloudFront distribution caching
Provisioning delay
Switching the caching
value to enabled
can cause your WordPress site to not load certain assets while the CloudFront distribution updates. This process can take as long as 40 minutes.
Full CloudFront caching disabled with REST API
If you have the caching
set to enabled
and the gateway
option set to rest
, the caching level will be downgraded to assets
automatically. That's because REST APIs already have CloudFront page caching by default.
# cookies_whitelist
type: array
default: ['comment_*', 'wordpress_*', 'wp-settings-*']
The list of cookies that are ignored by CloudFront and always forwarded to your WordPress site. Supports *
wildcard character.
# default_expiry
type: int
default: 300
The default time (in seconds) that CloudFront will keep something cached.
# excluded_paths
type: array
default: ['/wp-admin/*', '/wp-login.php']
The list of paths that are ignored by CloudFront and always forwarded to your WordPress site. Supports *
wildcard character.
Tailored to all project types
The project type
will change default paths for non-WordPress projects. So you don't need to edit this for bedrock
projects.
# invalidate_paths
type: array
The list of paths that are cleared from the CloudFront distribution cache during the project deployment. Supports *
wildcard character.
# concurrency
type: int | false
default: 10
This option controls the maximum number of website
Lambda functions that can exist at the same time. (AWS calls this reserved concurrency (opens new window).) Setting this option to false
removes the limit and allows unrestricted scaling.
Overwhelming your database server
If your concurrency
value is too high or disabled, your database server could get overwhelmed when a traffic spike hits your WordPress site. If this happens, you'll want to increase the capacity of your database server.
# cron
type: int | false
default: 1
The interval (in minutes) that WP-Cron (opens new window) gets called by CloudWatch. Also controls the DISABLE_WP_CRON
constant. If set to false
, it disables the CloudWatch rule and renables the standard WP-Cron behaviour.
# database
type: array | string
This is the array of values to configure the environment's database. If the database
value is a string, it'll be used as the server
value.
# server
type: string
The database server used by the WordPress site. It can be the name of the database server if it's managed by Ymir or the host name of the database server otherwise.
# name
type: string
default: wordpress
The name of the database used by the WordPress site.
# user
type: string
The user used by the WordPress site to connect to the database server.
# domain
type: array
The list of domain names mapped to the environment.
Domain name requirement
All domains names must either be managed by a DNS zone or have an issued certificate in the project region.
# gateway
type: string
The gateway type used by the environment. Allowed values are http
for HTTP APIs and rest
for REST APIs.
DNS changes when switching gateway types
Whenever you switch gateway types, the DNS records pointing to your environment will change. If Ymir manages the DNS zone used by your environment, it'll update your DNS records automatically. Otherwise, you will have to do it yourself. That said, even with a managed DNS zone, your environment will be briefly unavailable while the DNS changes propagate.
CloudFront page caching disabled with REST API.
When using a REST API, it isn't possible to use CloudFront for page caching. That's because the REST API already caches response using CloudFront. If your CloudFront caching is set to enabled
, it'll get downgraded to assets
automatically.
# log_retention_period
type: int
default: 7
Controls the duration (in days) that the environment's logs are retained in CloudWatch. Allowed values are 1
, 3
, 5
, 7
, 14
, 30
, 60
, 90
, 120
, 150
, 180
, 365
, 400
, 545
, 731
, 1827
and 3653
.
# php
type: string
default: 7.4
The PHP version used by the environment. The supported versions are 7.2
, 7.3
and 7.4
.
# warmup
type: int | false
default: 1
The number of website
functions that CloudWatch will keep warmed up. If set to false
, it disables the warming up CloudWatch rule.
# console / website
type: array
This is the array of values to configure the environment's Lambda functions. There are two function nodes: console
and website
. console
is the function used when running WP-CLI commands or any other background tasks. website
is the function connected to the API gateway and that handles all the HTTP traffic.
# memory
type: int
default: 256
for website
and 1024
for console
The amount of memory used by the Lambda function. The website
function has lower memory needs by default because most memory heavy tasks are handled by the console
function. Both default memory values are the lowest amount possible. If you lower them more, there might be issues during your function execution.
Low memory termination
If a function goes over the memory limit during its execution, it gets terminated automatically. So it's important to configure to give it enough memory to execute the worst case scenarios.
Memory cost
Lambda charges based on the configured memory used. So more memory, means a higher Lambda bill. This isn't much of a concern for the console
function since it won't get called a lot by default. But it's something to keep in mind when configuring the amount of memory that the website
function has.
# timeout
type: int
default: 30
for website
and 60
for console
The maximum amount of time (in seconds) that the Lambda function can run before Lambda terminates it. The maximum allowed values depend on the function type. website
cannot have a timeout larger than 30 seconds. console
can have a maximum timeout of 900 seconds (15 minutes).
API gateway timeout
The 30 second timeout limit for the website
function is due to a limit with AWS API gateways. An API gateway will terminate a connection after 30 seconds. This isn't modifiable.
This can be a significant technical hurdle if your WordPress site has long running operations that take more than 30 seconds to complete. In that scenario, these long operations need to be offloaded to a WP-CLI command or some external service.