The Boxfile
Whenever you synchronise the changes you made to your local repository with the
freistilbox Hosting Platform by doing a git push, you trigger the freistilbox
deployment process. This process updates the application code on each of your
boxes. It also does everything that’s necessary to integrate your application
with the hosting stack. The details of this integration are defined in a
configuration file named Boxfile. It tells freistilbox how to
integrate your application into the hosting environment.
Location and format
The Boxfile is in YAML format and must be located in the topmost directory of
your application repository.
Because we have to adapt the Boxfile behaviour from time to time, we recommend
setting the Boxfile version explicitly:
version: 2.0
[!warning]
Changing the format version of an existing Boxfile will probably result in a
different deployment behaviour that needs to be addressed. Please refer to our
detailed Boxfile documentation for the specifics.
Environment-specific files
Modern software workflows include developing and testing in multiple staging
environments, and freistilbox supports these workflows. In order to
do so, it has to solve the following problem: All staging websites will be
deployed from the same Git repository but require different settings for the
database connection, among other things. That’s why the Boxfile allows you to
declare certain files in your code base as specific for a single deployment
stage.
For starters, we’ll only use the “production” stage, the website instance
that’s aimed at the public. And to keep things simple, we’ll declare only one
file as environment-specific: the main configuration file of your application.
Later, you can lean about all the details in the Boxfile
documentation.
Drupal
Drupal’s configuration by default lives in sites/default/settings.php. In the
Boxfile, we tell freistilbox that docroot/sites/default/settings.php is
going to vary between staging environments, and that in “production”, we’d like
to have the file settings.production.php (in the same directory) take its
place:
env_specific_files:
docroot/sites/default/settings.php:
production: settings.production.php
Notice that we won’t have to repeat the full path for each environment-specific
file name; freistilbox assumes that all variants live in the same directory
together.
WordPress
In a similar fashion, we can make the WordPress configuration file
environment-specific:
env_specific_files:
docroot/wp-config.php:
production: wp-config.production.php
Shared folders
The “shared” in “shared folders” means they’re shared by all the servers that
deliver your website content on freistilbox. They’re not shared between
different websites. That your web application runs on multiple servers at the
same time is one of the most important differences between freistilbox and
conventional hosting. While your code base is copied to each of these “boxes”,
as we lovingly call them, asset files that are created by your application need
to be stored at a central place where they’re available to all boxes. Where
these asset files are located in the file system differs from CMS to CMS and
from website to website. That’s why the Boxfile lets you define these
locations yourself.
Let’s take this Boxfile section:
shared_folders:
- docroot/sites/default/files
As you can tell from the path sites/default/files, this section is from a
Boxfile of a Drupal installation. With this configuration, the deployment
process will set up your application’s file system in such a way that
everything under sites/default/files will reside on the shared file storage.
Armed with this knowledge, you should be able to guess how the shared_folders
section for a WordPress application should look like…
shared_folders:
- docroot/wp-content/uploads
[!important]
The shared folders you declare in theBoxfileare created automatically by
our deployment process. That’s why it’s important that your application
repository does not contain these directories. You can prevent them from
being added accidentally by telling Git to ignore them.
Examples
This is how a basic Boxfile for Drupal would look like. It defines one shared
folder for asset files and two variants of .htaccess and application
configuration, one for the “production” environment and one for “testing”:
version: 2.0
shared_folders:
- docroot/sites/default/files
env_specific_files:
docroot/.htaccess:
production: .htaccess.production
testing: .htaccess.testing
docroot/sites/default/settings.php:
production: settings.production.php
testing: settings.testing.php
And this is a version for WordPress:
version: 2.0
shared_folders:
- docroot/wp-content/uploads
env_specific_files:
docroot/.htaccess:
production: .htaccess.production
testing: .htaccess.testing
docroot/wp-config.php:
production: wp-config.production.php
testing: wp-config.testing.php
Next: Let’s set up the platform services your web application
is going to need!
This document is version controlled - suggest changes on GitLab.