This Special Guest article describes how to deploy (and work with) Grav utilizing Microsoft Azure for hosting and Bitbucket, acting as a source control repository.

The key benefits of this setup are:

1. Publish additions and changes to the site with a single command.
2. No need to keep track of the changes you made to the site locally.
3. Automatic building of revision history.
4. Easy setup of an authoring work-flow.
5. Authors do not need access to the production environment on Azure.

These benefits are in addition to all goodness that Grav and Azure have on their own.

Although this setup appears to be long, do not let that discourage you, it is actually quite simple. The vast majority of these steps need to be done only once.

After a description of the deployment structure (what goes where), and the Setup (just once), this article describes the setup of an author's machine and workflow along with a description of a professional authoring work-flow.

This article is written with the assumption that the reader has a basic knowledge of Git. If you need more information about Git, you can check out this basic overview.

Deployment Structure

Azure websites can be configured to pull changes from a source repository such as Github, Bitbucket, and Codeplex. As soon as your Azure website gets a signal that the repository has changed, it will retrieve the changes and publish them without requiring any user interaction.

For this article, Bitbucket was used because it provides free, private Git repositories. It is not necessary to have a private repository, a public repository would work just as well.

To change the Bitbucket repository, an author would clone the repository to his local machine, make changes, and then push the changes to Bitbucket. Bitbucket will signal the Azure website and the website will pull the changes from the repository.

This could be done by multiple authors at the same time. Each author would be responsible for merging any changes that occurred in the repository between pulling and pushing.

Setup

Create a Bitbucket repository

1. Sign up at Bitbucket.

2. Create a repository.

   1. In the top menu, click Repositories | Create Repository

      

   2. Enter a name for the repository (any name will do), and select Git. All other options can be set up as needed.

Create an Azure website.

1. Sign up for a free Azure account

   Azure offers 10 free basic websites. Free sites run on shared infrastructure, cannot have custom domain names assigned, and do not allow you to scale them up. In case you need these features later on, they can be added through configuration in the Azure management environment.

   By default, to prevent unexpected bills, your account has a spending limit of 0 which is a nice protection from costly experiments.

2. Create an empty, basic website.

   1. Open the Azure Management website.

   2. Create a website:

      

   3. Name and select the location of the site:

      

   4. After a little while, the site will will be created and running.

Link the website to the repository

1. In the overview of websites on Azure, click the name of the new website:

   

2. Open the dashboard of the website.

   

3. On the right hand side there is a list of options. Select "Set up deployment from source control":

   )

4. Select the repository provider and click the arrow.

   

