Skip to content

Customising the build with .pkgr.yml

Jump to bottom Edit New page
Matthias Mair edited this page Jul 16, 2024 · 3 revisions

To customize the way your package is built, you can add a .pkgr.yml file at the root of your project repository. This file will be parsed by Packager when a build is run.

You'll find all the available options explained below.

targets

Use this option to specify which distributions to target. Each target accepts a YAML hash of options, which will overwrite any other option defined for all distributions.

The available distributions can be found in Supported distributions.

By default, packages will be built for ubuntu-20.04, centos-7, and debian-10.

Use the distribution name as a key to the targets hash, as follows:

dependencies:
  - default-dependency-1
  - default-dependency-2
targets:
  ubuntu-12.04:
    # overwrite dependencies only for ubuntu-12.04
    dependencies:
      - other-dependency-1
      - other-dependency-2
  ubuntu-14.04:
  debian-7:

If you just want to enable a target without any additional option, you can do as follows:

targets:
  ubuntu-14.04: true
  centos-6: true

buildpack

If you want to pass a custom buildpack to package your application, you can do so with the buildpack configuration option. Though we can not ensure that the resulting package will work. Please do contact us if you run into any issue.

buildpack: https://github.com/heroku/some-buildpack#branch

build_dependencies

In some cases, some of your app dependencies (e.g. gems with C extensions in the case of Ruby projects) may only be installed if specific development headers are available. To allow for the packaging process to succeed, you must list them with the build_dependencies option. This must be specified as a YAML array.

build_dependencies: 
  - libicu-dev
  - libmagickcore-dev
  - libmagickwand-dev

crons

Native packages allow you to easily set up cron jobs, to periodically run tasks for your application.

Let's say you need to run the rake crons:task1 every hour, here is what you need to do:

  1. Create a cron job definition in your repository, for instance in packaging/crons/my-app-task1:
# packaging/crons/my-app-task
1 0 * * * * root my-app run rake crons:task1 1>&2 >> /var/log/my-app/cron-task1.log

This cron task wll run as the my-app user (automatically created with your app), and will run the rake task in the context of your application using the cli.

  1. Declare your cron in the .pkgr.yml file:
crons:
  - packaging/crons/my-app-task1

Now, upon installing your package, your cron task will automatically be installed in /etc/cron.d/my-app-task1.

default_dependencies

Every package ships with default dependencies for each supported distribution (example). If you don't want them to be added to your packages (e.g. it does not make sense for Go applications), you can disable them as follows:

default_dependencies: false

dependencies

If your application requires additional system dependencies to be installed, you can add them with the dependencies configuration option.

This must be specified as a YAML array. For instance:

dependencies: 
  - "libicu44 | libicu42"
  - libpcre3
  - git-core

user

The name of the user under which your app processes will be run. If this user does not exist on the target machine, then it will be automatically created. Defaults to your application name(taken from Github, which can be overwritten in the app settings).

user: "custom-user-name"

group

The name of the group under which your app processes will be run. If this group does not exist on the target machine, then it will be automatically created. Defaults to user.

group: "custom-group-name"

before_precompile

This option is deprecated. You should use the before option.

In the case of complex apps, you might need to do a bit of housekeeping before the packaging process can start.This can include creating files or folders that should be present for running the app (but not necessarily checked into the repository).

In that case, you can add a bash script anywhere in your repository that does just that, and reference it with the before_precompile configuration option:

before_precompile: "packaging/debian/setup.sh"

after_precompile

This option is deprecated. You should use the after option.

If you need to run a task after the buildpack compilation step is finished, you can provide a path to a file to execute:

after_precompile: path/to/file.sh

before

Replacement for before_precompile, which instead of pointing to a file, must be an array of commands to execute before the packaging process starts. e.g.:

before:
  - mv some/file to/path

Note that before_precompile takes precedence over before if both are specified.

after

Replacement for after_precompile, which instead of pointing to a file, must be an array of commands to execute after the buildpack compilation step is finished.

Note that after_precompile takes precedence over after if both are specified.

after:
  - cp some/file target
  - rm -rf some/dir

before_install

If you need to execute things just before the package is installed or updated on the user's machine, you can specify a before_install option, the value being the path to a file in your repository (it must have a shebang, e.g. #!/usr/bin/env bash):

before_install: "packaging/debian/preinstall.sh"

The file will be called with the arguments given to preinstall files for the distribution where the package is being installed. For debian-based distributions, please refer to https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html.

after_install

As with before_install, you can specify that a file be executed just after the package has been installed or updated on the user's machine:

after_install: "packaging/debian/postinstall.sh"

The file will be called with the arguments given to postinstall files for the distribution where the package is being installed. For debian-based distributions, please refer to https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html.

before_remove

If you need to execute things just before the package is removed or updated on the user's machine, you can specify a before_remove option, the value being the path to a file in your repository (it must have a shebang, e.g. #!/usr/bin/env bash):

before_remove: "packaging/debian/preremove.sh"

The file will be called with the arguments given to preremove files for the distribution where the package is being removed. For debian-based distributions, please refer to https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html.

cli

By default, all packages come with a command-line utility to manage your application. In some cases it may not be needed, for instance if the application you're packaging is itself a command-line utility with its own executable.

If you don't want the built-in CLI to interfere, you can delegate all calls to your own executable by specifying:

cli: bin/my-cli

If you don't want any CLI to be installed at all, then put:

cli: false

env

You can set environment variables for use during the packaging process. To do so, use the env configuration option:

env:
  - HELLO=world

Those environment variables will NOT be available when installing the package (e.g. in pre/post install steps), only when the package is compiled.

notifications

Note : only available on Packager.io.

Whenever a build fails or is successful on a branch, the default is to send an email notification to the authors and committers of the relevant commits (but only those who have also an account on Packager.io).

If you wish to disable all email notifications, add the following to your .pkgr.yml file:

notifications: false

If you wish to notify a specific set of people, add them to the list of recipients. Only them will receive notifications:

notifications recipients:
  - one@example.com
  - other@example.com

runner

Only change if you know what you're doing.

Each distribution has a specific init system (sysvinit, upstart, systemd, etc.). Packages will automatically include init files for the target distribution, but you can override the default init system selected by using this option.

For instance to force using upstart:

targets:
  debian-7:
    runner: upstart-1.5

Or force using classic says init scripts:

targets:
  ubuntu-12.04:
    runner: sysv-lsb-3.1

Note that sysvinit scripts do not support the automatic respawning of crashed processes.

services

Note : only available on Packager.io.

Sometimes third-party software is required for the packaging of your app to be successful. For instance, some Rails apps require a database to be present when precompiling assets, or even an instance of Redis. If you need to have such services started automatically for you before the packaging process starts, you can easily specify them:

services:

  • postgres:10
  • redis

They will be made available on their default port and address, and will automatically be shut down when your build finishes.

Currently, you can specify the following services (please contact us if you need anything specific):

  • PostgreSQL
  • Redis
Add a custom footer
Add a custom sidebar
Clone this wiki locally