Web Development

Web Development
Category
esembrat3

This section contains content system agnostic web design and development documentation and knowledge.


Web Development Sub-Topics

Appearances and Themes

Appearances and Themes esembrat3
Tags

This section contains generic appearance and theme-related resources for web development on campus.

Please be sure to also see the Georgia Tech Web Branding Rules for Georgia Tech's specific website standards and requirements.


Appearance and Theme Sub-Topics

HTML/CSS Templates for Creating Georgia Tech Websites

HTML/CSS Templates for Creating Georgia Tech Websites
Category
eh94
Tags

You can find a repo of a static HTML/CSS template for creating a Georgia Tech website available on the Georgia Tech GitHub page.

Access

To access the template, please see:

You must have an active Georgia Tech user account (GTAccount) in order to view this repository.

Details

The markup and styling associated with this repository is ported from the Georgia Tech Drupal theme. This template serves as a starter-kit to help one follow Georgia Tech Website Brand Requirements when building a static Georgia Tech website or website in a content-management system other than Drupal.

Contact

If you have any questions about this repository, please contact webteam@gatech.edu. For technical issues, please post an issue to the repo.

Security

Security ma195

This section has security related resources including authorization and authentication techniques, data encryption techniques, and security best practices.


Security Sub-Topics

Central Authentication Service (CAS)

Central Authentication Service (CAS) kp37
Tags

What is Central Authentication Service (CAS)?

From Wikipedia (Central Authentication Service):

The Central Authentication Service (CAS) is a single sign-on protocol for the web.[1] Its purpose is to permit a user to access multiple applications while providing their credentials (such as userid and password) only once. It also allows web applications to authenticate users without gaining access to a user's security credentials, such as a password. The name CAS also refers to a software package[1] that implements this protocol.

Georgia Tech implements the CAS service to allow campus members to easily log into campus websites using their GT Account Username and associated password.  However, for a website to utilize CAS, it must be set up correctly, which usually means adding a module, plugin, or library, and configuring it to work with Georgia Tech's CAS servers.


CAS Sub-Topics

CAS and Stand-Alone PHP Applications

CAS and Stand-Alone PHP Applications
Category
kp37
Tags

The most common approach for adding Central Authentication Service (CAS) support to a custom stand-alone PHP application is through the phpCAS Library. As of May 2021, the most recent version was phpCAS 1.4.0. Note: If you are using an earlier version you should upgrade as soon as possible to obtain the latest security patches.

The basic approach to using the library is to:

  1. Unpack it into a subdirectory of your application
  2. Require the library's main file, CAS.php
  3. Add the appropriate calls to it before your application does anything that requires the user's identity to be known

It is preferable to store the user's identity in a session cookie for later accesses, so that you are not authenticating the user against the CAS server on every single page access.

The phpCAS documentation has an example of a really simple phpCAS implementation. More information on using phpCAS can be found in the documentation library.

You will also need the campus CAS Server configuration settings.

Note: You would not utilize phpCAS in this manner if you are wanting to add CAS authentication to most content management systems (CMSs), such as Drupal or WordPress. Instead, you should look for a CAS module or plugin for your particular CMS, and use it. These modules and plugins are designed to integrate CAS into the CMS's user management system to give you proper security and a good end user experience. Not every CMS will have a CAS module, but most of the popular CMS's will. If you can't find a CAS module for the CMS you are using, you could look at it's module/plugin API and see if you can write your own module or plugin to integrate phpCAS, but this requires a fairly advanced knowledge of PHP programming, the CMS in question, and the CAS protocol or the phpCAS library.

CAS for WordPress Websites

CAS for WordPress Websites
Category
kp37

Recommended Option

If you want to utilize GT Account based authentication via CAS for a WordPress website, it is highly recommended that you try using the Sites @ Georgia Tech service, which has GT Account authentication already built in.  Once you have your site created, it is very easy to add other users to the site, who can then log in using their own GT Account Username and password.

Alternative Option

If you have an already established WordPress site on OIT Web Hosting or another on-campus hosting solution where you are able to install plugins, and you don't want to recreate your site in the Sites @ Georgia Tech service, there is a plugin that supports CAS authentication:  Authorizer.

After installing the plugin, read the instructions carefully and configure it using the campus CAS Server configuration settings.

