Docs

Your first package

This document provides a step-by-step tutorial on how to get your first package created and installed using PKG Deploy.

It goes into detail on how to create files in Github, if you already know how to use Git and Github you can skip those bits.

We will guide you through:

Prerequisites for creating your first package

  • A Github account
  • A Linux machine or remote server to install the package on
  • An understanding of which package format you need to create for the machine above. We can create both deb and rpm packages
    • deb packages are supported on Debian-based systems such as Debian, Ubuntu etc
    • rpm packages are supported on RPM-based systems such as RHEL, CentOS and Fedora etc

Creating a code repository

Begin by creating a new repository on GitHub. You may skip this section if you intend to use an existing repository.

  1. Open up GitHub and create a new repository
  2. Fill out the new repository form

    • Under owner select your user profile
    • Enter the name hello-world
    • Select Private
    • Check Initialize this repository with a README
    • Click on Create repository

    Screenshot of Github's create repository page

  3. Now we want to create a new file that will be installed via the package we are going to build

    • On the Github repository page click Create new file
    • In the Name your file input at the top enter in helloworld
    • We will create a very simple bash script which will output Hello world whenever it is run.

      #!/usr/bin/env bash
      echo "Hello world"
      
    • Enter the above 2 lines into the main text area on the page

    • In the first input under Commit new file type Adding helloworld bash script
    • Click on Commit new file to add this file to the git repository

    Screenshot of Github's create new file page

Setting up PKG Deploy

Now there is a Git repository to work with, you need to go through the PKG Deploy setup.

  1. Log in to PKG Deploy via Github
  2. Authorize the PKG Deploy application access to your GitHub account
  3. You should now be greeted with a Setup page - If you are not, you can access the setup page via this link
  4. Select the same organisation you selected for the owner when creating the Github repository
  5. Click Setup this organisation to get started

    Screenshot of PKG Deploy's setup page

    Creating a package repository

    To be able to install the packages that we create they need to be hosted. PKG Deploy will create a package repository to do this for you.

  6. Select the type of repository you want to create. This will depend on what type of package you want to build. If you want to create deb and rpm packages both can be selected

  7. Click Create repository. This will create a private and secure package repository for the organisation you selected in the previous step

    Screenshot of PKG Deploy's setup repo page

    Adding a project

  8. In the list of GitHub repositories select the hello-world project that was created at the start of this guide

    Screenshot of PKG Deploy's select project page

  9. Next select Github Webhook. This will automatically trigger releases via Github when new releases are created in Github

  10. Click Add project. A project will be created in the background for this code repository. A deploy key and webhook will also be added in Github for this repository

    Screenshot of PKG Deploy's select project trigger page

PKG Deploy is now configuration and ready to start building packages for your hello-world Github repository.

Creating a configuration file

Next, we need to create a configuration file to tell PKG Deploy what package to build and how.

  1. In Github go to the hello-world repository that was created before
  2. Click on Create new file

    • In the Name your file input at the top enter in .pkgdeploy/ then config.yaml
    • We will add a simple configuration file. It creates a deb package called pkgdeploy-helloworld and copies the helloworld file we added to Github before to the directory /usr/bin/ on the end-user machine

      name: pkgdeploy-helloworld
      format: deb
      
      install:
        copy:
          - source: ./helloworld
            destination: /usr/bin/helloworld
      

      If you want to create an RPM package instead, change the format to rpm

      name: pkgdeploy-helloworld
      format: rpm
      
      install:
        copy:
          - source: ./helloworld
            destination: /usr/bin/helloworld
      
    • Enter the above configuration example into the main text area on the page

    • In the first input under Commit new file type Adding my first PKG Deploy config file
    • Click on Commit new file to add this file to the git repository

    Screenshot of Github's create new file page

Triggering a release

You have now created a git repository and added all the files to it that are needed to create, package and set up PKG Deploy so it's watching the repo ready to build packages.

  1. Go to the hello-world Github repository
  2. Click on 0 releases in the navigation bar (highlighted in red in the screenshot below)

    Screenshot of Github's repository page with the releases button highlighted

  3. You should not have any releases yet. Click the Create a new release button

  4. On the release creation page

    • Enter 1.0.0 in the Tag version input
    • Enter 1.0.0 in the Release title input
    • Add a description if you want, this is not required
    • Click on Publish release

    Screenshot of Github's create release page

  5. In the background, Github will create a Git tag and then fire a webhook event to PKG Deploy letting us know a new release has been created. We will receive this event and start building your packages.

  6. To view the progress go to the PKG Deploy releases page
  7. Click on the 1.0.0 release for the hello-world project
  8. You will be taken to the release page. This page tracks the current progress of the release.
  9. Wait a few minutes until the release is complete and has been uploaded to you package repository

    Screenshot of the PKG Deploy release page

