Forem: Paula Mallol

Deploy Middleman with GitHub Actions

Paula Mallol — Fri, 07 Aug 2020 21:44:03 +0000

This is the final step to get the app live using Github Pages!

Thanks for sticking with me until the end of this series :) .

Read about how to set up Middleman, either locally or inside a Docker container, in the previous blog posts.

Setting up GitHub Actions is really easy and it just requires you to create a path named ./github/workflows in your repository root directory, inside which all workflow configuration files will be.

I’ll show you how to achieve making continuous deployments of a dockerized Middleman app to GitHub Pages in just a few steps, but know that you can also configure it to make deployments to AWS or any other server you’d prefer.

You can find all sorts of predefined actions in GitHub’s marketplace.

In this case, because we are using GitHub Pages, make sure to push your repository to GitHub, make it public, and create a ‘gh-pages’ branch.

Open your repository’s settings and you should see GitHub Pages was automatically enabled after the new gh-pages branch was created and pushed:

Awesome! Thanks GitHub.

Now create a deploy.yaml file inside the .github/workflows directory with the following content:

Commit this change inside the ‘master’ branch and push it to your repository. This will generate the GITHUB_TOKEN needed by the GitHub Pages action.

This first workflow run will probably fail, that’s ok!

You can monitor workflows navigating to the ‘Actions’ tab of your GitHub repository.

Now it’s the perfect time to modify Middleman’s build configuration. When Middleman is built with the command $ bundle exec middleman build, a new build folder is created. The asset files previously located inside the .tmp/dist folder will be bundled and moved inside the ./build folder in the process.

Also, because of the way relative links are generated in GitHub Pages, we will need to set a http_prefix with the name of the repository so that it is added as a prefix to all links in the application.

Let’s edit the config.rb file and add a build environment configuration to ensure relative links and paths for .css and .js files are set properly:

Commit and then push the changes to master. This time, the GitHub Actions workflow shouldn’t take as long as the first one because we’ve configured the gems and packages to be cached.

If your workflow ran successfully, open up your GitHub Page and see what it looks like. It will most likely be located at https://your-gh-username.github.io/your-gh-repo.

Check out the demo: https://pmallol.github.io/middleman-webpack-demo/.

If you inspect the site, you should see assets are properly linked, like so:

<head>
   ...
   <link href="/middleman-webpack-demo/style.css" rel="stylesheet">
   <script src="/middleman-webpack-demo/site.min.js"></script>
</head>

Final touches

Alright, so we now have a really nice app with continuous deployment.

What’s missing, I believe, is adding a bit of content. As a final step we’re going to add an About page and link it from the Home page.

When using Middleman, all new content should be located inside the /source folder. You can read more about how Middleman manages its directory structure in their docs.

So, create an /about folder inside ./source and inside this /about folder, create a file named index.html.erb. This will be our new About page.

Add some kind of content and a link to the Home page:

And next, as the last step, let’s make this About page accessible from the Home page. Open up the Home page file located inside the ./source directory also named index.html.erb, and add a link to the About page at the very bottom:

And, that’s it!

We should see the new About page working properly either locally and on the GitHub Page.

Hope these series were useful and please don’t hesitate to drop me a line if you have any questions or comments.

Special thanks

Huge thanks to @fnbellomo who helped me figure out a lot of things throughout the process of making this demo!

Dockerize Middleman

Paula Mallol — Fri, 07 Aug 2020 21:20:56 +0000

Welcome to part 2 of the “Add Webpack, dockerize and deploy your Middleman app to Github Pages” series!

In the last post we built an empty Middleman application locally and added Webpack as the external pipeline. Now it’s time to set up the same app but inside a Docker container to get everything ready for deployment.

Head over to the previous post to learn how to set up Webpack to your Middleman app or skip this all together and learn how to deploy your Middleman app to GitHub Pages using GitHub Actions, in part 3.

Setting up Docker

If you haven’t already, download Docker.

Create a new file named Dockerfile in your repository root directory where your Middleman app already exists. We’re going to be using a Ruby 2.6.3 image and install Node.js in it.

Open the Dockerfile file and paste the following configuration for our Docker image:

Now create another file in the same root directory with the name docker-compose.yml, open it and paste these lines:

We’ll be using port 1234 for LiveReload later.

To get the app up and running using Docker:

Run $ docker-compose build to build the Docker image first.
Run $ docker-compose up to start the container and get the environment ready.

If the last command fails, make sure you don’t have the application running locally in a previous terminal session.

Your app should still be available at http://localhost:4567/, but now running inside a Docker container!

You can stop the running container pressing CTRL + C inside the terminal.

Adding LiveReload

