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"
deploy section describes deployment targets, which describe where to deploy to and how to do the deployment. In the example above, the targets are
kind attribute describes the deployer to use. In the example above,
rsync are used for the
staging targets, respectively.
With GitHub Pages or Bitbucket
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' ]
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.
% 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/.
To deploy the site using the nanoc deploy command, add a deployment target with the target
git to the Nanoc configuration file (nanoc.yaml, or config.yaml on older sites):
deploy: default: kind: git branch: gh-pages
For Bitbucket, set
master, and for GitHub, set it to
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 likely to be out of sync with the
gh-pages branch in the repository in the output/ directory.
To use rsync as the deployment method, set
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' ]
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
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
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! %