Forem: Lee Smith 🍻

Kicking the Tires on Github Actions

Lee Smith 🍻 — Thu, 12 Sep 2019 16:31:55 +0000

This post was originally published on my blog.

I've been using GitHub for over 10 years now and I really think Github Actions is one of the biggest features to date. Github Actions is essentially an automation API that "enables you to create custom software development lifecycle workflows directly in your Github repo". Based on some event you specify (such as a push or issue creation or a new release), you're able to orchestrate workflows and have Github execute them for you. Workflows are described by a workflow file that lives in the root of your repository.

There are endless possibilities with this. You could have a workflow to triage stale issues, setup code reviews, perform branch management, or automate new releases. But probably the most popular use for Actions is Continuous Integration and Deployment (CI/CD). So this means Github now offers native CI/CD that third party vendors like Travis CI and CircleCI have provided over the years. Github Actions support a plethora of languages, operating systems, and frameworks. They also offer matrix builds where you can test across multiple operating systems and language versions in parallel.

This sounds exciting! For now, Github Actions is in beta and free for public repos so I wanted to convert one of my open source Ruby on Rails apps to use Github Actions for running the test suite on push. The test suite is pretty small and the only major dependency is PostgreSQL.

To begin setting this up, my repo needs at least one workflow file. Workflow files are found in .github/workflows directory and are in YAML format.

Here's what mine looks like:

# ruby.yml

name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-18.04

    services:
      postgres:
        image: postgres:11
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5

    steps:
    - uses: actions/checkout@v1
    - name: Set up Ruby 2.6
      uses: actions/setup-ruby@v1
      with:
        ruby-version: 2.6.x
    - name: Build and test with Rake
      env:
        PGHOST: 127.0.0.1
        PGUSER: postgres
        RAILS_ENV: test
      run: |
        sudo apt-get -yqq install libpq-dev
        gem install bundler
        bundle install --jobs 4 --retry 3
        cp config/database.postgres.yml config/database.yml
        bundle exec rake db:test:prepare
        bundle exec rake spec

I've named this workflow "Build" and set it to run whenever I push to the repo. The jobs section is really the meat of the action. Jobs are made up of steps that are executed in the same virtual environment. I'm saying here that this job will run in an Ubuntu 18.04 VM and use the postgres service with PostgreSQL version set to 11. The steps first check out my repo and then sets up a ruby environment using two of Github's public actions. Next, I set some environment variables, install a development package, install my project's gem dependencies, and lastly run the test suite. Upon each push to the repo, Github executes this workflow for me and I can view the logs from the Actions tab of my project to see the output.

I'm really excited to see what else they add to enhance Actions. For now, it looks like it will be a solid competitor to the other CI/CD services out there.

Migrating to minpac for Vim

Lee Smith 🍻 — Wed, 05 Dec 2018 18:11:21 +0000

This post was originally published on my blog.

I've just done an overhaul to my dotfiles and I wanted to document how and why I migrated from pathogen to minpac.

Why minpac

Minpac is described as a "minimal package manager for Vim 8". Ok, great. How is minpac different or better than the package managers that have been around for years (Vundle, vim-plug, pathogen, etc.)?

Now that Vim 8 ships with native package management, minpac builds on top of this functionality, allowing for a more lightweight plugin. Unlike its predesessors, minpac doesn't invent it's own solution for managing the runtimepath. Another Vim 8 feature that minpac leverages is the job control feature. This allows minpac to install and update plugins in parallel.

Configuring minpac

So for me, coming from pathogen, I can delete the ~/.vim/bundle directory and create the directory where minpac will live.

rm -rf ~/.vim/bundle
mkdir -p ~/.vim/pack/minpac/opt
git clone https://github.com/k-takata/minpac.git ~/.vim/pack/minpac/opt/minpac

