Configuration file basics

Syntax

Configuration files are YAML files with specific key-value pairs which control the package creation process.

Each file is assumed to have only one document. Files with 3 hyphens --- used to separate multiple documents may not be read correctly
To make multiple packages per release you need to have multiple configuration files in one git repository
Some of these key-value pairs have nested key-value pairs within them. Others may require their values to be strings, integers or lists.
Comments are supported using #' and will be ignored by the parser.

Where they live

At the root of your git repository create a directory called .pkgdeploy

Any YAML file (with extension .yml or .yaml) that starts with the word config (config\*.yaml / config\*.yml)

├── .pkgdeploy/
│   ├── config.yml
│   └── config_rpm.yaml
├── otherdirectories/
├── otherfiles.txt
└── README.md

For example all of the below will be picked up as configuration files:

./pkgdeploy/config.yaml
./pkgdeploy/config.yml
./pkgdeploy/config_ubuntu.yaml
./pkgdeploy/config_dev.yaml
./pkgdeploy/config_1.yml

Anything else within the ./pkgdeploy/ directory will be ignored by default. It can be a good place to store files related to installation such as shell scripts.

Sections

To help with explaining the configuration file we have broken it down into 'sections'. Sections are simply parts of the config which are key-value pairs. They may also have more key-value pairs within them.

# Base section - no indent
name: pkgdeploy-flaskapp
format: rpm
...


build:
  ...

install:
  ...

before_install:
  ...

before_upgrade:
  ...

after_install:
  ...

after_upgrade:
  ...

before_uninstall:
  ...

after_uninstall:
  ...

Base section

Includes the basic information for a package such as its name, format (rpm or deb), description and other information that can be included in the package. They are placed in the file with no indentation, generally at the top.

For a full list of all of the available key-values see the full reference page

install

This section is the only required section within the config. It gives the package instructions on how to deploy your software on the end-user machine.

Install instructions normally include copying files and / or running commands. It is also where you can tell APT / YUM what other packages your software requires to run so it can be automatically installed at the same time.

build

Sometimes your git repository does not contain all of the code needed to be installed on the end-user machine.

The build section instructs PKG Deploy to run certain steps before running the install step and creating the package.

For example, if you have a Javascript package with node_modules or a Python package with requirements you can install all of these 3rd party modules in the build to ensure all of the code needed for your software is pre-built within the package.

This stops these steps needing to be run as part of the deploy which has the following benefits:

Packages will always place the same code onto the end-user machine
No issue if a 3rd party module is updated between when you tested the package and when the end-user installs it. Great for ensuring what you tested gets released
If a 3rd party module is removed the package will still install without issue
The end-user machine does not need the build tools installed (for example a python project would not need python-pip installed)
Installs don't require internet access or use up extra bandwidth - the install itself does not need to connect to a specific software package-management system

before and after sections

These are places to put additional commands you want to run at different parts of the package install.

For more information on each of these sections see what the sections are made up of and when command sections are run.