Build profiles

It is common to be simultaneously working with different versions of a website, each of which needs to be built in slightly different ways. A common scenario is to have a local version of the site so that you can test it on your own machine, and a production version that is deployed to a server. In Salal, build profiles are used to store information about how to build and deploy the site in each case.

Build profiles are placed in a JSON-format file called config/profiles.json. Here is a sample of the basic file structure for the scenario where you need test and production profiles. For clarity we just show the tree structure, not the full JSON syntax:

common
|---system
|---project
test
|---system
|---project
production
|---system
|---project

The common section is optional. Any configuration information you place in it will be used as a default value for all profiles. If you specify a value in both the common section and in a specific profile, the value from the specific profile will be used.

Within each section of the file, you can have a system subsection and a project subsection. Both are optional. The system subsection is for variables that control how Salal operates. The project subsection is for variables that you want available to the templating engine as your site is being built. A brief example will help illustrate the typical use of each.

The appropriate way to deploy a site can vary depending on your OS, what tools you have installed, the requirements of a hosting provider, and so on. In Salal, you indicate the appropriate command line to use with a system variable called deploy_command. Assuming the same command will be used for all your profiles, it makes sense to put it in the common section so you only have to specify it once. Here's an example of what that might look like in the profile file:

common
|---system
    |---deploy_command: rsync -e "/usr/bin/ssh" -av --exclude=/.well-known/ --delete {{build_dir}}/ {{deploy_destination}}

The text {{build_dir}} and {{deploy_destination}} are variable references. The variable references are replaced with the appropriate values at the time Salal deploys the site. The variable build_dir is set by Salal automatically. However, deploy_destination is something only the user would know, so it must be specified in the profiles file. Since there is no deploy destination for the test profile, this time we will put it in the production section rather than common:

production
|---system
    |---deploy-destination: sally@neatserver.com:myapp.mybiz.com

Thus far, we've been talking about variables that Salal uses for its own purposes. However, you may also have your own things that need to change depending on the profile. As an example, suppose you have a Python backend for your site. As part of that, you have several Python scripts that are run to handle requests coming in from the client. These scripts need to indicate where the Python interpreter can be found. And it's in a different location on the test machine and on the server. That can be handled with a project variable. First, put a variable reference in your script files:

#!{{python_path}}

Then, specify the appropriate path for each profile in your profiles file:

test
|---project
    |---python_path: C:/msys64/mingw64/bin/python.exe
production
|---project
    |---python_path: /home/sally/opt/python-3.6.2/bin/python3

This technique can also be used for building web pages, CSS, JavaScript scripts, SVG files, or any other kind of file where Salal can do variable substitution. And it can sometimes be useful even when the value is consistent across profiles. For example, suppose all pages of a particular type should load a given CSS file. You could hard-code the URL for the CSS file in your page template. However, it may be better for maintainability to use a project variable instead. You can put something like this in your template:

<link rel="stylesheet" href="{{special_style_file}}" type="text/css" />

And then put this in your profiles file:

common
|---project
    |---special_style_file: /css/style_for_sally.css