Nanoc»Deploying Nanoc sites

Nanoc provides functionality for automating deployment through the nanoc deploy command. The automated deployment setup is described below.

The Nanoc configuration file (nanoc.yaml, or config.yaml on older sites) can contain a deploy section, such as the following:

deploy:
  default:
    kind: git
    remote: [email protected]:/srv/http/nanoc.ws.git
    branch: prod
    forced: true
  staging:
    kind: rsync
    dst:  "int.nanoc.ws:/srv/http/staging.nanoc.ws"

The deploy section describes deployment targets, which describe where to deploy to and how to do the deployment. In the example above, the targets are default and staging. The kind attribute describes the deployer to use. In the example above, git and rsync are used for the default and staging targets, respectively.

With GitHub Pages or Bitbucket

GitHub and Bitbucket are two repository hosting services that support publishing websites. This section explains how to use their functionality for publishing a website in combination with Nanoc.

GitHub Pages setup

The publishing of a website based on a Git repository to GitHub Pages is described in GitHub's help pages.

Clone the current repository into the output/ directory, create an orphaned branch dedicated to GitHub Pages named gh-pages, check out the new branch and remove everything in it:

% rm -rf output
% git clone . output
% cd output
[email protected]% git checkout --orphan gh-pages
[email protected]% git rm -rf .

Change the remote for this repository to point to the GitHub repository, rather than the local repository. To do so, execute the following git remote commands, replacing repo-url with the URL to the repository:

[email protected]% git remote rm origin
[email protected]% git remote add origin repo-url

Add the output/ directory to your .gitignore. Make sure that the base repository doesn’t contain the output/ directory.

Ensure that the .git directory is excluded from pruning. This is the default, but some sites might override this option. In nanoc.yaml (or config.yaml on older sites), look for a prune section, and if it exists, ensure that it has an exclude configuration option, and that it includes .git. The following is a correct set-up:

prune:
  auto_prune: true
  exclude: [ '.git' ]

Bitbucket setup

The publishing of a website based on a Git repository to Bitbucket is described in Bitbucket's help pages.

Bitbucket supports publishing a website at username.bitbucket.org, where username is your Bitbucket account name. The contents of the website will be read from a repository named username.bitbucket.org.

First of all, create a Bitbucket repository corresponding to your Bitbucket website address, e.g. ddfreyne.bitbucket.org.

Create a new Git repository inside the output/ directory, replacing repo-url with the URL to the repository (e.g. [email protected]:ddfreyne/ddfreyne.bitbucket.org.git):

% git init output/
% cd output/
output% git remote add origin repo-url

Add the output/ directory to your .gitignore. Make sure that the base repository doesn’t contain output/.

Automated deployment

To deploy the site using the nanoc deploy command, add nanoc-git to the Gemfile inside the nanoc group, and run bundle install:

group 'nanoc' do
  gem 'nanoc-git'
end
% bundle install

In the Nanoc configuration file (nanoc.yaml, or config.yaml on older sites), add a deployment target with the target git:

deploy:
  default:
    kind: git
    branch: gh-pages

For Bitbucket, set branch to master, and for GitHub, set it to gh-pages.

Publish

To publish a site, compile it and run deploy:

% bundle exec nanoc
% bundle exec nanoc deploy

After a few seconds, the updated site will appear at http://username.github.io/repo-name for GitHub, or http://username.bitbucket.org for Bitbucket.

For GitHub, we recommend removing the gh-pages branch from the base repository, since it is quite likely to be out of sync with the gh-pages branch in the repository in the output/ directory.

With rsync

To use rsync as the deployment method, set kind to rsync in the deployment configuration, and set dst to the destination, in the format used by rsync. For example:

deploy:
  public:
    kind: rsync
    dst:  "stoneship.org:/var/www/sites/example.com/public"
  staging:
    kind: rsync
    dst:  "stoneship.org:/var/www/sites/example.com/public/staging"

By default, the rsync deployer will upload all files in the output directory to the given location. None of the existing files in the target location will be deleted, but existing files with the same name will be overwritten. To deploy, run deploy with the name of a target, like this:

% nanoc deploy staging

This will deploy using the “staging” configuration. Replace “staging” with “public” if you want to deploy to the location marked with “public”.

To check whether the executed rsync command is correct, perform a dry run by passing --dry-run. The rsync command will be printed, but not executed. For example:

% nanoc deploy public --dry-run

Deleting stray files

Nanoc will, by default, only update files that have changed, and not remove any files from the remote destination. If you want to let nanoc deploy remove any files on the destination that are not part of the Nanoc site, you can modify the options used for rsync to include --delete-after, like this:

options: [ '-aP', '--delete-after' ]
This will remove all files and directories that do not correspond to Nanoc items from the deployment destination.

With fog

fog is a Ruby gem for interfacing with various cloud services, such as AWS or Google Cloud.

To use fog for deployment, install the fog gem (or add it to the Gemfile and run bundle install). Change the deployment configuration in nanoc.yaml to reflect the fog configuration. Here is an example for Amazon S3:

deploy:
  default:
    kind:                  fog
    provider:              aws
    region:                eu-west-1
    bucket:                nanoc.ws
    aws_access_key_id:     AKIAABC123XYZ456MNO789
    aws_secret_access_key: fd6eb5b112a894026d7b82aab3cafadaa63fce39
    path_style:            true

The kind attribute, which identifies the kind of deployer to use, should be set to fog. You’ll also need to specify provider, containing the name of the fog provider that you want to use. Each provider has their own configuration; see the fog provider documentation for details. For buckets whose names contain periods, path_style should be set to true.

To publish your Nanoc site, use the deploy command, as usual:

% nanoc deploy
Loading site data… done
Connecting
Getting bucket
Uploading local files
Removing remote files
Done!
%