This is a Jekyll site. I learned a lot trying to deploy it. Here’s what’s up.

You love Ruby (like I do). You need a static site (like this one). And you want to host it for free on Render.com (like this site is). So you do what I did and start a new Jekyll site to get to work.

For the purposes of this tutorial, I’ll assume that you’ve already followed Render’s own instructions to deploy a Jekyll site and that you’re using:

Problem #1: Render’s Ruby Version

The first problem you’ll encounter is a mismatch in Ruby and Gem versions when you deploy your site on Render.com for the first time. This happens for two reasons:

  1. On your local machine, every time you run bundle update and/or bundle install, bundler chooses gems that are compatible with your local Ruby version, which right now is 3.3.0.

  2. Render automatically uses Ruby 3.2.2 for its environment, meaning that several of your gems likely have code that Render’s virtual machines cannot execute (since they’re running Ruby 3.2.2 and your computer uses Ruby 3.3.0).

To fix this, you’ll need to explicitly declare your version of Ruby inside your Gemfile to tell every machine that runs your project to use the same Ruby version. We’ll follow Render’s own documentation to do it like this:

Create the file .ruby-version in your main directory, and explicitly declare Ruby 3.2.2:

# my_jekyll_site/.ruby-version

3.2.2

In your Gemfile, anywhere below source "https://rubygems.org" add the line:

# my_jekyll_site/Gemfile

ruby File.read('.ruby-version').strip

Now whether you run bundle exec jekyll build on your machine or inside a Render deployment, both environments will utilize the same Ruby version.

Problem #2: Local Ruby Version

Having solved one problem, we’ve created a new one. Even though we’re telling our machine to use Ruby 3.2.2, we don’t actually have Ruby 3.2.2 installed on our local machine. We’re still using Ruby 3.3.0, which is incompatible with many of the Gems that are chosen when we run bundle update and/or bundle install.

To fix this, we’re going to use a tool called asdf. Installation instructions can be found here. Once installed, we can solve our problem with a few simple commands.

Before we do that, though, let’s install Ruby 3.2.2, by running:

asdf install ruby 3.2.2

(When you install asdf, you will probably have to reinstall Ruby 3.3.0 using asdf. You can do this by running asdf install ruby 3.3.0 in your console after asdf’s setup finishes.)

Now, we need to tell our system to use Ruby 3.2.2. We need to decide: Do you want asdf to do this for my entire local machine or do you want to do it for only this project?

Declare Global Ruby Version

If you decide for your entire machine, you will run the command:

asdf global ruby 3.2.2

Now you should have a file in your home directory called .tool-versions which should say:

# ~/.tool-versions

ruby 3.2.2

This will also include any other tool versions you’ve declared with the asdf global command.

Declare Local Ruby Version

If you’d rather use Ruby 3.2.2 only for your website but Ruby 3.3.0 for everything else on your computer, you can do this by:

  1. Navigate to your site’s directory (where _config.yml lives).

  2. Run asdf local ruby 3.2.2 (This will create a .tool-versions file in your current directory.).

  3. Run asdf global ruby 3.3.0 (This doubly ensures that the .tool-versions in your home directly says ruby 3.3.0.).

In the same directory as _config.yml, you should have a .tool-versions file that says:

# my_jekyll_site/.tool-versions

ruby 3.2.2

Great work! Now whenever you work on your site, your computer will be using the same technology stack as Render’s servers.

(Don’t forget to commit & push your changes to Github so Render can pick them up and deploy your updated site.)

Problem #3: Declaring Jekyll Environment on Render

Whenever you run bundle exec jekyll serve or bundle exec jekyll build on your own computer, Jekyll declares a variable for itself called jekyll.environment which defaults to development. In this development environment, Jekyll turns off a number of features, including things like Disqus and Google Analytics (if you’re using the default minima theme).

Unfortunately, when we deploy on Render, jekyll.environment still gets set to development. To turn on those features, we need it set to production instead.

To do this, log in to your Render dashboard, click the name of the service you’ve used to deploy your site and navigate to Settings.

Scroll down to Build Command, and click Edit. Update the field to read:

JEKYLL_ENV=production jekyll build

When you save the change, Render will automatically redeploy your site with the updated build command. And voila! It should work 🙌

(And if it isn’t, feel free to leave a comment below 👇, and it will be my pleasure to look into it with you and see if we can fix it 🛠️)