Providence uses a set of environment variables to provision the guest, and you can specify most of them through your Vagrantfile. The following table summarizes the user-settable variables Providence recognizes. More information for specific variables is available below.
| Variable | Default value | Implied keywords |
|---|---|---|
| BUNDLER_CNF | /vagrant/Gemfile | ruby |
| CARGO_CNF | /vagrant/Cargo.toml | rust |
| CERT | /etc/ssl/certs/ssl-cert-snakeoil.pem | nginx |
| CKEY | /etc/ssl/private/ssl-cert-snakeoil.key | nginx |
| COMPOSER_CNF | /vagrant/composer.json | php |
| DOCKER_CNF | /vagrant/Dockerfile | docker |
| DOCKER_COMPOSE_CNF | /vagrant/docker-compose.yml | docker |
| GIT_DIR | /vagrant/.git | git |
| GITHUB_DIR | /vagrant/.github | github |
| GO_VER | go | |
| HG_DIR | /vagrant/.hg | hg |
| HUGO_DIR | hugo nginx | |
| HUGO_SRV | /srv/web | |
| JEKYLL_CNF | First _config TOML or YAML file in JEKYLL_DIR | |
| JEKYLL_DIR | Directory containing JEKLL_CNF or BUNDLER_CNF | jekyll nginx ruby |
| JEKYLL_SRV | /srv/web | |
| LANG | en_US.UTF-8 | |
| LOGIN_SHELL | /bin/bash | |
| LOGIN_SHELL_CNF | .bash_profile | |
| MARIA_VER | 10.5 | mariadb |
| MONGO_VER | 5.0 | mongodb |
| NODE_CNF | /vagrant/package.json | node |
| NODE_VER | Derived from NODE_CNF | node |
| PELICAN_CNF | First *conf.py file in PELICAN_DIR | |
| PELICAN_DIR | Directory containing PELICAN_CNF or PIPENV_CNF | nginx pelican python |
| PELICAN_SRV | /srv/web | |
| PERL_VER | perl | |
| PHP_VER | Dervied from WP_CNF or COMPOSER_CNF | php |
| PIPENV_CNF | /vagrant/Pipfile | python |
| PROVIDENCE | . | |
| PYTHON_VER | Derived from PIPENV_CNF | python |
| RUBY_VER | Derived from BUNDLER_CNF | ruby |
| RUST_CNF | /vagrant/rust-toolchain.toml | rust |
| RUST_VER | Derived from RUST_CNF | rust |
| SHELLSPEC_CNF | /vagrant/.shellspec | shell |
| SVN_DIR | /vagrant/.svn | svn |
| TEST_DIR | /vagrant/test | |
| WEB_DIR | nginx | |
| WEB_SRV | /srv/web | |
| WP_CNF | WP_DIR/readme.txt | |
| WP_DATA | https://github.com/WPTT/theme-test-data | apache mailhog mariadb php svn wordpress |
| WP_DIR | Directory containing WP_CNF or COMPOSER_CNF | apache mailhog mariadb php svn wordpress |
| WP_PLUGINS | . | apache mailhog mariadb php svn wordpress |
| WP_SRC | https://develop.svn.wordpress.org/branches | apache mailhog mariadb php svn wordpress |
| WP_SRV | /srv/web | |
| WP_THEME | apache mailhog mariadb php svn wordpress | |
| WP_THEMES | . | apache mailhog mariadb php svn wordpress |
| WP_VER | Derived from WP_CNF or COMPOSER_CNF | apache mailhog mariadb php svn wordpress |
| ZOLA_CNF | ZOLA_DIR/config.toml | |
| ZOLA_DIR | Directory containing ZOLA_CNF | nginx zola |
| ZOLA_SRV | /srv/web | |
| ZONE |
Guest locale. Must be a locale recognized by the guest.
Login shell to use. Defaults to /bin/bash. Providence will attempt to install
the preferred shell if LOGIN_SHELL is not listed in /etc/shells.
Login shell config filename. Defaults to .bash_profile. Providence will source
.profile and add PATH updates and eval calls from applications like nodenv
to this file on the guest.
Version of Node.js to install with nodenv. No default, but Providence
will use the version specified in NODE_CNF if found (e.g.
"node": ">=0.10.3 <15"). Note that Providence does not understand Node version
constraints and may attempt to install an incorrect version.
Version of PHP to install with phpv. No default, but Providence will use
the version specified in WP_CNF (e.g. Requires PHP: 7.4) or COMPOSER_CNF (e.g.
"php": ">=7.4") if found (WP_CNF takes priority). Note that Providence does
not understand Composer version constraints and may attempt to install an
incorrect version.
Space-separated list of keywords used to provision the guest.
| Keyword | Provisions |
|---|---|
| * | Everything |
| . | Based on project structure and configuration files |
| apache | Apache |
| couchdb | CouchDB |
| docker | Docker, Docker Compose |
| hg | Mercurial |
| git | Git, Git LFS |
| github | GitHub CLI |
| go | Go, goenv |
| hugo | Hugo |
| jekyll | Jekyll |
| mailhog | MailHog, postfix |
| mariadb | MariaDB |
| memcached | Memcached |
| mongodb | MongoDB |
| nginx | Nginx |
| node | Node.js, nodenv, node-build, NPM |
| pelican | Pelican |
| perl | Perl, perl-build, plenv |
| php | Composer, PHP |
| postgres | PostgreSQL |
| python | Pipenv, pyenv, Python |
| redis | Redis |
| ruby | Bundler, rbenv, Ruby, ruby-build |
| rust | Cargo, Rust, rustup |
| shell | ShellCheck, ShellSpec |
| sqlite | SQLite |
| svn | Subversion |
| webmin | Webmin |
| wordpress | WordPress, WP-CLI |
| xml | xmllint |
| zola | Zola |
Some keyword combinations trigger extra provisioning.
| Keyword | Keyword | Keyword | Provisions |
|---|---|---|---|
| git | svn | git-svn | |
| php | apache or nginx | ocp, Webgrind | |
| php | apache or nginx | mariadb, mongodb, postgres, or sqlite | Adminer |
| php | apache or nginx | memcached | phpMemcachedAdmin |
| php | apache or nginx | redis | phpRedisAdmin |
Some keyword and variable combinations trigger extra actions.
| Keyword | Variable | Action |
|---|---|---|
| docker | DOCKER_CNF | docker run -d (docker-compose takes priority) |
| docker | DOCKER_COMPOSE_CNF | docker-compose up -d |
| go | GO_VER | goenv install $GO_VER |
| hugo | HUGO_DIR | hugo -d $HUGO_SRV |
| jekyll | JEKYLL_DIR | jekyll build -d $JEKYLL_SRV |
| node | NODE_CNF | npm install |
| node | NODE_VER | nodenv install $NODE_VER |
| pelican | PELICAN_DIR | pelican -s $PELICAN_CNF -e OUTPUT_DIR=$PELICAN_SRV |
| perl | PERL_VER | plenv install $PERL_VER |
| php | COMPOSER_CNF | composer install |
| python | PIPENV_CNF | pipenv install |
| python | PYTHON_VER | pyenv install $PYTHON_VER |
| ruby | BUNDLER_CNF | bundle install |
| ruby | RUBY_VER | rbenv install $RUBY_VER |
| rust | RUST_VER | rustup toolchain install $RUST_VER |
| zola | ZOLA_DIR | zola build -o $ZOLA_SRV |
Note that Providence does not install Jekyll or Pelican on its own; you must have Jekyll or Pelican listed as a dependency in BUNDLER_CNF or PIPENV_CNF.
Version of Ruby to install with rbenv. No default, but Providence will
use the version specified in BUNDLER_CNF if found (e.g. ruby '~> 2.3.0'). Note
that Providence does not understand Bundler version constraints and may attempt
to install an incorrect version.
URL or file containing WordPress data to import with WP-CLI. Defaults to the theme unit test data from https://github.com/WPTT/theme-test-data.
Directory containg a WordPress project. Defaults to the directory containing
WP_CNF or COMPOSER_CNF (WP_CNF takes priority). If WP_DIR exists and
COMPOSER_CNF contains an apropriate custom WordPress type (e.g.
wordpress-plugin), Providence will create a link to WP_DIR in the correct
location (e.g. $WP_SRV/wp-content/plugins).
Space-separated list of WordPress plugins to install with WP-CLI. The
default value, ., is a placeholder for the following plugins:
Providence always installs wordpress-importer, regardless of the value of WP_PLUGINS.
Source URL for WordPress files. Defaults to https://develop.svn.wordpress.org.
Providence will attempt to download test files (e.g. a PHPUnit test config) from
WP_SRC into TEST_DIR when provisioning WordPress if appropriate TEST_DIR
directories exist (e.g. $TEST_DIR/phpunit).
WordPress theme to activate by default with WP-CLI.
Space-separated list of WordPress themes to install with WP-CLI. The default
value, ., is a placeholder for the following themes:
Providence always installs WP_THEME if specified, regardless of the value of WP_THEMES.
Version of WordPress to install with WP-CLI. No default, but Providence
will use the version specified in WP_CNF (e.g. Requires at least: 5.1) or
COMPOSER_CNF (e.g. "johnpbloch/wordpress": ">=5.1") if found (WP_CNF takes
priority). Note that Providence does not understand Composer version constraints
and may attempt to install an incorrect version.
Guest time zone. Must be a valid tz database value (e.g. America/Detroit).