Add guide on automated Travis CI rebuilds

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Aug 24, 2016 · 1325251 · 1325251
1 parent ca0c658
commit 1325251
Show file tree

Hide file tree

Showing 6 changed files with 160 additions and 2 deletions.
diff --git a/listings/travis.yml b/listings/travis.yml
@@ -0,0 +1,31 @@
+# Travis CI config for automated Nikola blog deployments
+language: python
+cache: apt
+sudo: false
+addons:
+  apt:
+    packages:
+    - language-pack-en-base
+python:
+- 3.5
+before_install:
+- git config --global user.name 'Travis CI'
+- git config --global user.email 'travis@invalid'
+- git config --global push.default 'simple'
+- pip install --upgrade pip wheel
+- echo -e 'Host github.com\n    StrictHostKeyChecking no' >> ~/.ssh/config
+- eval "$(ssh-agent -s)"
+- chmod 600 id_rsa
+- ssh-add id_rsa
+- git remote rm origin
+- git remote add origin git@github.com:USERNAME/REPO.git
+- git fetch origin master
+- git branch master FETCH_HEAD
+install:
+- pip install 'Nikola[extras]'
+script:
+- nikola build && nikola github_deploy -m 'Nikola auto deploy [ci skip]'
+notifications:
+    email:
+        on_success: change
+        on_failure: always
diff --git a/posts/5000-commits.txt b/posts/5000-commits.txt
@@ -1,7 +1,7 @@
 .. title: 5000 commits to Nikola!
 .. slug: 5000-commits
 .. date: 2014-09-21 08:00:00 UTC
-.. tags: python, github, devel
+.. tags: python, GitHub, devel
 .. link: https://github.com/getnikola/nikola/commit/a99ef7a06bbd9bf07be44e019a15a991248e0ff4
 .. description: Nikola has just hit 5000 commits!
 .. type: text

