Home

Awesome

GitHub Backup!

An App that helps you backup your GitHub Issues so that you can still work when (you/they are) offline.

<div align="center">

Build Status Inline docs codecov.io HitCount

</div>

Why?

As a person (team of people) that uses GitHub as their "single-source-of-truth" <br /> I need a backup of GitHub issues <br /> so that I can see issue history and/or work "offline". <br /> (either when I have no network or GH is "temporarily offline")

What?

GitHub (Issue) Backup is an App that lets you (unsurprisingly):

  1. Store a backup of the content of the GitHub issue(s) for a given project/repo.
  2. Track the changes/edits made to issue description and comments. see: dear-github/issues/129
  3. View all your issues when you or GitHub are "offline"

How?

The app is built using the Phoenix Web Framework <br /> (using the Elixir programming language) <br /> and Tachyons UI ("Functional CSS") system. <br /> While you can run the App without knowing Elixir or Phoenix <br /> (see instructions below), if you want to understand how it works, <br /> we recommend taking the time to learn each item on the list. <br /> If you are new to Phoenix, Elixir, Tachyons (the UI) or ngrok, <br /> we have a "beginner tutorials" which will bring you up-to-speed:

Additionally we use Amazon Web Services (AWS) Simple Storage Service (S3) <br /> for storing the issue comment history with "high availability" and reliability. <br /> To run github-backup on your localhost you will need to have an AWS account and an S3 "bucket". <br /> (instructions given below).

