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:

Creating a code repository in Github and adding a file to it
Setting up PKG Deploy for the first time
Creating a simple configuration file
Triggering your first release and building a package
Adding a PKG deploy package repository and using it to install a package
Updating your code and triggering a new release
Upgrading the package on your server

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.

Open up GitHub and create a new repository
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
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

Setting up PKG Deploy

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

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

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.
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
Click Create repository. This will create a private and secure package repository for the organisation you selected in the previous step

Adding a project
In the list of GitHub repositories select the hello-world project that was created at the start of this guide
Next select Github Webhook. This will automatically trigger releases via Github when new releases are created in Github
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

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.

In Github go to the hello-world repository that was created before
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

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.

Go to the hello-world Github repository
Click on 0 releases in the navigation bar (highlighted in red in the screenshot below)
You should not have any releases yet. Click the Create a new release button
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
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.
To view the progress go to the PKG Deploy releases page
Click on the 1.0.0 release for the hello-world project
You will be taken to the release page. This page tracks the current progress of the release.
Wait a few minutes until the release is complete and has been uploaded to you package repository

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.

In PKG Deploy go to the Package Repos page
Select the package repository you created earlier
On this page, you will see a link to download an installer (highlighted in red in the screenshot below). Click Download.
Copy the file onto the server (assuming you are in the same directory as the installer)
```
scp ./*repo-pkgdeploy_1.0.0-1.deb [email protected]:/tmp/
```

Install the package repository installer. Below are examples for both debian and RPM based servers:

Debian / deb / APT:

$ ssh [email protected]
$ 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 [email protected]
$ 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.

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
```
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

In Github go back to the hello-world repository
Select on the helloworld file we created earlier
Click the Edit icon which looks like a pen
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

Triggering a new release

Go back to the main page for the hello-world Github repository
Click on 1 release in the navigation bar (this was 0 releases last time)
You should see the previous version 1.0.0 we created. Click on the Draft a new release button
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
Just like last time, Github will create a Git tag in the background and fire of a webhook to us
To view the progress go to the PKG Deploy releases page this time selecting release 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.

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
```
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.

Find out how to run commands as part of the install steps
Get a better understanding of how to copy files as part of a package install
Learn about all of the different fields and operations which are supported when creating packages