Let’s improve the app by making sure we don’t have to refresh the browser every time we want to see new changes. In order to achieve that we’re going to add LiveReload. LiveReload will automatically refresh the browser whenever files in the repository are modified.

With the Docker container stopped, add this line to the Gemfile:

gem 'middleman-livereload', '~> 3.4.3'

Run $ bundle install to install the LiveReload gem.

Open your config.rb file and add the following lines of code under the “# Activate and configure extensions” section, to activate LiveReload in our application:

Because we modified the Gemfile, we need to build the docker image again:

Run $ docker-compose build
Start the web container again running: $ docker-compose up

Try modifying any css property to quickly see LiveReload in action. The browser should refresh the preview automatically.

Great!

Now the application is all set and ready to be deployed.

Add Webpack to Middleman

Paula Mallol — Fri, 07 Aug 2020 14:56:35 +0000

This blogpost will be the starting point for a 3 part series on how to deploy a Middleman app using Webpack to GitHub Pages in simple steps.

We’ll go through:

The creation of an empty Middleman application using Webpack as an external pipeline
Dockerizing your Middleman application (plus, adding LiveReload to refresh the browser after new changes)
Finish it off by configuring deployment to GitHub Pages using GitHub Actions

You can check out the demo to see how it ends up looking on my own personal GitHub page, or you can skip this whole blogpost and head over to the repository to check out all the files and configurations.

The final result will be an empty Middleman app with an About page, it will have Webpack integrated and all relative links working properly according to Github Pages relative paths.

Also, head over to this dev.to article by Mario if you are looking to add TailwindCSS! Middleman + TailwindCSS + Webpack

Setting up the environment locally

Middleman is really simple to set up locally and it is distributed with the RubyGems package manager so you will need to install both the Ruby language and RubyGems first.

We will be working with Ruby’s 2.6.3 version, make sure to upgrade yours if necessary. You can check which Ruby version you have installed by running $ ruby -v and easily upgrade it with rvm, a Ruby version manager:

Run $ rvm list to list the available Ruby versions installed in your rvm
Run $ rvm install 2.6.3 to install the desired version
Run $ rvm use 2.6.3 to use a specific Ruby version

Now, lets update the Ruby Gems:

$ gem update --system

If you are already good to go, follow this get started guide to install Middleman or just try running the following command in a new terminal session:

$ sudo gem install middleman

Create a new Middleman application by running middleman’s built in command $ middleman init. You can either execute it inside your project’s folder or include the desired project name in the same command and let Middleman do everything for you:

$ middleman init your_new_project

Move inside your project’s folder to check how it all looks and let’s start a Middleman server for our first live preview:

$ cd your_new_project

$ bundle exec middleman server

Open a browser at http://localhost:4567/. You should be able to see your new Middleman app!

Stop the preview server by pressing CTRL + C in the terminal session.

Adding Webpack

We’re now ready to install and configure Webpack in the project. Start with initiating npm, and then installing Webpack:

$ npm init -y

$ npm install webpack webpack-cli --save-dev

Open the package.json file created in the repository root and edit its content to add Webpack’s scripts:

Also, we’re going to need some extra packages to handle how stylesheets are bundled. To make it easier for you, just copy and paste this entire line in your terminal to install them all at once:

$ npm install --save-dev mini-css-extract-plugin sass-loader css-loader node-sass

Don’t forget to add node_modules inside the .gitignore file so as to prevent commiting all node_modules folders and files before we configure Webpack.

Next, create a file under the project’s root directory and save it as webpack.config.js:

Go ahead and run $ npx webpack inside your terminal. You should see a new .tmp/dist folder was automatically created after bundling the assets with Webpack, and inside of it, you should end up with a style.css, a site.min.js and a style.min.js files.

Nice!

Ok, so now that we made sure our files are being handled properly by Webpack, we need to make Middleman incorporate them when developing and building our app.

Open the config.rb file, where Middleman’s configuration lives, and add the following lines -we’re telling Middleman how to handle assets and where our new .css and .js files actually are-:

Finally, open up ./source/layouts/layout.erb, and replace the assets link helper inside the <head> tag of the application’s layout with the following two lines -asset’s file names have changed a tiny bit-:

Check everything’s working ok by starting your application again with $ bundle exec middleman.

Modify either ./source/stylesheets/site.css.scss or ./source/javascripts/site.js and open the browser at https://localhost:4567 to see the changes reflected live:

Here I’ve changed the background-color property to “powderblue” and added a console.log(“Hello World”); to the JavaScript file.

Great! You can further improve Webpack’s configuration by adding specific settings to your production environment and create a separate configuration file for both production and development.

We won’t get to cover that in this blogpost. That’s it for now on all matters regarding Webpack as an external service.

Coming next, we’re going to dockerize all of this!