Documentation

How Do I Include Compiled Assets In My Bundles?

Bundles on Servd track the contents of specific Git Commits to ensure you have a clear papertrail from commit to deployment on the Servd platform. By default this means that only files which are part of your commit will end up inside the subsequent bundle.

If your CSS, JS and static images are checked into your repo already then you shouldn't have any problems. Build a bundle and you're all set! If not, there are a few options you can choose from to get everything set up nicely:

Strategy 1: Add the files to the commit

The easiest, if not the most popular, solution to this is to just add your compiled assets to your repo. This will ensure your files end up exactly where you expect inside your bundles and in the exact form that they take in the Git Commit.

The primary disadvantage of this approach is that you may subsequently experience merge conflicts on these files if you're using multiple Git branches in your repo. However there area couple of easy fixes:

a. Recompile

When git complains about merge conflict on these files, just re-run your buildchain to generate new compiled assets and then resolve the merge conflict. Easy.

b. Ignore the conflict

Alternatively you can create a .gitattributes file in the root of your repo which lists the compiled files with a simpler merge strategy:

/web/assets/css/app.css merge=theirs
/web/assets/js/app.js merge=theirs

With that file added to the repo git will simply accept the remote version of the file when it encounters a merge conflict. You can then re-run your buildchain and create a new commit with the updated files.

Strategy 2: Use The Servd CDN

If you're using the Servd Asset Platform for asset volumes inside Craft, you're already making use of the CDN, but you can use it for arbitrary files outside of Craft volumes.

To do this you'll need to connect to the platform via SFTP. You can then organise your files however you like. We like to create a directory called assets and inside that create a directory for each of our environments: staging, production etc.

We can then either manually upload our compiled assets to the CDN as part of our deployment process, or include relevant SFTP commands in our CI process to do it automatically whenever we release a new version of our project.

If you want to use this strategy we recommend using an environment variable to define the base URL of your CDN assets. That way it can be different in each environment without having to change any code.

Also, be aware that the CDN will cache assets for a while, so you might need to employ some cache busting techniques such as appending a query parameter or including a revision number in the filename of your compiled assets.

Strategy 3: Use an External Continuous Integration Platform

Any external CI provider, including but not limited to:

  • Gitlab CI
  • Github Actions
  • Buddy Works
  • Deploybot

Can be used to build our assets before triggering a bundle build on Servd.

Under normal circumstances Servd will build a bundle directly from the contents of a commit. If you want to avoid committing these files you can also send an archive of files to use instead.

The steps for your CI platform look a little like this...

  1. Clone your repo
  2. Perform any relevant build steps such as compiling CSS and JS
  3. Make sure all compiled assets are in their final locations inside your repo's directory structure (probably somewhere inside your web folder)
  4. Use the Servd Custom Webhook Script to archive and upload your files

Servd Custom Webhook Script?

This script can automate the archive and upload of your a craft base directory and trigger a bundle build based on the contents of this archive.

You can run it using a single command in your CI script which looks like this:

curl -L https://app.servd.host/servd-webhook-script | sh -s [project-slug] [webhook-secret] [commit-sha] [path-to-craft-base-dir] [comment]

The arguments are as follows:

  • [project-slug] - Your project's slug from the Servd dashboard
  • [webhook-secret] - Your project's webhook secret from the Servd dashboard
  • [commit-sha] - The SHA of the commit you're currently working with. This is usually supplied as an $ENVIRONMENT_VARIABLE by your CI platform
  • [path-to-craft-base-dir] - A relative or absolute path to your craft base directory (containing config, web, templates etc)
  • [comment] - A comment to attach to the bundle. It's usually a good idea to just use the first line of the Git commit comment

A real world example from Gitlab CI which we use to deploy the servd.host website:

curl -L https://app.servd.host/servd-webhook-script | sh -s $SERVD_PROJECT_NAME $SERVD_SECRET $CI_COMMIT_SHA ./src "${CI_COMMIT_TITLE}"

GitLab supplies the $CI_* variables and we have defined the others as 'secrets' in the GitLab dashboard. Your CI provider of choice should allow you to do something similar.