Examples

In this document there are 2 examples with a small explanation of each.

For real world examples check out the other examples section below. It includes links to our public projects on Github with full breakdowns of what the configuration files do.

With only required options

In this example we are installing a helloworld command which can be called via a CLI:

name: pkgdeploy-helloworld
format: deb

install:
  copy:
    - source: ./helloworld.sh
      destination: /usr/bin/helloworld

Breaking down the configuration - we are:

Creating a package called pkgdeploy-helloworld. This means you will be able to use apt install pkgdeploy-helloworld to install
The package is going to be a .deb which will be installable on OS's such as Ubuntu
Copying the file helloworld.sh at the root of a Github repository to /usr/bin/helloworld

Once this package is installed a user on the system will be able to run a CLI command called helloworld.

While this is the most simple configuration file possible it is generally considered to fill out as much base information as possible such as the license, maintainer and architecture.

With all options

For this example we are creating a package to install a basic python web service.

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

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

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

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

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

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

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

To help breakdown the configuration, we are:

Creating a package called my-app. This means you will be able to use apt install my-app to install
The package is going to be a .rpm which will be installable on OS's such as Centos
The package will be built on a Centos 7 system
Stating the package should be installed on anything with 64-bit architecture
Setting a nice description, url and maintainer giving more information to anyone who inspects the package.
Stating the license the code is release under is GNU General Public License version 3
To build the software
- python36-pip must be installed to run the build steps
- All build steps should be done in a directory at/var/lib/myapp/.
- The commands here create a python virtual environment and use pip to install all the 3rd party modules needed to run the application.
If the package is being installed for the first time before_install notes 3 export commands should be run, each setting an environmental variables
On installation of the package:
- Both python36 and nginx will be installed automatically by Yum. Note: Both packages will need to be available to Yum via one of the configured repositories. In this caseyum install epel-release should have been run first as epel includes both of the packages needed
- As part of the deployment a user called myuser and group mygroup will be created withmyuser being put into mygroup.
- All of the code within the git repository (./) will be copied to /var/lib/myapp/ except for files that end in *.md or have test in their path. The files and directories will be owned by myuser in group mygroup and have the permissions 755/rwxr-xr-x
- Copy The file myapp-nginx.conf at the root of the git repository will be copied to /etc/nginx/conf.d/myapp.conf
- The file myapp.service will be copied to /etc/systemd/system/
- A curl command will be run as the final step of the install
After the install steps have been carried out 2 commands will be run. The first to reload nginx's config and the other to start the new service
If this package is being upgraded from an older version then run a command. In this case an rm command to remove the directory /var/lib/myapp/old-logs/
After any upgrade is complete the commands at scripts/upgrade.sh from the root of the git repository should be run. After that the myapp service should be restarted.
If someone decodes to uninstall the app at any point - before removing all of the files that were added as part of the install process the myapp service should be stopped
Finally once the uninstall has completed the myuser should be disabled

Other examples

helloworld-example - Basic example with only the required fields. Creates 2 packages, one deb and rpm
flask-example - Install a basic Flask web app using Python 3, pip, Flask, gunicorn and nginx
fastapi-example - Install a basic FastAPI web app using Python 3, pyenv, uvicorn, FastAPI, gunicorn and nginx
django-example - Install a basic Django web app using Python 3, pip, Django, Postgres11, gunicorn and nginx with psycopg2 being build from source for example purposes