Using GitHub For Your ZenPack

From Zenoss Wiki
This is the approved revision of this page, as well as being the most recent.
Jump to: navigation, search

We recommend using GitHub for storing your ZenPacks. This page will guide you through the process of initializing a GitHub repository from a Linux system, and ensuring that the Linux system is configured optimally for ZenPack development.

Initial One-Time Setup

This section covers all initial one-time setup steps to configure a Zenoss install for ZenPack development.

Create an RSA/DSA SSH KeyPair

On your local Zenoss development system, ensure that you have an ssh RSA/DSA private/public key pair generated for the zenoss account. These key pairs will be used to conveniently access your new git repository without having to supply a password each time.

If you already have key pairs generated, you can find them in the .ssh sub-directory within the zenoss home directory (typically /home/zenoss) and are named id_dsa or id_rsa, with the public keys being stored in id_dsa.pub or id_rsa.pub:

# su zenoss
$ cd
$ ls .ssh/
id_dsa  id_dsa.pub  known_hosts
$ 

It will be most convenient if these are installed under the zenoss account, since this is typically the account you will use for ZenPack development.

Bulbgraph.png Note: Note that if you have Zenoss configured to monitor devices using SSH and are currently using passwords, adding an RSA/DSA key pair to the zenoss account will likely confuse Zenoss into trying key-based authentication, and authentication will fail unless the remote systems are configured to accept your RSA/DSA key. If this applies to you, go to Configuration Properties and set zKeyPath to an empty string. This will disable key-based authentication via SSH.

If you do not have a key pair generated, you can do so using the following command:

# ssh-keygen -t dsa
Generating public/private dsa key pair.
Enter file in which to save the key (/root/.ssh/id_dsa): 
Enter passphrase (empty for no passphrase): ******* 
Enter same passphrase again: *******
Your identification has been saved in /root/.ssh/id_dsa.
Your public key has been saved in /root/.ssh/id_dsa.pub.
The key fingerprint is:
d5:e2:c7:97:94:3c:12:5a:fa:fe:99:19:84:f1:18:5a root@quicktest
The key's randomart image is:
+--[ DSA 1024]----+
|            o    |
|           = o . |
|          = E =  |
|         o * O o |
|        S o * =  |
|           o o   |
|            . .  |
|             . = |
|              =  |
+-----------------+
# 

If you specify a passphrase, it will be used to encrypt your private key (~/.ssh/id_dsa) on disk, to prevent it from being easily used by someone else who might acquire it.

Install Git and Keychain

If you specified a passphrase to encrypt your private key, it is recommended that you use Keychain, which will alleviate you of the need of supplying your passphrase to decrypt the key for each connection.

Use your distribution's package manager to install both the keychain and git packages. If keychain is not available, download the tarball and install as root:

# tar xvf keychain-2.7.1.tar.bz2
# cd keychain-2.7.1
# make
# cp keychain /usr/local/bin

Set Up Git

As the zenoss user, run the following commands to set reasonable defaults for git:

$ git config --global user.email "me@here.com"
$ git config --global user.name "Daniel Robbins"
$ git config --global push.default current

This will configure git with your email, name, and tell git to use intuitive push/pull behavior.

Set Up Keychain

To enable keychain, add the following lines to the zenoss account's ~/.bash_profile file:

eval $(keychain --eval id_dsa)

Then, source your ~/.bash_profile to initialize keychain. It will ask for your private key passphrase. Once you enter it, keychain will cache your passphrase in RAM using ssh-agent so you do not need to type it in again until you reboot your system. This will allow the zenoss account to authenticate with GitHub without having to supply a password, after you upload your public key to GitHub. We'll cover this step below.

Using GitHub

To use GitHub, you will need to log in and if you have not already, create a GitHub account.

Upload SSH Key

You will will want to upload your SSH public key to GitHub so that it will recognize it for SSH-based access. To do this, go to Account Settings (tools icon), then go to SSH Keys. Click Add SSH Key, and give the key a name of your choice, and paste the output of cat ~/.ssh/id_dsa.pub into the text box. Click Add key and your new key will be saved, and GitHub will grant this key read and write access to all of your public and private GitHub repositories, including any ones you create in the future.

Create a Repository

Now that all the one-time setup is completed, you're now ready to create a repository for your ZenPack. To do this, first go to GitHub and on the main page, you should see a New Repository button. Click this button.

Provide a logical name for the repository. This will be used as the directory name for the respository. It is also recommended that you provide a description. If you would like to allow others to see the repository, make it public. GitHub allows you to create private repositories that only you can see, but you are required to pay for this feature. But public repositories can be created for free.

You can choose to create the repository with a README. We'll skip this option and walk you through the full process of initializing your repository.

Assuming you gave your repository the name "test", GitHub will then instruct you to perform certain steps to initialize your repository. I strongly recommend tweaking the steps to not use https://-style connection if at all possible, as this will allow you to leverage Keychain and your SSH keys.

Instead of the GitHub steps, you can initialize your GitHub repository by typing the following commands under the zenoss account on your Linux development machine:

$ cd /opt/zenoss/ZenPacks
$ mkdir test
$ cd test
$ git init
$ touch README
$ git add README
$ git commit -m 'first commit'
$ git remote add origin git@github.com:your_github_username/test.git
$ git push -u origin master

You will now have made your first commit and pushed it up to GitHub.

gitignore

When you use git, it is very easy to accidentally commit temporary files that you may not intend to, particularly when developing ZenPacks. For this reason, I strongly recommend that you create a .gitignore file alongside the README file at the root of your repository. This will tell git to ignore certain files and directories when you perform a git add command:

*.pyc
*.pyo
.svn
*.egg-info
build
dist

This will prevent compiled python files, as well as temporary distutils build and dist directory contents from being added to git. It will also protect against adding .svn directories, if you happen to be migrating from subversion.

After creating .gitignore, add, commit and push as follows:

$ git add .gitignore
$ git commit -m "adding .gitignore file"
[master (root-commit) fe080a8] adding .gitignore file
 0 files changed, 6 insertions(+), 0 deletions(-)
 create mode 100644 .gitignore
$ git push

You local git repository as well as your GitHub master repository will now contain the .gitignore file.