PKG Deploy

Docs

Full reference

In this document there is a breakdown of all of the different fields that are available within a configuration file, their value type, if required and, a description.

You can see a complete configuration in our full YAML example.

Full list of key-values

Base

Base

It is always considered a good idea to add as many of the key-values as possible.

For example, while they are not required fields, fields such as description, license and maintainer give people a lot more information about your package which can only be beneficial to end users, even if they are just within your organisation.

Key name Type Required Description
name string Yes Name of the package which is used when installing via APT or YUM. It can only contain lowercase characters, numeric characters, hyphens (-), plus signs (+) and full stops (.). Regex used: [a-z0-9-.+]
format string (multi-choice) Yes The type of package you want to create. Must be either deb or rpm
distribution string (multi-choice) No The specific Linux distribution the software will be built on. See the valid choices below. Defaults to ubuntu18 (deb) and centos7 (rpm). This is subject to change due to distribution maintenance periods
architecture string (multi-choice) No What architecture your package supports. See the valid choices below. Defaults to 64-bit
description string No A full description of the software packaged. Use YAML multi-line strings to have a multi-line description
url string No The full URL for more information about your software. Can just be an upstream project website
license string No Short License identifier for the license you want to release your code under. It will default to 'Unknown''
maintainer string No Must be in format "Name <[email protected]>". It will default to "Unknown <[email protected]>" if not supplied
build key-value No See build section
install key-value Yes See install section
before_install string or list of key-values No See commands section
after_install string or list of key-values No See commands section
before_upgrade string or list of key-values No See commands section
after_upgrade string or list of key-values No See commands section
before_uninstall string or list of key-values No See commands section
after_uninstall string or list of key-values No See commands section

Valid choices

  • format - deb or rpm
  • distribution (format dependant):
    • deb - ubuntu14, ubuntu16, ubuntu18, ubuntu20, debian8, debian9, debian10 - Defaults to ubuntu18 if not supplied
    • rpm - centos6, centos7, centos8, rhel6, rhel7, rhel8, centos8, fedora24, fedora27, fedora30, fedora31, fedora32 - Defaults to centos7 is not supplied
  • architecture - 64-bit, 32-bit, ARM 64-bit, ARM 32-bit, any - Defaults to 64-bit if not supplied
    • Note: These architectures are translated into the correct but less human readable values such as i386, x86_64, amd64 etc

build

Key name Type Required Description
requires list of strings No A list of any packages that are required to run the build commands. You need to assume the build server is fresh minimal install with no applications installed. requires works slightly different for build and install. See requires for more information
directory string No The directory the code will be built in. This can be important if a build step injects a path to your code such as in a shebang, often the case when using virtual environments in python or npm node_modules. If needed it is often set to a location code is copied to in your install step
commands string or list of key-values Yes See commands section

install

Key name Type Required Description
requires list of strings No A list of any packages that your application depends on to run. requires work slightly different for build and install. See requires for more information
user String No* Creates a user with this name as part of the install
group String No* Creates a group with this name as part of the install
copy list of key-values No* See copy section
commands string or list of key-values No* See commands section

* One of these fields is required. While each of the keys is marked as not required you must include at least one of user, group, copy or commands within the install section.

Copy

For a more in-depth breakdown check out the Copying code page

Copy requires a list of key-values. Each of these key-values lists can have the following keys

Key name Type Required Description
source string (relative path) Yes Relative path to a file or directory in your git repository you want to copy
destination String (absolute path) Yes Absolute path to the install location on the end-user machine
user String No The user that should own what is being copied
group String No The group that should own what is being copied
permissions String No chmod numeric notation of the permissions given to what is being copied. E.g. 755

Commands

For a more in-depth breakdown check out the Running commands page

Any command section may be a single line string, multi-line string or a list of key-values.

The keys in the table below are only needed if you want to use a list, strings have no key-values.

Key name Type Required Description
run string No* Single string command
file String (absolute path) No* Relative path to a file with commands that need to be run. Allows for commands to be used across multiple configuration files

* One of these fields is required if using a list. While neither of the keys is marked as required you must have at least one of run or file in a command section if you use a list and not a string.

requires

The requires key-value allows you to specify what other software your application depends on. It works slightly differently depending on if it is being used in the build or install key-value.

build:

Each package is individually installed on the build server one at a time via an APT/YUM command in the order they are specified. This allows one requirement to depend on another. For example, you can install a package repository before then installing a package from that repository.

For rpm builds, the build requires also supports be HTTP URL's as they are supported by yum.

To use HTTP URL's in when building deb packages a combination of wget and dpkg can be used within the commands key-value

install

Package dependencies are directly controlled via APT/YUM. as dependency management on the end-user machine can be far more complicated. This is because the package manager needs more control in case a package install fails and it needs to remove all dependencies etc.

Full YAML Example

The below example is just to show a technically valid configuration file. It is not intended to be used but includes all of the different fields available. Where a key supports multiple value types we have included examples of the different types.

For more in-depth examples with full explanations please see the examples page

name: my-app
format: deb
distribution: ubuntu18
architecture: amd64
description: New awesome application
url: https://www.pkgdeploy.com
license: GPLv3
maintainer: MyApp Engineers <[email protected]>

build:
  directory: /var/lib/myapp/
  requires:
    - python36-devel
    - python36-pip
  commands: |    # Commands multi line string
    python3.6 -m venv ./venv/
    ./venv/bin/pip install -r requirements.txt

install:
  requires:
    - python36
    - nginx
  user: myuser
  group: mygroup
  copy:
    - source: ./
      destination: /var/lib/myapp/
      user: myuser
      group: mygroup
      permissions: 0755
    - source: myapp.service
      destination: /etc/systemd/system/myapp.service
  commands: |
    curl http://example.com -o /var/lib/myapp/example.txt -s

before_install: |  # Commands multi line string
  export LANG=en_US.UTF-8
  export LANGUAGE=en_US:en
  export LC_ALL=en_US.UTF-8

before_upgrade: |  # Commands multi line string
  rm -rf /var/lib/myapp/old-logs/

after_install:  # Commands list of key values with run keys
  - run: nginx -s reload
  - run: systemctl enable myapp
  - run: systemctl start myapp

after_upgrade:  # Commands list of key values with file and run keys
  - file: ./scripts/upgrade.sh
  - run: systemctl restart myapp

before_uninstall: systemctl stop myapp  # Command single line string

after_uninstall: usermod -L myuser  # Command single line string