Configuring your machine

Now you have a package created and uploaded to your package repository. Before you can install any packages you need to make sure your machine is aware of the package repository you created.

  1. In PKG Deploy go to the Package Repos page
  2. Select the package repository you created earlier
  3. On this page, you will see a link to download an installer (highlighted in red in the screenshot below). Click Download.

    Screenshot of the PKG Deploy package repo page

  4. Copy the file onto the server (assuming you are in the same directory as the installer)

    scp ./*repo-pkgdeploy_1.0.0-1.deb user@server:/tmp/
    
  5. Install the package repository installer. Below are examples for both debian and RPM based servers:

    Debian / deb / APT:

    $ ssh user@server
    $ dpkg -i /tmp/*repo-pkgdeploy_1.0.0-1.deb
    $ wget -qO - https://www.pkgdeploy.com/pkgdeploy_gpg.asc | apt-key add -
    $ apt update
    # Then to check everything is setup correctly
    $ grep '^Package:' /var/lib/apt/lists/pkgdeploy-repo*
    

    RPM / Yum:

    $ ssh user@server
    $ yum install /tmp/*repo-pkgdeploy_1.0.0-1.rpm
    $ yum clean expire-cache
    
    # Then to check everything is set up correctly
    $ yum repolist  # List all of the repository on the machine
    $ yum repo-pkgs myorg-pkgdeploy list  # List packages in your repository
    

    Here is an example of the Debian commands being run on a Ubuntu server

Installing the package

Now for the most important step, deploying your code via the package you have created. Make sure you have used the installer to add the PKG Deploy repository you created in the steps above.

  1. Use APT or Yum to install the pkgdeploy-helloworld package we created above

    Debian / deb / APT:

    $ apt install pkgdeploy-helloworld
    

    RPM / Yum:

    $ yum install pkgdeploy-helloworld
    
  2. Once this has completed successfully the helloworld command should be added to your path. You should be able to run it with

    $ helloworld
    > Hello world
    

    Here is an example of the install being done via APT on a Ubuntu server

Congratulations!

You have successfully created your first package!

Nice work. You are awesome.

Now let's change some code, trigger a new release and install the new version of the package.

Making a change to the code

  1. In Github go back to the hello-world repository
  2. Select on the helloworld file we created earlier
  3. Click the Edit icon which looks like a pen

    Screenshot of Github's edit file button

  4. The edit page is the same as the new file page, except the file content is filled out

    • We will update the bash script to print PKG Deploy instead of Hello world

      #!/usr/bin/env bash
      echo "Hello PKG Deploy"
      
    • Remove the current contents of the file and enter the above 2 lines instead

    • In the first input under Commit changes type Updating helloworld bash script
    • Click on the Commit changes button to update the file

    Screenshot of Github's edit file page

Triggering a new release

  1. Go back to the main page for the hello-world Github repository
  2. Click on 1 release in the navigation bar (this was 0 releases last time)
  3. You should see the previous version 1.0.0 we created. Click on the Draft a new release button
  4. On the release creation page

    • Enter 2.0.0 in the Tag version input
    • Enter 2.0.0 in the Release title input
    • Add a description if you want, this is not required
    • Click on Publish release

    Screenshot of Github's draft new release page

  5. Just like last time, Github will create a Git tag in the background and fire of a webhook to us

  6. To view the progress go to the PKG Deploy releases page this time selecting release 2.0.0

    Screenshot of the PKG Deploy release page for version 2.0.0

Upgrading the package

Now for the final step in upgrading the package on your machine. Everything is already configured so this is nice and easy. As we have used semantic versioning, APT or Yum automatically know our new 2.0.0 version is an upgrade.

  1. To upgrade the pkgdeploy-helloworld package that was created above we need to ensure your system has the latest repo information in order to enable the upgrade of the package

    Debian / deb / APT:

    $ apt update
    $ apt install pkgdeploy-helloworld
    

    RPM / Yum:

    $ yum clean expire-cache
    $ yum install pkgdeploy-helloworld
    
  2. Once this has completed successfully the helloworld command will have been updated. Running it will now print Hello PKG Deploy instead of Hello world

    $ helloworld
    > Hello PKG Deploy
    

    Here is an example of the install being done via APT on a Ubuntu server

Double congratulations!

You have now created 2 packages and installed both of them.

That is it for this guide. You should now have a good idea of the basic package creation flow.

Next steps

Now it's time for you to start building packages for your applications.