From here, it's a matter of configuring your .vimrc for minpac. The following is a basic example of what you might include in your .vimrc. Minpac's install instructions offer something more simple than this but I like this example because it offers the ability to have a more flexible .vimrc for the case where you want to use the same .vimrc in different environments (like on a server that doesn't have your plugins installed).

" ~/.vimrc
" Try to load minpac.
packadd minpac

if !exists('g:loaded_minpac')
  " minpac is not available.

  " Settings for plugin-less environment.
  " ...
else
  " minpac is available.
  " init with verbosity 3 to see minpac work
  call minpac#init({'verbose': 3})
  call minpac#add('k-takata/minpac', {'type': 'opt'})

  " Additional plugins here.
  call minpac#add('airblade/vim-gitgutter')
  call minpac#add('altercation/vim-colors-solarized')
  call minpac#add('itchyny/lightline.vim')
  call minpac#add('prettier/vim-prettier')
  call minpac#add('tpope/vim-commentary')
  call minpac#add('tpope/vim-endwise')
  call minpac#add('tpope/vim-fugitive')
  call minpac#add('tpope/vim-repeat')
  call minpac#add('tpope/vim-surround')
  " ...

  " minpac utility commands
  command! PackUpdate call minpac#update()
  command! PackClean call minpac#clean()
  command! PackStatus call minpac#status()

  " Plugin settings here.
  " ...
endif

" Common settings here.
"...

Here's minpac in action. After I open vim, I update all plugins specified in my .vimrc using the utility command :PackUpdate. After the update is finished, :PackStatus shows a summary of what changed.

Of course, minpac also works with Neovim if you prefer that over Vim 8. Check out the docs for a slightly different install process.

Happy Vim'ing! 🍻

Static Sites Powered By Nuxt and AWS

Lee Smith 🍻 — Mon, 20 Aug 2018 18:42:32 +0000

This post was originally published on my blog.

I'd like to share how I built my new personal site and blog. My goals were pretty simple as far as a static blog. Obviously, I didn't want to use a CMS. I wanted to use a static hosting environment so I didn't have to manage a server. I also wanted to explore technologies aimed at the front-end since I spend a lot of my time building web applications using server-side languages. There's really a lot going on right now in the static site generation space. Static sites have certainly proven their value, especially when it comes to performance and cost factors. From the React community, Next.js and Gatsby have taken off in popularity. Hugo is a popular project written in Go and VuePress came alive just this past April.

So I ended up choosing Nuxt as my static site generator. Nuxt is a high level framework that sits on top of Vue and offers many cool features and also some conventions that I appreciate. I've been keeping my eye on Vue for a while and I like what I see so that also played a part in my choosing Nuxt. I'm also deploying to AWS S3 and using AWS Cloudfront as a CDN for better performance and HTTPS communication. This site is open source so feel free to check it out on Github.

Nuxt

Nuxt, primarily inspired by Next.js, is a high level framework for developing universal JavaScript applications in Vue. By default, Nuxt supports server-side rendering but can also be configured as a SPA. The big innovation of Nuxt is "pre rendering" which allows you to generate your web app so that it can be hosted on any of the popular static hosting providers like Amazon S3 or Netlify.

Starting out, I used the following commands to create my project:

# install vue-cli globally
npm install -g vue-cli

# create a project using a nuxt template
vue init nuxt-community/starter-template leesmith-dot-net

# cd into the project and install dependencies
cd leesmith-dot-net
npm install

# spin up a local dev server on port 3000
npm run dev

At this point, Nuxt has created a basic project structure including assets, components, layouts, pages, and plugins among others. With my site, I've built a basic layout and each post I make simply sits inside my layout. One of the conventions that you get with Nuxt is that each .vue component file you place in the pages directory gets generated into its own html file. Inside of my pages directory, I have a posts directory that contains each blog post of my site. With this convention, there's very little configuring to do on your part.

The nuxt.config.js file defines project-wide settings. There is a section that allows you to set the attributes for the elements in the <head> section. You'll want to set things like language and meta tags among other things.

As far as a layout, the following would suffice for something very basic:

<template>
  <header>
    <h1>Example Site Title</h1>
  </header>
  <section>
    <nuxt/>
  </section>
</template>

<script>
</script>

<style>
</style>

The following would suffice for a basic page:

<template>
  <article><p>Hello World</p></article>
</template>

<script>
</script>

<style>
</style>

One of my favorite features you get out of the box are page transitions, which are powered by Vue. It gives the site a native feel instead of the usual "blink" when clicking around to different pages. To control the styling of page transitions, you need to add styles for the transition hooks, like so:

.page-enter-active,
.page-leave-active {
  transition: opacity 0.3s;
}

.page-enter,
.page-leave-to {
  opacity: 0;
}

I've chosen Bulma as my CSS framework. I'm also using Fontawesome icons as well as vue-highlightjs plugins. I'll probably write some future posts detailing these further.

In addition to the project-wide settings in nuxt.config.js, you can control meta tags at the page level. I want each blog post (page) to have a custom title. To do this, you can tap into Nuxt's API - specifically the head() method:

// script section of your vue component
<script>
export default {
  head() {
    return {
      title: "Static sites powered by Nuxt and AWS - LeeSmith.net",
      meta: [
        {
          hid: "description",
          name: "description",
          content: "Static sites powered by Nuxt and AWS"
        }
      ]
    };
  }
};
</script>

So those are some of the basics as far as Nuxt. From here you could generate your site:

npm run generate

Nuxt produces a dist folder containing your generated site files. These are the files you'd push to your static host. Let's see how that works when hosting with Amazon.

AWS Setup

Getting set up on AWS is pretty straight forward. They have easy to follow documentation for the entire process. I won't recreate their documentation here but the first thing you'll do is create your S3 bucket and enable static hosting on it. I'm assuming you've already registered a domain name but if you haven't, I recommend using AWS Route 53 for domain registration and DNS management.

Follow the AWS S3 walkthrough for creating and configuring your S3 bucket.

At this point, you could push up your generated site files to make sure your bucket is configured properly. I highly recommend using the awscli when working with AWS. Pointing and clicking through the web console isn't the most efficient way to get things done. Once awscli is installed and configured for your AWS account, you should be able to copy your files to your bucket:

aws s3 cp dist s3://mybucket --recursive

Now that the S3 bucket is serving your site, the next thing you would do is serve your website through an AWS Cloudfront distribution. This allows you to improve performance by making your website's static files (such as HTML, images, and video) available from data centers around the world (which they call edge locations). With AWS Cloudfront you can also configure your website to be served over HTTPS. Speed and security are vital for today's web. HTTPS for websites is pretty much the standard as browsers will now warn you when pages are not using HTTPS. Google search algorithms also favor faster websites.

Follow the AWS Cloudfront walkthrough for creating and configuring your Cloudfront distribution.

So far, lighthouse scores look pretty good:

Deployment

I've put together a simple script to automate deployment. This script depends on your AWS settings. It creates a .env file if one does not exist and after you fill in the two variables (S3 URI and Cloudfront distribution ID), deployment is as simple as running the script. I'm using the S3 sync command to push my files to the bucket. The sync command is using a cache-control option to set a far future max-age value for the files as well as a delete option that will delete anything in the bucket that's not contained in my dist directory. In addition to sync'ing the files to the bucket, we also need to invalidate our cloudfront distribution so that future visits to the site get served the latest content.

# deploy.sh
if [ ! -f .env ]; then
    echo "# Project environment variables...do not commit this file." >> .env
    echo "AWS_CF_DIST_ID=" >> .env
    echo "AWS_S3_URI=" >> .env
    echo "Please add the necessary values to the .env file."
else
    export $(egrep -v '^#' .env | xargs)
    echo "CF DIST -> $AWS_CF_DIST_ID"
    echo "S3 URI -> $AWS_S3_URI"
    echo "Performing sync..."
    aws s3 sync dist s3://$AWS_S3_URI --cache-control "max-age=31536000" --delete
    echo "Invalidating cloudfront distribution..."
    aws cloudfront create-invalidation --distribution-id $AWS_CF_DIST_ID --paths "/*"
    echo "Deploy complete! 🎉"
fi

You could automate your deploys even further by using a CI/CD service like Semaphore so that each push to your master branch kicks off a deploy. This is very similar to what Netlify offers. I could see that being a nice feature when working on a larger project.

So far, I've really enjoyed playing around with Nuxt. Hit me up on Twitter with any questions/comments.

Cheers! 🍻