diff --git a/posts/automating-nikola-builds-with-travis-ci.rst b/posts/automating-nikola-builds-with-travis-ci.rst
@@ -0,0 +1,116 @@
+.. title: Automating Nikola rebuilds with Travis CI
+.. slug: automating-nikola-rebuilds-with-travis-ci
+.. date: 2016-08-24 18:05:25 UTC
+.. tags: Travis CI, GitHub, automation, tips
+.. author: Chris Warrick
+.. type: text
+
+In this guide, we’ll set up Travis CI to rebuild a `Nikola
+<https://getnikola.com/>`_ website and host it on GitHub Pages.
+
+Why?
+----
+
+By using Travis CI to build your site, you can easily blog from anywhere
+you can edit text files. Which means you can blog with only a web
+browser and `GitHub.com <https://github.com>`_ or try a service like `Prose.io <http://prose.io/>`_.
+You also won’t need to install Nikola and Python to write. Or a real computer,
+a mobile phone could probably access one of those services and write something.
+
+Caveats
+-------
+
+* The build might take a couple minutes to finish (1:30 for the demo site;
+  YMMV)
+* When you commit and push to GitHub, the site will be published
+  unconditionally. If you don’t have a copy of Nikola for local use, there is
+  no way to preview your site.
+
+What you need
+-------------
+
+* A computer for the initial setup that can run Nikola and the Travis CI
+  command-line tool (written in Ruby) — you need a Unix-like system (Linux,
+  OS X, \*BSD, etc.); Windows users should try *Bash on Ubuntu on Windows*
+  (available in Windows 10 starting with Anniversary Update) or a Linux virtual machine.
+* A GitHub account (free)
+* A Travis CI account linked to your GitHub account (free)
+
+Setting up Nikola
+-----------------
+
+Start by creating a new Nikola site and customizing it to your liking. Follow
+the `Getting Started guide <https://getnikola.com/getting-started.html>`_. You
+might also want to add support for `other input formats
+<https://getnikola.com/handbook.html#configuring-other-input-formats>`_, namely
+Markdown, but this is not a requirement (unless you want to use Prose.io).
+
+After you’re done, you must configure `deploying to GitHub
+<https://getnikola.com/handbook.html#deploying-to-github>`_ in Nikola.
+Make your first deployment from your local computer and make sure your site
+works right. Don’t forget to set up ``.gitignore``. Moreover, you must set
+``GITHUB_COMMIT_SOURCE = False`` — otherwise, Travis CI will go into an
+infinite loop.
+
+If everything works, you can make some change to your site (so you see that
+rebuilding works), but don’t commit it just yet.
+
+Setting up Travis CI
+--------------------
+
+Next, we need to set up Travis CI. To do that, make sure you have the ``ruby``
+and ``gem`` tools installed on your system. If you don’t have them, install
+them from your OS package manager.
+
+First, download/copy the ``.travis.yml`` file (note the dot in the beginning;
+the downloaded file doesn’t have it!)
+and adjust the real name, e-mail (used for commits; line 12/13), and the
+username/repo name on line 21. If you want to render your site in another
+language besides English, add the appropriate Ubuntu language pack to the list
+in this file.
+
+.. listing:: travis.yml python
+   :linenos:
+
+Next, we need to generate a SSH key for Travis CI.
+
+.. code:: console
+
+   echo id_rsa >> .gitignore
+   echo id_rsa.pub >> .gitignore
+   ssh-keygen -C TravisCI -f id_rsa -N ''
+
+Open the ``id_rsa.pub`` file and copy its contents. Go to GitHub → your page
+repository → Settings → Deploy keys and add it there. Make sure *Allow write
+access* is checked.
+
+And now, time for our venture into the Ruby world. Install the ``travis`` gem:
+
+.. code:: console
+
+   gem install --user-install travis
+
+You can then use the ``travis`` command if you have configured your ``$PATH``
+for RubyGems; if you haven’t, the tool will output a path to use (eg.
+``~/.gem/ruby/2.0.0/bin/travis``)
+
+We’ll use the Travis CI command-line client to log in (using your GitHub
+password), enable the repository and encrypt our SSH key. Run the following
+three commands, one at a time (they are interactive):
+
+.. code:: console
+
+   travis login
+   travis enable
+   travis encrypt-file id_rsa --add
+
+Commit everything to GitHub:
+
+.. code:: console
+
+   git add .
+   git commit -am "Automate builds with Travis CI"
+
+Hopefully, Travis CI will build your site and deploy. Check the Travis CI
+website or your e-mail for a notification. If there are any errors, make sure
+you followed this guide to the letter.
diff --git a/state_data.json b/state_data.json
@@ -1,3 +1,3 @@
 {
-  "last_deploy": "2016-08-24T14:17:41.008642"
+  "last_deploy": "2016-08-24T18:35:15.660969"
 }
diff --git a/stories/documentation.txt b/stories/documentation.txt
@@ -39,6 +39,9 @@ the current GitHub master, check out `Nikola on ReadTheDocs
 `Using Social Buttons <social_buttons.html>`_
     Replacing AddThis with other solutions.
 
+`Automating Nikola rebuilds with Travis CI </blog/automating-nikola-rebuilds-with-travis-ci.html>`_
+    Blogging anywhere with Nikola, Travis CI and GitHub Pages.
+
 `Tutorial by Tim van der Linden <http://shisaa.jp/postset/nikola-web.html>`_
     Goes from installing to developing a custom theme.
 

diff --git a/stories/manual.txt b/stories/manual.txt
@@ -1279,6 +1279,14 @@ If you want to use a custom domain, create your ``CNAME`` file in
 output directory. To add a custom commit message, use the ``-m`` option,
 followed by your message.
 
+Automated rebuilds with Travis CI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want automated rebuilds and GitHub Pages deployment, allowing you to
+blog from anywhere in the world, follow this guide:
+`Automating Nikola rebuilds with Travis CI
+</blog/automating-nikola-rebuilds-with-travis-ci.html>`_.
+
 Comments and Annotations
 ------------------------