Tuesday, Mar 14, 2017
Hosting a Jekyll site with Aerobatic can be as easy as typing in a couple of commands using the Aerobatic CLI:
[$] jekyll new my-jekyll-site [$] cd my-jekyll-site [$] aero create -n my-jekyll-site # create the Aerobatic site [$] echo "url: https://www.aerobatic.com" > _aerobatic.config.yml # override site.url for Aerobatic [$] jekyll build --config _config.yml,_aerobatic.config.yml # generate the output [$] aero deploy --directory _site # deploy output to Aerobatic Version v1 deployment complete. View now at https://my-jekyll-site.aerobatic.io
In the example above, we compiled our site locally and deployed the
/_site directory to Aerobatic. However, using Bitbucket Pipelines, we can set things up such the site is automatically built and deployed with each push to a Bitbucket repository.
First, create a repository in Bitbucket, and then push your jekyll site to the newly created repository:
# initialize new git repository [$] git init # set up our .gitignore file [$] echo -e "/_site\naero-deploy.tar.gz" >> .gitignore # commit and push code to master branch [$] git add --all [$] git commit -m "Initial commit" [$] git remote add origin email@example.com:YourUsername/jekyll-pipelines.git [$] git push -u origin master
In your website’s Bitbucket repo:
image: aerobatic/jekyll pipelines: branches: master: - step: script: - '[ -f Gemfile ] && bundle install' - 'echo "url: https://www.aerobatic.com" >> _config.yml' - bundle exec jekyll build - aero deploy --directory _site ---
To make the build as steps as streamlined as possible, there’s a ready-made docker image aerobatic/jekyll that already has Ruby, Bundler, Jekyll, aerobatic-cli, and other supporting software for building native plugin gems all ready to go.
https://!!baseurl!! is a special value that Aerobatic will substitute on the fly with the current website URL. This makes it so the same deployed version can be safely pushed to a different deploy stage and all absolute URLs will auto-correct themselves.
It’s recommended that you include a Gemfile that includes the specific version of Jekyll you want to build your site with, along with any plugin gems. Here’s the Gemfile that the
jekyll new command generates:
source "https://rubygems.org" ruby RUBY_VERSION # Hello! This is where you manage which Jekyll version is used to run. # When you want to use a different version, change it below, save the # file and run `bundle install`. Run Jekyll with `bundle exec`, like so: # # bundle exec jekyll serve # # This will help ensure the proper Jekyll version is running. # Happy Jekylling! gem "jekyll", "3.4.0" # This is the default theme for new Jekyll sites. You may change this to anything you like. gem 'minima', '2.1.0' # If you have any plugins, put them here! group :jekyll_plugins do gem "jekyll-feed", "~> 0.6" gem 'jekyll-tagging', '1.0.1' gem 'jekyll-paginate', '1.1.0' gem 'jekyll-sitemap', '1.0.0' end
It’s also a good idea to run
bundle install to generate a
Gemfile.lock that should be committed to source control.
The code for this example can be found in this Bitbucket repository.
This step only needs to be done once per account. If you haven’t already done this in Bitbucket, from the command line:
[$] aero apikey
AEROBATIC_API_KEYwith the value you got by running the
aero apikeycommand. Be sure to click the Secured checkbox.
Now that we’ve got Bitbucket Pipelines set up, we’re now ready to test that everything is working smoothly. Push a commit to your repo and Pipelines will provision a Docker container, clone your code, and run your build script which builds your site and deploys it to Aerobatic.
Aerobatic deploy stages makes it trivially easy to deploy your site to a test URL by passing the
--stage option to the
deploy CLI command. This plays nicely with Pipelines mechanism for running different build steps per branch.
image: aerobatic/jekyll pipelines: branches: master: - step: script: - '[ -f Gemfile ] && bundle install' - 'echo "url: https://www.aerobatic.com" >> _config.yml' - bundle exec jekyll build - aero deploy --directory _site develop: - step: script: - '[ -f Gemfile ] && bundle install' - 'echo "url: https://www.aerobatic.com" >> _config.yml' - bundle exec jekyll build - aero deploy --directory _site --stage staging ---
With this configuration, any push to the
master branch will deploy to
https://jekyll-pipelines.aerobatic.io and pushes to the
develop branch will deploy to
https://jekyll-pipelines--staging.aerobatic.io. This of course works with custom domains as well.
aerobatic.ymlto extend the capabilities of your static Jekyll site.
Jekyll seems to be very particular when running in the Docker container about the format of the
Gemfile. If you get the error below, look at the files in the sample repo for guidance. Some users have reported they needed a line break at the end of the
jekyll 3.4.2 | Error: (/opt/atlassian/pipelines/agent/build/_config.yml): mapping values are not allowed in this context