5. A web browser window will pop up requesting you to log in to the selected provider (if the browser still has a valid session to the provider's site it will log in automatically.

6. Select the repository and branch that were created previously and click the check mark.

   

7. After a little while the dashboard will show that the link between the repository has been set up.

   

8. Because the repository is still empty, the website will show a generic placeholder when you browse to the site.

   

Add Grav

1. Create an empty folder on your local machine that will contain the local site.

   If you want to run the site locally, make sure this path is made available to your local web server. This will enable you to test your changes before committing them to BitBucket.

2. Open a command window on the local machine and navigate to the folder.

3. Clone the (empty) Bitbucket repository in this folder.

   1. In a web browser, open the Bitbucket repository, click the ... menu item and select Clone.

      

   2. Copy the git clone command.

   3. In the command window paste the git clone command and press enter. Below is an example command. Yours will be different.

      git clone https://[email protected]/ernow/gravdemo.git

      Enter your Bitbucket password when requested.

      This will clone the empty repository to the new folder.

4. On a local machine, download the latest Grav zip.

5. Copy the contents of the grav folder in the Grav zip into the folder.

   Make sure local folder directly contains the Grav folders (assets, bin, cache, images,...)

Configure Grav

1. Configure Grav's system and site YAML according to your wishes.
2. Configure the user's system and site YAML as needed.

Publish the website

1. Add all files to the repository (there might be a lot of warnings about line endings, you can ignore these)

   git add -A

   

2. Commit all changes (warnings about line endings might be repeated here, just ignore):

   git commit -m "Initial setup"

   

3. Push the repository to Bitbucket:

   git push origin --all Enter your Bitbucket password when requested.

   

4. This push to Bitbucket should trigger the automatic pull from Azure so browse to the Azure website:

   http://gravdemo.azurewebsites.net

5. If it still shows the blue Azure placeholder, wait a little and refresh.

   If it it takes longer than a couple of minutes (normally it takes seconds) check the website's deployment view for any messages or to re-configure the link to the repository.

Set up an author's machine

1. Make sure the author knows/understands the basics of Git.

2. Install Git and/or a Git client; whatever is preferred by the author.

   SourceTree from Atlassian is a useful tool to handle repositories, commits, pulls, merges, pushes and give a good overview of all changes.

When using SourceTree

1. Install SourceTree and configure it with the Bitbucket account the author will use.

2. Click Clone

   

3. Browse the hosted projects and select the Grav repository

4. Select a folder that will contain the cloned, local repository.

   Make sure it is not nested in another git repository.

   

5. The local folder is now ready to be authored.

When using the Command-line

1. Create an empty folder that will contain the local site.

   If you want to run the site locally make sure this path is made available to your local web server.

2. Open a command window on the local machine and navigate to the folder.

3. Clone the (empty) Bitbucket repository in this folder.

   1. In a web browser open the Bitbucket repository, click the ... menu item and select Clone.

      

   2. Copy the git clone command.

   3. In the command window paste the git clone command and press enter.

      git clone https://[email protected]/ernow/gravdemo.git

      Enter your Bitbucket password of the author when requested.

      This will clone the repository to the new folder.

4. The local folder is now ready to be authored.

Writing an article as the single author of a site

When Using SourceTree

1. First, pull the most current version of the repository to the local folder.

   

2. Write articles, change the folder structure, change configuration.

   Commit after each change that you would want to roll-back to.

   

3. When ready to publish push the local repository to Bitbucket.

   1. Make sure all changes have been committed.

   2. Push the changes to the remote:

      

When Using the Command-line

1. First, pull the most current version of the repository to the local folder.

   1. Open a command prompt.
   2. Navigate to the folder that contains the local repository.

   3. Pull the remote's status to the local repository:

      git pull origin

2. Write articles, change the folder structure, change configuration.

   Commit after each change that you would want to roll-back to.

   1. Open a command prompt.
   2. Navigate to the folder that contains the local repository.

   3. Stage all changes:

      git add -A

   4. Commit the changes to the local repository:

      git commit -m "Added article on Azure. Draft 1"

3. When ready to publish push the local repository to Bitbucket.

   1. Make sure all changes have been committed.
   2. Open a command prompt.
   3. Navigate to the folder that contains the local repository.

   4. Push the local repository to the remote.

      git push origin

Writing articles with multiple authors

All steps are the same as for a single author except for the final push to the site.

Before pushing the local repository, the author has to make sure another author did not push a change that will conflict with his local changes.

1. Commit all local changes.
2. Pull the remote.
   1. This will automatically merge any changes since the previous pull.
   2. If there are any conflicts that cannot be solved by Git they will be reported and it will be up to the author to decide and fix them.

In general it is wise to frequently pull from the remote as conflicts will be easier to solve in an early stage.

Professional Authoring Work-flow Considerations

When writing with multiple authors, designers, editors, reviewers and/or the requirement to release multiple articles and changes at once after being tested a couple of extra steps could be considered. These extra steps could be beneficial for single authors too, depending on their wish to test, experiment, and still keep a stable, public version of the site.

Use branches

When an author wants to create a change or add an article, he could create a branch and work in this branch. The work should be committed, pushed and pulled in the same way as before. By doing this, the author's work will be available for others to review, link to and edit in that branch. Because the Azure website is linked to the master branch, these changes will not appear in the production, public website.

By the time the author is content with the article, and it is time to publish the article, he should merge his branch to the master branch and push it to the remote which will automatically make it public on the website.

An extra step could be considered. Let's assume that multiple authors work on a single article and other authors work on other articles. If the editor of the website wants to publish all articles at once: he could start off by creating a branch for that publication, and setting up the basic structure in that branch.

Each first author of an article would create a branch for the article, and all other cooperating authors for that article would branch and merge to that branch. When an article is done (reviewed, designed, etc.) it can be merged to the publication branch. Once all articles have been merged, the publication branch could be merged to the master branch.

Add Azure websites for the author and staging branches

To review and test the work on a publication extra, Azure websites could be created and hooked to specific branches. These sites can be secured so only editors and reviewer would have access. Especially site structure and linking could be tested like this, and it would take away the burden on authors to run a local web server.

Pull requests

To prevent the accidental publication/modification of the wrong branches, the repository could be secured. Websites such as GitHub and BitBucket allow the assignment of branch owners. When a branch is ready to be merged to a publication or other staging branch the author would create a pull request. The owner of the staging branch could then organize the order in which branches are merged and also keep track of the work that has been done and is still left to do.