Converting a Website to SSL (https://)

Converting a Website to SSL (https://) kp37
Tags

With changes to web browsers (Chrome in particular) coming soon that will mark non-SSL (http://) websites as Not secure, now is the time to consider upgrading your site to SSL encryption.  The first part is getting an SSL certificate and adding it to your hosting account.  However, you also have to check through and adjust your site for optimal results.

In most cases, switching to SSL will not outright break a site, but its not impossible in some cases:

  • Chrome and possibly some other browsers will not show a non-SSL page in an IFRAME of an SSL page.  Unlike other types of security issues, Chrome will not let the user bypass or ignore the issue on non-SSL page in an IFRAME, so the user will be completely blocked from getting to the IFRAMEd content.

  • Custom code might break if it dissects page URLs and doesn't treat "http://" and "https://" as the same site, or has been coded to only work with http:// URLs.

The more common issue is a page being flagged as having mixed content, which means that something included on an SSL encrypted page (an image, a video embed, a CSS file, a JavaScript file, etc.) is being loaded from a non-encrypted site.  A lot of times, this is due to a local resource having been added to the page with a fully qualified URL (e.g. http://foobar.gatech.edu/styles.css) instead of using a relative URL (e.g. /styles.css).  Updating those URLs will fix the problem, though finding them can be a challenge.  Getting comfortable with your favorite browser's development inspector can help a lot, as many have a Network feature to let you see all of the files being loaded by the page and which ones were SSL encrypted and which ones were not.

There are other places you should check to optimize your site:

  • Menu bars often have fully qualified links added to them, so check for ones that can either be shortened to a relative link or updated from "http://" to "https://"

  • Redirects in .htaccess files are sometimes entered as fully qualified links.  Once again, they should be made relative or updated from "http://" to "https://".  If your content management system has its own redirection system (e.g. the Drupal 7/8 Redirect module), you may need to check its tables for URLs that need to be updated in the same way.

Certain applications may need a little assistance:

  • WordPress has two settings on the General settings page:  WordPress Address (URL) and Site Address (URL).  Both need to be updated to begin with "https://"

In most cases, you'll not only want to clean up the links and settings of your site, but also redirect all of your non-SSL traffic to your SSL site, and content systems don't typically handle this for you.  To cover all of your bases, it's good to add the following to your site's .htaccess file, ahead of any other Rewrite Engine rules:

RewriteEngine on
# This forces the visitor to the non-www.* address *before* forcing them to SSL
RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule ^ https://%1%{REQUEST_URI} [L,R=301]
# This checks to make sure the connection is not already HTTPS
RewriteCond %{HTTPS} !=on
# This rule will redirect users from their original location, to the same location but using HTTPS.
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

One final tip: if you control any other websites that link to the site you're upgrading, you should go into them and update those links from "http://" to "https://", and also make sure they're using the version of your site's domain name that matches your SSL certificate (in most cases, this will be a version without "www." at the beginning.)

SSL Encryption

SSL Encryption
Category
ma195
Tags

SSL encryption (technically Transport Layer Security, but still commonly referenced as SSL, the acronym for its now deprecated predecessor) is a protocol for encrypting communications between a web browser and a web server. Encrypted connections (denoted by a web URL starting with 'https://') are not easily monitored by third parties unlike unencrypted connections (denoted by a web URL starting with 'http://'), where all content can be easily viewed by anyone with access to some part of the connection path. SSL works through a system of public-key cryptography, and is intended to not only keep communications private, but to also help ensure that you are actually communicating with the right server and not a hacker's rogue server that is merely impersonating a legitimate server.

By default, SSL is provided and available on OIT Webhosting, and can be enabled other types of on-campus web hosting where you or your information technology support staff have low-level management access to the web server.

SSL Certificates

In order to enable SSL encryption for a website, you need to have an SSL certificate that securely identifies that your server is the genuine server for your website's domain name. There are many possibilities for obtaining an SSL certificate – too many to list here.

Presently, Georgia Tech is a member of InCommon, a collective of universities which have pooled resources. This means campus units can get SSL certificates for free. Usually one person in a department, college and/or school has the ability to request and issue certificates. Ask your information technology support staff for assistance if you need a certificate for a web site.

InCommon Certificate Caveats

  • Georgia Tech's InCommon account can issue certificates for sub domains of Georgia Tech (addresses that end in .gatech.edu) as well as non-Georgia Tech domains. If you need a certificate for a non-Georgia Tech domain, you will need to contact the InCommon admins who will assist with granting authority to sign the non-Georgia Tech domain, and provide instructions on verifying the ownership of the non-Georgia Tech domain. This is usually accomplished by uploading a unique key file to your site's docroot for verification.
  • If your site is on OIT Web Hosting, you may not need a certificate, as web hosting has a 'wildcard' / multi-site certificate that covers a lot of common Georgia Tech sub domains, and they are often willing to add additional Georgia Tech sub domains if you ask. Please see the OIT FAQ Article on SSL Certificates and Web Hosting for more information.
  • As of now OIT Web Hosting only allows creation of 2048 bit certificates. Most security standards now call for a minimum of 4096 bit SSL certificates.

Other Types of SSL Certificates

Before InCommon, there were several options for SSL certificates. You may stumble across them:

  • Paid SSL certificates - Issued by GoDaddy, Thawte, Comodo and others.
  • Self signed certificates - Generated and signed on the server that hosts them.  These are fine for development, but should never be used in production, as users will get a certificate error message in their browser when accessing a site with a self-signed certificate.
  • Georgia Tech Signed certificates - For many years, Georgia Tech had its own root certificate.  It's no longer used, but may still be on systems.  If you find this, you should remove it, as the root certificate has expired, as have any certificates signed by that root certificate.

Implementing SSL Encryption

Security Best Practices

Security Best Practices kp37
Tags

Patch, Patch, Patch

The most important security practice for web application software is to keep up with your software patches.  The more commonly used the application, the greater a chance that someone out there is looking for insecure installations to hack.

Systems like Drupal and WordPress are so popular that you need to be prepared to deploy security patches for them just as soon as they come out.  If your hosting server is running Installatron, you can configure it to automatically install many of these updates.  If you don't have Installatron, you can still configure WordPress to automatically install new updates on its own.  Drupal, unfortunately, requires manual intervention if you don't have an outside tool like Installatron, but modules can usually be updated from within the application.  Drupal core updates have to be installed from the command line or from a web hosting file manager control panel.

Non-security patches can be important, too, but should be tested more thoroughly before deployment since they could break things.  (Security patches could break things, too, but sometimes it may be better to break a small feature of your site temporarily than to leave it susceptible to a known vulnerability.)

Lock Down Site Access

Securing the back doors to your site is pointless if you leave the front door wide open.  Make sure you have configured your web application properly so that only the proper authorized people can access it.  

  • Consider user roles carefully and don't give out more access privileges than are necessary.
  • Audit user access lists and remove users who no longer need access (employees who no longer work for your unit, students who have graduated, anyone who has moved to a different role that doesn't need to use the application.)
  • Besides auditing access lists within web applications, also audit the access lists for their server hosting accounts as well.  Make sure that the people with access to administer those accounts still have reason to be doing so.  Take old developers off of these accounts if they aren't actively working for you, even if you think you'll bring them back in later, and remove anyone who has left Georgia Tech, as they could potentially still be able to get to your hosting account even after many of their standard IT privileges have expired.
  • If you implement a configuration where anyone with a GT Account can log into your application, be very careful about what you make available to these 'regular' users.  Keep in mind that when you include all GT Accounts, you include all guest users, outside vendors and developers who are doing work for Georgia Tech units, retirees, alumni, etc.  That's a pretty big pool of people.  If you really don't need to include all of those people, look into options for validating that someone logging in is a current faculty/staff member or student.
  • If you add custom security modules to content systems like Drupal and WordPress, don't just assume they work as you have configured them:  open a different browser and test to make sure a non-logged in user really can't get to the content you are trying to protect.  A security configuration that doesn't actually work is worthless.

Run a Tight Ship

Module and plugin based applications like Drupal and WordPress have one distinct downside:  not all modules and plugins are created equal, and poorly written and managed ones can put your application at risk.

Before installing a module or plugin, review it carefully.  Avoid ones that do not have active support, ones that haven't been updated in several years, and ones that have never left alpha/beta status.  It's usually better to tell a stakeholder that there's nothing available to provide a certain functionality than to offer up a module or plugin that isn't stable and risks introducing security holes.  It's also far better to say no up front than to try something that stakeholders get used to, only to later discover a serious uncorrectable problem that necessitates removing the plugin/module.

Avoid Frankensites

What's a Frankensite?  It's a module/plugin based web application where so many extra components have been added to it that it's impossible to properly audit the functionality of the site.  Upgrading these sites can either become impossible, or strokes of pure luck if a major update doesn't break several things at once.

When any kind of complex functionality is required, look at abstracting that functionality out to a separate application that can run in parallel with the main application.  For example, if you are running a Drupal site and your stakeholders want a nice photo album, don't load up the Drupal site with the half-dozen extra modules needed to make a barely functional internal photo album system.  Instead, set up a copy of ZenPhoto, which is designed from the ground up to handle photo albums.  Or, suggest the usage of an hosted in-the-cloud system.  Any of these options will keep your main website application from turning into an unmanageable Frankensite.

(Setting up multiple applications may seem like more work at first glance, but it's far less work in the long run, as you'll be able to streamline the installation of updates, not to mention that you can update the secondary applications one at a time without having to bring down any others or the main application/site.)

Enable and Monitor Security Logs

Many applications and all hosting account systems will log different kinds of activity related to your web application.  While a lot of these logs may seem unreadable to the untrained person, they could still be invaluable should a problem arise - especially a security incident.  It's a good idea to keep these logs around for at least six months, and even longer if your application handles any sensitive data.  Check the Georgia Tech data security policy to find institute requirements and recommendations for log retention.

When possible, sending logs to a remote server is a really good idea, as that prevents those remote copies from being modified by a hacker who gets too far into your web server.

Make Regular Site Backups

Nothing is worse than having a site crash without a recent backup available.  Whether the crash was due to a patch gone bad or a hacker getting into the site, being able to restore the site to a previously known good state is critical.  Here are some recommended guidelines for handling backups:

  • For all sites, run a full backup once a week, and for important sites, also run an incremental backup daily.
  • Store backups in a safe location, ideally on a remote server.  If possible, configure your infrastructure so that the web server can't modify a backup once it's been written to the remote server, so that a hacker who breaks into the web server can't delete your backups.
  • TEST your backups!  Far too many a systems administrator has been bitten hard by backup files that were corrupted, missing important components, or even just plain missing because the backup process didn't write out the files as expected.  After running your first backup, download the files and try to recreate the website in a test environment to make sure you have a complete backup of the site.  And, don't forget to check the backup archives periodically to make sure they're still functioning as you expect.
  • Be sure to cycle out old backup files periodically, so that your backup system doesn't run out of disk space.  This is yet another way to discover that you have no recent backups when you need them the most.

Install and Utilize Security Tools

Some applications may have third-party tools to help you monitor for security problems.  A good, reliable security tool can block many types of known attacks, stop brute-force login attempts, log more details about accesses to the site, and/or point out configuration settings that you ought to change to make the site more secure.

Since every application is unique, you'll have to research the available security tools that work with a specific applications.  Be sure to look at how well respected the tool is within the user community, as that will give you an idea of how safe and reliable it will be.

There are also server level security tools that you can utilize, such as Web Application Firewalls (WAFs).  These have to be installed by a server administrator, but can add an extra layer of protection beyond the tools available for the specific application(s) you are running.  The OIT Web Hosting servers all run a WAF that protects their hosting accounts by filtering any requests coming from off-campus.

Write Safe Code

If you are coding applications for the web or even just coding modules / plugins / themes for existing applications, take the time to write safe code:

  • Sanitize any user input that you utilize to deter hackers from running malicious commands by submitting carefully crafted values into a form field.
  • Use proper security wrapping methods to make sure that authorization is being checked properly before the execution of any higher level command.
  • Avoid putting in a backdoor "just for testing", as it can be all too easy to forget to remove it later.  If you must use one, document it boldly and clearly so that it's easy to detect when you review the code later.
  • Do carefully review your code before putting it into production, and even better, have someone else review it as well, since they might catch bugs that aren't obvious to you.
  • Always keep a copy of your code on a separate server, so that if your development or production servers get hacked, you can run a code comparison to your protected code to see if anything was changed by the hackers.

Clean Up After Yourself

Leaving junk behind in your public web hosting account directories can cause multiple problems, so keep your public directories clean:

  • When installing code updates, keep the installers out of your public directories, or at least move them out once you are finished with the update.  If your hosting account doesn't already have a private directory, create one and use it for installers, backups, etc.
  • If you edit live code, don't leave any backup copies in the live directories.  If you need to make a backup of a file before editing it, put the copy in a private directory.  There are many ways in which an improperly named backup file could accidentally expose the program code to a hacker, and depending on the file, this could expose internal user account credentials, shared secrets, or internal server names, all of which could be quite valuable to a hacker.
  • If you run a major update and want to move your current installation to a different folder, once again move it somewhere inside a private (non-public) directory, especially if there is no need to be able to access the old installation over the web.  If you do need to leave the old installation up temporarily, plan a date at which it will be shut down, and if at all possible, firewall that directory for the interim to just on-campus IP addresses (or if possible, just IP addresses for your local unit).  Old installations usually never get patched, and thus can become huge forgotten security holes if left publicly accessible over the web.
  • Security precautions aside, keeping your public web directories neatly cleaned up will help you in many other ways, including making it easier to debug problems and in some cases even speeding up application performance.

Suppliers and Contracts

Suppliers and Contracts esembrat3

This section covers all aspects of having websites created or managed by someone outside of your Georgia Tech unit, such as hiring a consultant from another part of campus, or using an outside web development company.


Suppliers and Contracts Sub-Topics

Georgia Tech Web Contract

Georgia Tech Web Contract
Category
esembrat3

For those considering hiring a third party for their website work, Georgia Tech has an enterprise-wide contract in place that allows you to quickly get estimates from a group of pre-approved vendors. 

In March 2020, the Institute finalized two enterprise-wide contracts for web projects:

  • One for projects less than $50K.
  • One for projects greater than $50K.

These contracts include a number of fully vetted vendors with a broad range of skillsets in owned digital. Every Georgia Tech unit seeking third-party website support must use a vendor from one of the enterprise-wide web contracts.

For more information, refer to: How to Hire a Website Vendor.

A Layman's Guide to Working With a Website Developer

A Layman's Guide to Working With a Website Developer
Category
kp37

Once you have selected a developer or development company to rebuild your unit's website, you'll need to give them access to your existing website and in many cases a development workspace.  The information below will help guide you through this process.  Note: if you are using a student developer or hiring a tech temp, then you can skip the parts about setting up a GT Account Username, as these individuals will have their own GT Account username.  Simply have them tell you what their GT Account username is and follow the instructions for adding it to the appropriate web hosting services and accounts.

Development Space

Your selected development company is going to need access to your existing website as well as to a space in which to develop your new website.

While some developers may prefer to do most of their work in their own development environment, we highly recommend having them test their work in a Georgia Tech web hosting space that is as similar to your existing hosting space as possible.  This will avoid unnecessary downtime when it comes time to put the new website into place.

If your website is on OIT Web Hosting, then we recommend that you put in a request to OIT to create a second Web Hosting account on the same server, configured the same way.  You can then have your developer load their work into that second account and test it there to make sure it will work on OIT's systems.  Once they have confirmed that everything is working, you can then tackle the final steps for replacing the old site with the new one.

If your website is on Sites @ Georgia Tech, you can and should request an new site in which to allow the development company to do their building work.  Unlike with other content management systems, with Sites @ Georgia Tech the developers will have to do their development directly on Sites @ Georgia Tech, as it is not practical to try to build the site somewhere else and then copy it to Sites @ Georgia Tech.  Once the new site is ready to launch, you can work with OIT to repoint your current website domain name to the new site.

Access to the Current and New Web Hosting Spaces

If your current website is on any web hosting service managed by OIT, then at a minimum, your development company will need a guest GT Account Username to access the OIT Web Hosting control panels for your hosting accounts (the current account and the account for testing the new website). You can use PASSPORT to create this guest user account, which could be shared among individual developers working on your project. If you have questions about creating this account, please see your local IT support staff.

OIT Web Hosting

If your current website is on OIT Web Hosting then there are several factors to consider in providing access to your developer.

Once you have set up a GT Account Username for your development company, you will need to give it access to your sites Plesk Control Panels.  Instructions are available for adding new administrators - please be sure to only add your developer's account as an 'administrator' and not as an 'owner'.  Be sure to give the account access to both the original hosting site and the new site that you create for testing purposes.

The developers may wish to use a service called SSH to upload their files to either OIT Web Hosting account.  If anyone in your unit is using this service with your current website, then you will need to coordinate with that person, as there is a single SSH password for the account.  It is possible to use a token called an SSH key in lieu of the password.   If your developer asks you to add their SSH key to one or both hosting accounts, you can refer to our instructions for managing SSH Key access to your hosting account.

If your existing website is in a content management system (Drupal, WordPress, etc.) then you'll want to give the developers access to the content system itself.  This is a separate process from giving access to the web hosting account.

  • For Drupal, log into the site as a user with administrator privileges, then navigate to People -> Add CAS User on the black administrative toolbar.
  • For Wordpress, Instructions are available for adding users to WordPress sites.
  • For other content systems, please consult the documentation for that particular system.

Finally, to access Plesk Control Panels or to access a hosting account via SSH, the developers will need VPN access.  This comes automatically with any GT Account Username, but you should direct the developers to OIT's VPN instructions for using the campus VPN and installing the appropriate VPN client.

Sites @ Georgia Tech WordPress Hosting

If your current site is on Sites @ Georgia Tech and your updated site is going to remain on Sites @ Georgia Tech, then setting up your development company is a little easier.

Once you have set up a GT Account Username for your development company, you will need to give it access to your WordPress site.  Log into Sites @ Georgia Tech, navigate into the administrative interface for the site in question, and go to the Users option.  From there, add the GT Account Username that you created and make it an Administrator.

That's it!  Accessing Sites @ Georgia Tech does not require any further configuration, and does not require use of the VPN either.

Cleaning Up After Development is Complete

Once your contract with your development company is complete and all deliverables are delivered, you need to make sure their access to your websites is turned off.   A few key places to check and review:

  1. Review the SSH Keys for the hosting account and delete any that belong to your developers.

  2. Log into your website and check the website content management system user list.  Delete or disable any accounts associated with your development company.

  3. Log into PASSPORT and disable the developer's Guest User Account.  (Note: the person who created the guest user account must do this.  If that person is no longer available, contact your local IT support for assistance.

On-Campus Contract Work

On-Campus Contract Work
Category
esembrat3

On-campus web developers can, in some cases, serve as contractors for on-campus web work

Important Notes

  • Please note that is strongly advised that you receive direct agreement from your supervisor and the hiring unit's leadership before beginning work. 
  • To simplify the process, the best practice is to complete this work outside of the employee's regular working hours. 

Employee Policy

5.3.2 Extra Compensation:

Extra compensation may be paid to employees for tasks performed after normal business hours for duties not included in the employee’s normal job responsibilities, provided the following three criteria are met:

  1. The tasks must be outside of the employee’s regular department.

  2. The Departmental Agreement Form, must be completed and signed by the appropriate department heads. Departmental Agreement Form

  3. The employee must meet at least one of the criteria listed below (Criteria from the Official Code of Georgia Annotated Section 45-10-25):

    • Chaplain
    • Fireman
    • Dentist
    • Certified Oral or Manual Interpreter for Deaf Persons
    • Registered Nurse
    • Licensed Practical Nurse
    • Psychologist
    • Teacher or Instructor of an evening or night course or program
    • Professional holding a doctoral or masters degree from an accredited college or university
    • Part-time employee

Also, an employee meeting all three criteria listed above may be paid extra compensation for a task for another department during normal job hours if the task is not part of the employee’s normal job responsibilities, and the employee takes annual leave for the portion of time that is being used for the task receiving extra compensation.

Employees that have been determined by the institution to be non-exempt, as defined by the Fair Labor Standards Act (FLSA), and are performing extra duties could qualify for overtime pay. Non-exempt employees should be paid at least the overtime rate or more.

Examples of situations justifying the payment of extra compensation are:

  • An employee teaching a continuing education course after hours or while taking annual leave, when teaching the course is not part of the employee’s normal job responsibilities.

    Note: This is allowable under the Official Code of Georgia Annotated Section 45-10-25, No. 15.

  • A part-time public safety officer working extra hours to referee a ball game.

    Note: Georgia Code 45-10-25 does not apply to part time employees.

  • A staff member with a masters degree doing web design for another department.

    Note: This is allowable if the required Departmental Agreement Form is completed and signed by the appropriate department heads.

GitHub Enterprise and Repository Management

GitHub Enterprise and Repository Management
Category
esembrat3

Git is a distributed version-control system for tracking changes in source code during software development. {Definition and links courtesy of Wikipedia}

Georgia Tech OIT supports a centrally managed server running the GitHub Enterprise software, which provides a web-based interface to the underlying Git application.  Georgia Tech community members can create and maintain code repositories on the Georgia Tech GitHub server and easily share access with other members of the Georgia Tech community.  (Note: you cannot share access with anyone who does not have a Georgia Tech user account).

This page contains information about the Georgia Tech campus GitHub Enterprise installation.

A Georgia Tech gitflow Process

A Georgia Tech gitflow Process
Category
afrank30

A proposed workflow for how smaller teams can code collaboratively with git at Georgia Tech.

Defining Git

Git is an environment-agnostic version control system that allows teams or individuals to collaborate on projects in a distributed fashion. Git was created for the command line, but there are also GUI clients available.

Commits

Under the hood, git is powered by a tree of commits. Each commit tracks the difference between it and the previous commit in the tree. This saves tremendous space by storing only the changes and not the entire changed file.

Repositories

Repositories (repos) are a place where files and their histories are stored. Local repos are stored on your machine and/or the production server. The remote (origin) repo is an agreed-upon authoritative repository through which all changes flow. We use the GitHub.gatech.edu enterprise website to store our remote repos, as well as to manage their permissions and the code review process.

Branches

Central to git is the idea of branches. Each branch is just a pointer to a commit in a tree. So making a new branch is as cheap as initializing a pointer to the current commit, and updating that pointer (and only that pointer) when work is done on that branch. And because of the way git stores commits, storage for the work done on branches will be cheap too.

Branches are a way for collaborators to work together without all working on the same version of code. This allows for more advanced nonlinear workflow than a single stream of commits. It also allows for powerful administrative features such as code reviews, keeping the master (production) branch stable and testing new features without compromising that stability.

Pull requests

Pull requests are a GitHub-specific feature that encourages review of any code changes before they go live. It also gives administrators a chance to request changes or resolve conflicts before the final code is merged into the master branch.

Collaborative Workflow Overview

This workflow is based on the lightweight GitHub Flow system. This choice reflects our emphasis on less complexity for our small team, instead of focusing on a perfectly clean commit history.

In this system, all development (whether fixes or features) is done in branches and then merged back into the master/production branch when completed. Below is a sample timeline for the workflow of creating and implementing a new feature branch.

 

Visual diagram of 5-step Georgia Tech gitflow workflow

This workflow follows 5 rules:

  1. The master branch is protected and should be kept deployable to production at all times. This is the most important rule. All code merged into master should first be thoroughly tested and reviewed. It is possible to revert the master branch, but this should be avoided whenever possible. Even if a hotfix is needed, verification of the fix should always be done in a branch. This is especially essential when our server is configured to automatically pull updates from the remote origin repo, meaning that any commit to master will quickly be made live.

  2. Create separate branches off the latest master for each feature. Since branches are cheap, use one for every feature or fix. And, to ensure updated code, branch off of the current master.

  3. Before every commit, pull the latest master and merge it into your local branch. One of the most challenging tasks in collaborative git is updating an existing file that needs to integrate divergent code changes from multiple developers. Merging the latest master branch into your local feature branch before every commit will largely prevent that by ensuring that any discrepancies in code are limited in scope and easily resolvable.

  4. Constantly push all branches to the remote/origin repo. The remote repo isn’t just for maintaining the master branch: it can also store any other branches you are developing. This allows others to contribute to the individual branch you are working on (if you both are working on the same feature, for instance), as well as showing the current progress on each feature.

  5. Use pull requests to add completed features to the master branch. Pull requests allow new features to be vetted by administrators before being added to production. Once a feature is in a mergeable state, a pull request allows discussion, review, and finally approval to get integrated into our live, master branch.

(Credit to Eli Trexler for putting together a lot of this content).

Connect Your Website to a GitHub Repo with SSH Keys

Connect Your Website to a GitHub Repo with SSH Keys
Category
afrank30

Learn how to connect a repository on github.gatech.edu to a virtual host on a server (examples given for a RHEL7 server, but similar will work IF using at least OpenSSH version 5 or higher on your server).

Make SSH Keys on Server

  1. On your server, become the superuser (sudo su).
  2. Create a folder in which to store SSH keys (mkdir /var/www/.ssh).
  3. Create an SSH key pair on your server in that .ssh directory (ssh-keygen -b 2048 -t rsa), and name the key for the virtual host (example: /var/www/.ssh/mysite).
  4. Create a config file (touch /var/www/.ssh/config) and add this code inside it:
    # mysite.gt
    Host mysite
    HostName github.gatech.edu
    PreferredAuthentications publickey
    IdentityFile /var/www/.ssh/mysite
  5. Change the .ssh folder permissions (chmod 700 /var/www/.ssh).
  6. Change the .ssh folder ownership for use by apache (chown -R apache:apache /var/www/.ssh).
  7. Change ownership of the already-existing vhost's folder for use by apache (chown -R apache:apache /var/www/vhosts/mysite.gatech.edu).
  8. Copy the contents of the public key into your Text Editor of choice (cat /var/www/.ssh/mysite.pub).

Add Deploy Key on Github

  1. Create your private repo on github.gatech.edu, under the appropriate departmental Team. Do not add any files (not even a README).
  2. Within your repo, click the Settings tab.
  3. Choose "Deploy keys" in the left side menu, and click on "Add deploy key"
  4. Give a descriptive title, like "Mysite server public key".
  5. Paste the public key you copied from your server into the "Key" area.
    • If this is your initial copying of the repo from the server TO github, check "Allow write access", so that you can push to this github repo from your server.
    • If you already have the initial copy of your files pulled from the server, you need to delete the old key and make a new one that does NOT allow write access (to improve the security setup).
  6. Click "Add key".

Connect your Server to Github

  1. Make sure git is running (git --version).
  2. Become the apache user (su -s /bin/bash - apache).
  3. You probably need to symlink the .ssh directory for the apache user, so that known_hosts is saved in the correct place.
    • As the apache user, change to the home directory (cd ~)
    • Find where that home directory is located (pwd)
    • Make a symlink from your recently-created .ssh folder to apache's home directory location (ln -s /var/www/.ssh /path/to/apache/home/.ssh).

Existing Server Repository

If this vhost on your server already has a git repo initialized, follow these steps:

  1. Change to your vhost's folder (cd /var/www/vhosts/mysite.cc.gatech.edu).
  2. Use ssh not http to add the github repo as its origin, including the "Host" you created in the .ssh/config file as the url so that the server uses the correct ssh key to connect (git remote add origin git@mysite:My-Dept/mysite.git).
  3. Push your server's repo to github (git push -u origin master).
  4. Check the repo on github to make sure you see the commits from your server.

New Server Repository

If this vhost on your server does not yet have a git repo initialized, follow these steps:

  1. Change to the directory above your vhost (cd /var/www/vhosts).
  2. Use ssh not http to copy the repo from github to your server, including the "Host" you created in the .ssh/config file as the url so that the server uses the correct ssh key to connect (git clone git@mysite:My-Dept/mysite.git mysite.gatech.edu).
  3. Change to your vhost's folder (cd /var/www/vhosts/mysite.gatech.edu).
  4. Check the repo on your server to make sure you see the commits from github (git log -n 1).

Configure protected master branch on Github (Under construction section)

Since you will be connecting the repo to a Production site, you need to protect the master branch on github, so that all changes pushed to it must go through an approval process before being merged into the master/production branch.

Customize .gitignore file

For a Drupal 7 site, add these lines to the repo's .gitignore file (as they should not be version controlled):

  • sites/*/files
  • sites/*/private
  • sites/*/settings.php

Set cron to do a git pull as the apache user (Under construction section)

Example:
0 */1 * * * cd /var/www/vhosts/mysite.gatech.edu && git pull >> /dev/null

Change File Permissions (Under construction section)

Often, the file and directory permissions on the server differ from your local development environment. You will need a cron job or automatic git-accompanying command so that, whenever it pulls updates from the remote repository, files and directories receive the correct ownership and permissions for the server.

For a Drupal 7 site, the defaults should be:

  • user and group = apache:apache
  • most directories = 755
  • most files = 644
  • not version controlled, so set it once and forget it:
    • settings.php file = 444
    • /sites/*/files = 777 (directory)
    • /sites/*/files/* = 666 (files)

Connecting to GitHub Enterprise (command-line)

Connecting to GitHub Enterprise (command-line)
Category
esembrat3

Connecting to GitHub Enterprise at Georgia Tech, unlike Github.com, requires a few additional steps because GitHub Enterprise is not publicly accessible.

Please note that it is much easier to connect to GitHub Enterprise via GitHub Desktop, which natively supports enterprise installs like GitHub Enterprise at Georgia Tech.

To facilitate access to a repository in GitHub Enterprise at Georgia Tech, follow the directions below.

Setup

Derived from metroplus documentation.

  1. Generate a SSH key:
    ssh-keygen -f ~/.ssh/filename-goes-here -b 4096
    
  2. Copy SSH key files onto your server of choice into ~/.ssh/, making sure that your private key is chmod to 0400.
  3. Add the SSH key to your GitHub Enterprise at Georgia Tech account.
  4. Establish SSH fingerprint for GitHub Enterprise at Georgia Tech:

     ssh-keyscan github.gatech.edu >> ~/.ssh/known_hosts
     
  5. Edit (or create) file config in ~/.ssh/. This file is responsible for routing the generic git@github.gatech.edu account to the defined SSH key on the server and on Github. See below for an example config file.

Sample config file

host github.gatech.edu-identifying-text-here
 Host github.gatech.edu
 IdentityFile ~/.ssh/filename-goes-here
 User git

The above configuration routes git repository URLs for Host (github.gatech.edu) to check for the SSH key file under IdentityFile with the git account (User). 

More Information

Site Development / Management Server Options

Site Development / Management Server Options kp37

Whether you are building sites from scratch or helping to maintain a production site, you are going to need some place to do your development work and test updates that need to be rolled out to your sites.  You may even want to implement a pipeline process where you have development, test, and production versions of your sites.

What follows is a brief discussion of development server options

Local Development Site on a Desktop or Notebook

Several options exist for doing development on a regular computer (i.e. a workstation) that you use for general purposes.  With Macintosh computers, you are already running a Unix style operating system with all of the components needed to do web services - they just aren't enabled by default.  Linux based workstations are exactly the same.  With any kind of standard computer (Windows, Macintosh, or Linux), there are also add-on applications that will let you create a Unix style environment for doing web site development and management.  Some examples are:

  • MAMP (Windows or Macintosh; free and commercial versions)
  • Lando (Most major Operating Systems; free open-source)

Some upsides to a local development site are:

  • Available on that computer regardless of network availability
  • Full access to configure the instance as you wish (assuming you have admin rights to your computer)
  • Local operations will run as quickly as your computer can support

Some downsides to a local development site are:

  • To do development work, you have to have access to the particular computer that the site is on
  • Transferring large sites to and from the production server may be slow
  • Other developers cannot access your development site, since it's local to you

Development LAMP Virtual Machine on the Campus Network

As an alternative to a local development site on one of your workstation computers, your IT unit can help you get a LAMP (Linux, Apache, MySQL, PHP) virtual machine set up on the campus network that you can use for development.  One LAMP server can host multiple development sites, so you probably only need a single development server regardless of how many sites you manage or expect to build.

Some upsides to a LAMP development server on the campus network are:

  • Available from any workstation computer (desktop or notebook) you might be using
  • Transferring large sites to and from the production server should be fast, as you won't be going outside the campus network
  • Local operations will run as quickly as your virtual machine can support
  • Other developers can access your development site, since it's on a shared server

Some downsides to a LAMP development server on the campus network are:

  • To do development work, you have to have working network access
  • Depending on your IT staff policies, you may not have full access to the virtual machine to configure everything yourself

If you're concerned about security, keep in mind that a LAMP virtual machine can be firewalled at the network level to just the campus and the VPN (or even tighter, if needed).  You can also have your IT staff set up regular backups of your virtual machine so that the risk of losing anything is minimal - far less than if you are developing on a notebook computer.

Tips for Using a LAMP Development Virtual Machine

DNS Domains and Hostnames

Through Apache Virtual Host configurations, you can host as many sites as necessary on one LAMP server.  To manage this, it's helpful to have a dedicated web development sub-domain assigned to your server.  If you have DNS management access, then you could request such a domain and manage it yourself, adding CNAMEs to it as needed.  If you're not familiar with the intricacies of DNS and don't want to get into it, you can ask your IT staff about assigning a wildcard domain to your server.  What this means in layman's terms is that you'd have a domain like foo.unit.gatech.edu, and all possible names under it (e.g site1.foo.unit.gatech.edu, site2.foo.unit.gatech.edu, test1.foo.unit.gatech.edu, etc.) will be pointed to your development server.  With that configuration in place, you can just add a site to your Apache Virtual Host configuration with a hostname that falls under your assigned wildcard domain, and it should just work immediately.

Scripting is Your Friend

If you're expecting to work with a lot of sites over time, a site creation script can be very helpful.  Such a script would automatically add the right Apache configuration for your new site, and could even automatically create a MySQL database for the site.  If you're working with a standard content management system, the script could even install a fresh copy of that system.  The overhead needed for creating such a script that can do all of that might seem a bit high, but can really pay off when you need to spin up a site quickly.

Tracking is Important

If you're going to have multiple sites in your development environment, you absolutely must keep track of them and shut down or archive the ones you no longer need.  Even though your server may be firewalled, you still don't want to leave unattended sites on your server that aren't being patched regularly.

A simple approach is to make an archive directory in /var/www/ and move any site no longer needed to that directory.  At the same time, backup and remove the Apache configuration for the site so that Apache won't complain about the site's root directory not being where it used to be.  Later, if you decide to revive an old development site, you can just move things back where they used to be, and in the meantime, no one can get to that old site over the web.  Note: if you do revive an old development site built in any standard content management system or other third-party web application, be prepared to upgrade or patch it immediately to the latest release of that system!