Configuration
Server
The server
part of the Pillar data contains which edition of webserver
(vanilla or zendserver) and which webserver (apache or nginx) should be
used.
vhosting:
server:
webserver: nginx
edition: vanilla
note
If
zendserver
is being configured as edition this formula should be available on your Salt fileserver and configured as well.This does duplicate the webserver part since this particular formula only reads its own information. If the formula is not available it cannot install ZendServer (and components) and if the Pillar data is missing it will install it with default values which may differ from your requirements.
If
letsencrypt
is being used, the officialletsencrypt
formula should be installed as well.
Users
A user is only created when a ‘vhost’ is set, since this the only reason (currently) why a user would be needed.
For users individual flags can be set:
deploy_structure
Create a
data
and areleases
folder. The webroot is a symlinked to../releases/current
unless the vhost is set to use ‘public’ (more about this later)
Vhosts
If at least one vhost
key is specified in the user-tree of the
vhosting pillar it will automatically install the configured webstack.
Vhosts depend on users. A user will be created automatically and will be used for all of the domains that belong to this user.
The minimal configuration for a vhost is:
vhosting:
users:
example:
vhost:
example.com: {}
note
An empty dictionary is mandatory if no parameters are specified.
All default values will be used instead.
The following keys can be defined:
webroot_public
A boolean value (False by default) telling the webserver configuration to use /public as entry point. This is required for some frameworks such as Laravel or Zend Framework.
webroot
A string with the desired webroot location instead of auto-generated one based on the domain.
aliases
A list of aliasses (with a dash in front of them) that need to be added to the vhost.
redirect_to
A string which will - if set - redirect the domain to the given URL and uses the
redirect
vhost template.This may be used in conjunction with
ssl
proxy_pass
A string which will - if set - setup the webserver to proxy the domain to the given URL and uses the
proxy
vhost template.This may be used in conjunction with
ssl
ssl
A dictionary containing at least
key
andcert
, optionallyca
for the CA chain (required for certain SSL providers), booleanforward
to force non-ssl to SSL and booleanspdy
to enable SPDY mode (if a compatible webserver is being used).Setting "letsencrypt" to "True" results in automatically retrieve and renew a certificate for this domain via LetsEncrypt
listen_ip
A string containing the listen IP (any IP by default, may be set to a specific one. Please note: all vhosts should be explicitly set if this is being used!)
listen_port
The webserver listens on port 80, can be overruled using this.
listen_port_ssl
Same as
listen_port
but for SSL.Depending on the vhost template more parameters may provided (e.g for nginx:
logdir
,try_files
,index
,fastcgi_pass
,fastcgi_params
orextra_config
)
MySQL Databases
If the mysql_database
key is specified in the user-tree of the vhosting pillar it will automatically install MariaDB 10.0 via the built-in state.
A user can have one or more databases and will always get a 'pair' consisting of: a database, a user and the specified password.
The minimal configuration for a MySQL database is:
vhosting:
users:
example:
mysql_database:
example:
password: 'topsecret'
The following keys can be defined:
host
A string containing the host the grant should be made on. By default this is localhost, but you can set this to any host (including
%
)
hosts
A list (with a dash) containing all hosts and IP's additional grants should be created for. All privileges are granted with the same password as the global user.
Cronjobs
Since the cron
daemon is always installed and running it is not being installed or managed directly by this formula.
If one or more cronjobs are specified for a user they will be installed. Cronjobs are created under the user they belong to in the tree.
The minimal configuration for a cronjob is:
vhosting:
users:
example:
cronjob:
example:
cmd: '/tmp/test.sh'
If no times are set, the *
value is being used (run every minute on every day etc).
Optionally the following keys can be specified:
user
A string the cronjob should run as, by default the owner where the cron is placed under
minute
The minute(s) the cron should run on
hour
The hour(s) the cron should run on
daymonth
The day of the month the cron should run on
month
The month the cron should run on
dayweek
The day of the week the cron should run on
comment
An optional comment
PHP-FPM Versions
The vhosting module recognizes either the vanilla PHP-FPM 5.5 installation, or any combination of PHP-FPM 5.6 and PHP-FPM 7, provided by Ondřej Surý via the PPA. When specified, either PHP 5.6, PHP-FPM 7.0, or a combination of both will be installed.
Because both the phpfpm formula and the vhosting formula need to know what PHP-FPM versions are to be used, this must be set on both the global level like so:
phpfpm:
php_versions:
- '5.6'
- '7.0'
and on a per vhost basis as well:
vhosting:
users:
example:
vhost:
example.com:
php_version: '7.0'
This also allows for choosing between PHP 5.6 and PHP 7.0 on a per vhost basis.
If both the global PHP-FPM versions and the per vhost configuration are omitted, PHP 5.5 will be used instead.
Some warnings
- It is not possible to use PHP-FPM 5.5 together with either 5.6 or 7.0, as 5.6 will remove 5.5 and the formula does not manage 7.0 alongside 5.5.
- If other packages depend on either the package or service php5-fpm, it is not possible to use PHP-FPM 5.6 or 7.0, because of the init script being renamed.
- Support for native PHP7 (e.g. as provided in Ubuntu 16.04) is not yet implemented and requires the alternative versions setup to be used