<!-- > Point People to the "Landing Page" (once it's ready): https://github.com/dwyl/github-backup/issues/55 -->

Set Up Checklist on localhost

This will take approximately 15 minutes to complete. <br /> (provided you already have a GitHub and AWS account)

Install Dependencies

To run the App on your localhost, you will need to have 4 dependencies installed:

Once all the necessary dependencies are installed, we can move on. (if you get stuck, please let us know!)

Clone the App from GitHub

Run the following the command to clone the app from GitHub:

git clone https://github.com/dwyl/github-backup.git && cd github-backup

Required Environment Variables

To run the project on your localhost, you will need to have the following Environment Variables defined.

Note: if you are new to "Environment Variables", <br /> please read: github.com/dwyl/learn-environment-variables

Copy The .env_sample File

The easy way manage your Environment Variables locally is to have a .env file in the root of the project.

Copy the sample one and update the variables:

cp .env_sample .env

Now update the values to the real ones for your App. <br /> You will need to register a GitHub app, so that is what we will do below!

Don't worry, your sensitive variables are safe as the .env file is "ignored" in the .gitignore file

Create a GitHub Application

The role of the Github application is to send notifications when events occur in your repositories. <br /> For example you can be notified when new issues or pull requests are opened.

Note: we have simplified the steps in the "official" Github guide to create a new Github App: https://developer.github.com/apps/building-github-apps/creating-a-github-app

1. Access the New Application Settings Page

While logged into your GitHub Account, visit: https://github.com/settings/apps/new <br /> Or navigate the following menus:

Settings -> Developer settings -> Github Apps -> New Github App

github-backup-create-new-app-numbered

<!-- numbering steps is in instructions **always** better than bullet points as it's easier to reference a **specific** step -->
  1. Github App name: The name of the app; must be unique, so can't be "gh-backup" as that's taken!
  2. Descriptions: A short description of the app; "My backup app"
  3. Homepage URL: The website of the app. e.g: "https://gitbu.io" (yours will be different)
  4. User authorization callback URL: Redirect url after user authentication e.g."http://localhost:4000/auth/github/callback". This is not needed for backup so this field can be left empty.
  5. Setup URL (optional): Redirect the user to this url after installation, not needed for github-backup.
  6. Webhook URL: the URL where HTTP POST requests from Github are sent. The endpoint in the github-backup App is /event/new, however Github won't be able to send requests to http://localhost:4000/event/new as this url is only accessible on your localhost. To allow GitHub to access your localhost server you can use ngrok. Remember to update these value after you have a running server on your machine!
  7. Webhook secret (optional) - leave this blank for now. see: github-backup/issues/76 (please let us know your thoughts on how/when we should prioritise this!)

2. Set the Necessary Permissions

Still on the same page, scroll down below the initial setup, to the Permissions section:

github-backup-permissions

Define the access rights for the application on the permission section.

  1. Change "issues" to "Read & write" (this is required to update "meta table" which links to the "issue history")

  2. Change "Pull requests" to "Read-only" (this is required to allow the app to see the current state of pull requests)

3. Subscribe to Events

Scroll down to the "Subscribe to events" section and check the boxes for Issue comment and Issues: github-backup-subscribe-to-events

4. Where can this GitHub App be installed?

Scroll down to the "Where can this GitHub App be installed?" section.

github-backup-where-can-be-installed

In our case we want to be able to use GitHub Backup for a number of projects in different organisations, so we selected Any account. but if you only want to backup your personal projects, then select Only on this account.

5. Click on the Create GitHub App Button!

Finally, with everything configured, click on "Create Github App"!

create-github-app

You should see a message confirming that your app was created: github-backup-create-private-key

(obviously your app will will have a different name in the url/path...)

6. Generate Private Key

Click on the link to "generate a private key".

github-backup-private-key

When you click the Generate private key button it should download a file containing your private key.

github-backup-pk-download

Open the file in your text editor, e.g: private-key

<small>Don't worry, this is not our "real" private key ... it's just for demonstration purposes. <br /> but this is what your RSA private key will look like, a block of random characters ...</small>

The downloaded file contains the private key. Save this file in the root of the github-backup repo on your localhost.

For example in our case the GitHub app is called "gitbu", <br /> so our Private Key file starts with the app name and the date the key was generated. <br /> e.g: gitbu.2018-03-23.private-key.pem

<small>Don't worry, all .pem (private key) files are ignored in the .gitignore file so your file will stay private.</small>

Once you have copied the file into your project root, run the following command:

echo "export PRIVATE_KEY='`cat ./gitbu.2018-03-23.private-key.pem`'" >> .env

Replace the gitbu.2018-03-23.private-key.pem part in the command with the name of your private key file e.g: my-github-backup-app.2018-04-01.private-key.pem

That will create an entry in the .env file for your PRIVATE_KEY environment variable.

7. Copy the App Name and App ID from GitHub App Settings Page

In the "Basic information" section of your app's settings page, copy the GitHub App name and paste it into your .env file after the = sign for the GITHUB_APP_NAME variable.

github-backup-app-name

Scroll down to the "About" section where you will find the ID of your app. This is the number that needs to be set for GITHUB_APP_ID in your .env file.

app-about-id e.g: 103

Generate the SECRET_KEY_BASE

Run the following command to generate a new phoenix secret key:

mix phx.gen.secret

copy-paste the output (64bit String) into your .env file after the "equals sign" on the line for SECRET_KEY_BASE:

export SECRET_KEY_BASE=YourSecretKeyBaseGeneratedUsing-mix_phx.gen.secret

S3 Bucket

In order to save the Issue Comments (which are a variable length "rich text"), we save these as .json in an S3 bucket. If you do not already have an S3 bucket where you can store issues/comments, create one now.

Once you have an S3 bucket, copy the name and paste it into your .env file against the S3_BUCKET_NAME environment variable.

You will also need to define the

"Source" the .env File

Now that you have defined all the necessary environment variables in your .env file, <br /> it's time to make them available to the App. <br />

Execute the command following command in your terminal:

source .env

Note: This method only adds the environment variables locally and temporarily <br /> so you need to start your server in the same terminal where you ran the source command.

Install Elixir (Application-specific) Dependencies

Now that you have the environment variables defined, you can install the elixir (application-specific) dependencies:

mix deps.get && cd assets && npm install && cd ..

Run the Tests! (To check it works!)

Confirm everything is working by running the tests:

mix test

Create the Database

In your terminal, run the following command:

mix ecto.create && mix ecto.migrate

Note: your PostgreSQL server will need to be running for this to work.

Run a github-backup (Phoenix Application) Server

The github-backup server will receive events from Github and then save the details or edits to an external database.

mix phx.server

Run ngrok on your localhost

In a New Window/Tab in your Terminal run the ngrok server:

ngrok http 4000

You should see something like this: ngrok-terminal-running-proxy

On the line that says "forwarding" you will see the (public) URL of your app, in this case https://38e239f0.ngrok.io (your URL's subdomain will be a different "random" set of characters)

Copy the URL for the next step. (remember to copy the https version)

Update your Webhook URL on your GitHub App

Now that your server is running you can update the webhook url in your app config.

You can read more about webhooks and ngrok at: https://developer.github.com/webhooks/configuring

On the "GitHub App settings page" Find the "Webhook URL" section: (the URL is currently http://localhost:4000 ...)

github-backup-webhook-url-before

Replace the http://localhost:4000 with your unique ngrok url e.g:

github-backup-webhook-url-after

Scroll down and click on the "Save changes" button:

NOTE: you will need to update the webhook URL each time you disconnect/connect to ngrok because a different URL is generated every time.

save-changes

View the App in your Web Browser

Open http://localhost:4000 in your web browser. You should see something like:

gitbu-homepage-localhost

Try The App!

To test your github-backup server try installing your app onto one of your repos.

1. Visit Your App's GitHub Page

Visit your App's URL on GitHub e.g: https://github.com/apps/gitbu

gitbu-homepage-install

Click on the Install button to install the App for your organisation / repository.

2. Install the App

Select the Organisation you wish to install the app for: gitbu-install-select-org

Select the repository you want to install the App for e.g:

gitbu-select-respository then click Install.

You should now see a settings page confirming that the app is installed:

gitbu-confirmed-installed

3. Create/Update or Close an Issue in the Repo

In the repo you added the App to, create/update or close an issue. e.g:

gitbu-hits-elixir-issue

Since this issue has/had already been resolved by a Pull Request from Sam, I closed it with a comment:

gitbu-issue-closed

4. Observe the Data in Phoenix App Terminal Window

When you perform any Issue action (create, comment, update or close), you will see a corresponding event in the terminal.

You should see the payload of the request in the tab you have open in your terminal for the phoenix server, e.g:

gitbu-phoenix-event-terminal-log

5. Confirm the Data in PostgreSQL Database

You can confirm that the data was saved to PostgreSQL by checking your DB. <br /> Open pgAdmin and navigate to the database table in app_dev > tables > issues

gitbu-confirm-data-in-postgresql-db

To run the query, right-click (⌘ + click) on the table (in this case issues) and then click "View/Edit Data" followed by "All Rows":

gitbu-all-rows

You can also confirm that the status of the issue has been update to "closed":

gitbu-issue_status-closed

That's it, your github-backup instance is working!

Deployment

The project is hosted on Heroku at: https://github-backup.herokuapp.com

If you want to know how see: <br /> https://github.com/dwyl/learn-heroku/blob/master/elixir-phoenix-app-deployment.md