Managing GitHub Deployment for Perch Runway Projects.md

Managing GitHub Deployment for Perch Runway Projects

The following is how Transition manages the GitHub Deployment process. We are assuming a private ssh key linking the Git Repository to the hosting server has been created, and SSH access to the server is setup.

This process results in previous versions of the site remaining on the server in case a rollback is required. Resources not included in the version control process are stored in a folder called non-syncing-resources, and symbolic links (otherwise known as symlink) are used to connect the resources.

New Deployment

1. Log in to the server over SSH

2. Create a new directory called git by running mkdir git and then cd into that directory

    $ mkdir git && cd git
   

3. Git clone the repository into our newly created git folder

    $ git clone git@github.com:url_to_git_repository
   

4. CD back to root

5. The contents of the development build folder now needs copying into our newly created directory

    $ cp -r ~/git/repository_name/build/* ~/v0.0.1
    
    ### Note: Our deployment files are within the folder called `build`, hence we only need the contents of this folder copying into our newly created v0.0.2 folder.
   

6. Create the non-syncing-resources directory

    $ mkdir ~/non-syncing-resources
   

7. CD into the directory and create the non-changing files and folders. For Perch Runway projects, these would be the .htaccess file and the resources folder. On new projects, these are created on the local build machine and then using FTP, move the files and folders into place.

8. Now these are in place, symlinks are created to link our files.

   a. cd into v0.0.1 and run ln -s ~/non-syncing-resources/.htaccess .htaccess

   b. cd into v0.0.1/perch and run ln -s ~/non-syncing-resources/resources resources

9. Change the public web root folder into a new directory reflecting the GitHub tagged release version number. In our exmaple, v0.0.1 is being used.

    $ mv public_html v0.0.1
   

10. Finally a symbolic link can be created to replaced the currently missing public_html web root folder

    $ ln -s v0.0.1 public_html
    
    ### Note: Always link from the real file to the alias.
    

11. Test, Test, Test… I mean it, run some tests.

Future Releases

Now the hard work has been done, future releases require much less work. Again, v0.0.2 is just an example of a folder tag name.

1. CD into the git repository folder

    $ cd git/repository_name/   
    $ git pull
    $ git log -1
    
    ### Note: The third step is to test whether the pull was sucessful.
   

2. Create a new directory reflecting the GitHub tagged release version number

    $ cd
    $ mkdir v0.0.2
   

3. Move back to the root

    $ cd
   

4. Now copy the files from the git repository into the new folder

    $ cp -r ~/git/repository_name/build/* ~/v0.0.2
    
    ### Note: Our deployment files are within the folder called `build`, hence we only need the contents of this folder copying into our newly created v0.0.2 folder.
   

5. Everything is now in place and we just need to create new symlinks which replace the old symlinks.

   a. Move into the new directory and link the symlinks.

    $ cd ~/v0.0.2 
    $ ln -s ~/non-syncing-resources/.htaccess .htaccess 
    $ cd ~/v0.0.2/perch 
    $ ln -s ~/non-syncing-resources/resources resources
   

   b. The last step can be done with one command which deletes the old old symbolic and creates a new one.

    $ ln -sfn v0.0.2 public_html
    
    ### Note: `-n` is only to be used when the symlink is for a folder instead of a single file.
   

   c. Now move into the old dictory and remove the old symlinks

    $ cd ~/v0.0.1
    $ unlink .htaccess 
    $ cd ~/v0.0.1/perch 
    $ unlink resources
    
    ### Note: I used to unlink the old symlinks first and then relink the new. I found this to be better as the site is down for less time.
   

6. Test, Test, Test… I mean it, run some tests.

7. Kualo hosting appears to have server caching issues upon releasing new versions. This only appears to happen on sites that are using the symlink method. The below additional steps should be run to clear both OpCache and RealPath cache.

    $ php cachetool.phar opcache:reset --web --web-path=/home/PATHTO/public_html --web-url=https://www.site.com
    $ php cachetool.phar stat:clear --web --web-path=/home/PATHTO/public_html --web-url=https://www.site.com
    
    ### Note: PATHTO and website URL need to changed, the below is example code.
   

Testing:

Check symlink to see where they link to.

$ ls -l <link-name>
$ file <link-name>

Help

$ ln --help

Resources

ln, link

Copy files

Todo

Create shell scripts to automate parts of the process, ideally all.