Skip to content

Deploying to S3

Jump to bottom
Justin Pease edited this page Mar 25, 2015 · 2 revisions

The most important thing to remember about deploying the docs is that the deployment process is completely separate from the version control. The docs are hosted on Amazon S3 and have no awareness of Git or GitHub. When you make changes to the docs and push those changes to GitHub, this will have no impact on the actual generated docs. To change what users actually see on docs.basho.com you'll have to use a set of tools created by Basho.

The deployment process isn't terribly tricky in and of itself once you get the hang of it. There's a deploy.rb script in the root of the basho_docs directory that handles the deployment process. If you run the script with no arguments it will deploy the latest version of the docs for both Riak and Riak CS:

./deploy.rb

What this does is transfer the generated files from your local machine to AWS.

Setting Your Credentials

Before you can deploy the docs from your machine, however, you'll need to get the proper AWS credentials from a Basho employee who has them. The script will attempt to fetch those credentials from your environment variables. You will need to set the following variables:

Variable Value
AWS_ACCESS_KEY_ID secret
AWS_SECRET_ACCESS_KEY secret
AWS_CLOUNDFRONT_DIST_ID secret
AWS_S3_BUCKET riakdocs.en

You can set those temporarily using export:

export VARIABLE=VALUE

But it's best to store them in your .bash_profile, .bashrc, .zshrc, or related file so that they are loaded into your environment every time you start your shell.

Deploying Specific Versions

As stated above, if you run the deploy script with no arguments it will deploy the latest version of the Riak and Riak CS docs. You can deploy different versions, however, as follows:

./deploy.rb RIAK_VERSION RIAK_CS_VERSION

The following would thus deploy Riak 1.4.12 and Riak CS 1.5.1:

./deploy.rb 1.4.12 1.5.1

Deploying a New Version of the Docs

If a new version of Riak or Riak CS is released, you will need to deploy a new version of the docs and update the data/versions.yml file to both reflect the existence of the new versions and to update which is deemed latest. Here's an example of an existing versions.yml file:

riakee:
  - ['1.2.0', '1.2.1']
  - ['1.3.0', '1.3.1', '1.3.2']
  - ['1.4.0', '1.4.1', '1.4.2', '1.4.6', '1.4.7', '1.4.8', '1.4.9', '1.4.10', '1.4.12']
  - ['2.0.0', '2.0.1', '2.0.2', '2.0.4', '2.0.5']
riakcs:
  - ['1.2.0', '1.2.1']
  - ['1.3.0', '1.3.1']
  - ['1.4.0', '1.4.1', '1.4.2', '1.4.3', '1.4.4', '1.4.5']
  - ['1.5.0', '1.5.1', '1.5.2', '1.5.3', '1.5.4']
stanchion:
  - ['1.3.0', '1.3.1']
  - ['1.4.0', '1.4.1', '1.4.2', '1.4.3']
  - ['1.5.0']
riak:
   - ['1.0.0']
   - ['1.1.0', '1.1.4']
   - ['1.2.0', '1.2.1']
   - ['1.3.0', '1.3.1', '1.3.2']
   - ['1.4.0', '1.4.1', '1.4.2', '1.4.6', '1.4.7', '1.4.8', '1.4.9', '1.4.10', '1.4.12']
   - ['2.0.0', '2.0.1', '2.0.2', '2.0.4', '2.0.5']
riakcscontrol:
   - ['1.0.0', '1.0.1', '1.0.2']
# describes the latest version per project
gen_projects: ['riak', 'riakcs']
currents:
  riakee: '2.0.5'
  riakcs: '1.5.4'
  riak: '2.0.5'
  riakcscontrol: '1.0.2'
  stanchion: '1.5.0'

Let's say that version 2.0.6 of Riak is released at the same time as Riak CS version 1.5.5. What you need to do now is add 2.0.6 to the riak and riakee versions and 1.5.5 to the riakcs versions. Then, change the currents values to reflect that. Below is what the versions.yml file should look like afterward:

riakee:
  - ['1.2.0', '1.2.1']
  - ['1.3.0', '1.3.1', '1.3.2']
  - ['1.4.0', '1.4.1', '1.4.2', '1.4.6', '1.4.7', '1.4.8', '1.4.9', '1.4.10', '1.4.12']
  - ['2.0.0', '2.0.1', '2.0.2', '2.0.4', '2.0.5', '2.0.6']
riakcs:
  - ['1.2.0', '1.2.1']
  - ['1.3.0', '1.3.1']
  - ['1.4.0', '1.4.1', '1.4.2', '1.4.3', '1.4.4', '1.4.5']
  - ['1.5.0', '1.5.1', '1.5.2', '1.5.3', '1.5.4', '1.5.5']
stanchion:
  - ['1.3.0', '1.3.1']
  - ['1.4.0', '1.4.1', '1.4.2', '1.4.3']
  - ['1.5.0']
riak:
   - ['1.0.0']
   - ['1.1.0', '1.1.4']
   - ['1.2.0', '1.2.1']
   - ['1.3.0', '1.3.1', '1.3.2']
   - ['1.4.0', '1.4.1', '1.4.2', '1.4.6', '1.4.7', '1.4.8', '1.4.9', '1.4.10', '1.4.12']
   - ['2.0.0', '2.0.1', '2.0.2', '2.0.4', '2.0.5', '2.0.6']
riakcscontrol:
   - ['1.0.0', '1.0.1', '1.0.2']
# describes the latest version per project
gen_projects: ['riak', 'riakcs']
currents:
  riakee: '2.0.6'
  riakcs: '1.5.5'
  riak: '2.0.6'
  riakcscontrol: '1.0.2'
  stanchion: '1.5.0'

Once you've done that, run a typical deploy operation and the new versions should be all ready to go, i.e. available in the version bar, available through the normal URL system, etc.

Static Assets

It's important to bear in mind that the deploy process does not upload static assets such as images. If you need to add static assets like images or anything else that isn't HTML, CSS, or JavaScript, you'll need to do so manually using a tool like s3cmd.

Clone this wiki locally