HOWTO install s3_website on macOS

While converting my various websites to hugo static sites, I looked at various ways to push my local changes to production. Ultimately, I chose s3_website as the best choice for my setup. The tool is static site generator agnostic so works well with jekyll, middleman, hugo and others but in case you are curious, the tech stack I use is:

  • hugo [static website generator]
  • Amazon Web Servics (AWS)
    • S3 for storage / web hosting
    • Cloudfront for CDN
    • Certificate Manager for TLS
    • Route 53 for DNS (alias support)
  • s3_website for deploys

Installing s3_website on macOS

Installing s3_website on macOS requires a few dependencies so I wanted to document them here for anyone else interested in using it. Note: this article only covers the installation of s3_website so you will still have to configure it for your specific website.

Install rbenv on macOS

Like most folks, I started out following the directions from the s3_website repo README file (gem install s3_website) and immediately hit a snag (on a fresh macOS High Sierra 10.13.6 install):

hiro@h42:~|⇒  gem install s3_website
Fetching: thor-0.20.0.gem (100%)
ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /Library/Ruby/Gems/2.3.0 directory.

At first, I tried a few solutions like using the --user-install options but ran into issues further down the line. Ultimately, it make sense to install a ruby environment manager like rbenv to update user install ruby runtimes but not change the system install.

To install rbenv, let’s use brew:

$ brew install rbenv

then initialize it (which will provide shell specfic directions, in my case zsh):

$  rbenv init
# Load rbenv automatically by appending
# the following to ~/.zshrc:

eval "$(rbenv init -)"

Go ahead and add that eval line to the end of your shell’s rc file. Next, check your install with rbenv-doctor:

$ curl -fsSL | bash

which will then request that you install a ruby version. At this time, it suggest ruby v2.2.4 but you can google for the latest version and use that:

$ rbenv install 2.5.1

Almost done. For simplicity, I do actually set the global ruby version to the freshly isntalled 2.5.1:

$ rbenv global 2.5.1

Then restart my shell and viola:

hiro@metaverse:~|⇒  ruby --version
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin16]

Install s3_website on macOS

Now go ahead and install the s3_website gem:

$ gem install s3_website

and then run the built in install command:

s3_website install

At this point, you need to configure s3_website for your website. Then when you try the --dry-run option you’ll hit your next issue:

hiro@metaverse:~/git/mfio|master⚡ ⇒  s3_website push --dry-run
No Java runtime present, requesting install.

Install jEnv on macOS

However, at this time, s3_website isn’t compatible with Java 10 (the version you will get with a standard brew install) so you have to install the older Java 8 runtime. Since w already went down the path of installing a ruby environment manager, might as wll do the same for Java. Enter jEnv, which is pretty straight forward to install:

$ brew install jenv

and then setup in your shell (zsh in this case):

$ echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
$ echo 'eval "$(jenv init -)"' >> ~/.zshrc

Next we use brew to install the current and older versions of Java:

$ brew cask install java
$ brew tap caskroom/versions
$ brew cask install java8

add these to jEnv so it knows about the runtimes:

jenv add /Library/Java/JavaVirtualMachines/jdk1.8.0_181.jdk/Contents/Home/
jenv add /Library/Java/JavaVirtualMachines/jdk-10.0.2.jdk/Contents/Home/

then change into your website directory (where you s3_website.yml file is) and run this command:

jenv local 1.8

Running s3_website

You’re finally ready! As I mentioned before, I always start by running s3_website with the --dry-run option to make sure everything looks correct for the push to production. Common things I foget to do are to remove and re-build the website with hugo or to set the environment variables for my AWS account. But hopefull your s3_wbsite setup will now work on macOS.