For the past few years, this blog has been hosted on a personal Kubernetes cluster. In addition to my blog, I used the cluster to host a few other websites, as well as run occasional compute jobs. Kubernetes is a great, very flexible technology, and since (full disclosure) I work at Google, throwing container images at a server infrastructure feels very natural to me. But maintaining a Kubernetes cluster means paying for the VMs, and lately I’ve been wondering if I can avoid those costs.
So I started to move my sites and my jobs off Kubernetes, and finally, a month ago, I was able to turn down the cluster completely. I migrated this blog to Cloud Run, a container-based serverless environment that Google introduced in April. It’s been working perfectly so far, and since it fits easily into the free tier, my costs have gone down to effectively zero. And I know that if I ever get slashdotted… this is Google: they’ll scale me up as needed.
In this article, I’ll discuss whether a serverless platform might be a good fit for a static site. Then I’ll provide a tutorial for deploying a Jekyll-based static site to Cloud Run. Along the way you’ll also learn some good practices for containerizing static sites. It shouldn’t be too difficult to adapt these instructions for other static site generators such as Hugo.
Why serverless for static sites?
These days we have a number of choices for hosting static sites. One of the easiest is to use a cloud storage service such as Amazon S3 or Google Cloud Storage. Just upload your static content to a storage bucket, configure a few knobs, and you have a website. Source control services such as GitHub and Bitbucket also often provide web hosting for content pushed to their repositories. For simple static sites, options such as these are generally straightforward and inexpensive.
With the advent of the serverless cloud, we now have a third inexpensive option. With many serverless platforms, you don’t pay for containers or VMs or storage—just the compute resources that you actually use. And for a static site, you don’t use very much.
But still, why choose a general-purpose serverless platform over storage-based or source control hosting?
Different deployment options always have pros and cons. One of the chief benefits of general-purpose serverless, however, is flexibility. Static sites are almost never “purely” static. Maybe you need custom error handling and error documents. Maybe you need more sophisticated redirects. Maybe you need to hide some content behind authentication. Maybe the majority of your site is static, but you still need server-side scripts for a few cases. Simple content-based hosting generally provides some configuration knobs to help with these extras, but they can’t always handle every case.
In my blog, I have a large number of redirects, and a few special cases handled by specially crafted Nginx configuration. So for me, one of the big draws of Google Cloud Run was the ability to provide my own container with my own Nginx config files.
There’s of course no one size that fits all. But if you’re having trouble getting S3 to handle your site the way you need, or if you’re currently running on VMs or on your own servers and want to cut costs, a serverless platform might be your sweet spot as well.
Jekyll on Cloud Run
The rest of this article is a tutorial for deploying a Jekyll-based site to Google Cloud Run. Cloud Run is particularly effective for static sites because it uses containers, letting you configure your own web server for static content. (In contrast, “function” or “lambda” based platforms are typically tailored for specific dynamic web languages or frameworks, and might not support static sites at all.)
Note that there are two “flavors” of Cloud Run: a fully-managed flavor that runs directly in Google’s infrastructure, and a flavor that runs on your own Kubernetes Engine cluster. For static sites, you will probably prefer the former, because it’s the one that gives you the very cheap pay-per-use model. (And in my case, part of the whole purpose was to get rid of my Kubernetes cluster.) However, it’s still easy to adapt these instructions to deploy to Cloud Run on GKE if you want more control over the infrastructure. This video has additional info on the differences between the two Cloud Run flavors.
Jekyll is written in Ruby. I’ll assume you already have Ruby and Jekyll installed, but if you need help, the Jekyll documentation has detailed instructions.
Creating and testing a Jekyll project
We’ll start by creating a new Jekyll project. (If you have an existing project, feel free to use it instead.)
Now to run your site locally:
Jekyll will build your site locally and serve it on port 4000. Point your web browser to localhost:4000 to see.
You can edit your site by editing posts in the
_posts directory, or by making changes to the configuration and layouts. As you make changes,
jekyll serve will notice the file edits and rebuild your site automatically. We won’t go through all the details of how to use Jekyll here, but there’s a good tutorial in the Jekyll documentation.
C to stop the server.
jekyll serve is a convenient way to view your site during development, but it’s not how you should run it in production. In fact, as we shall see, you don’t need Jekyll, or even Ruby, installed at all in your final production container. So let’s explore how to create an efficient production image of your site.
Creating a production Docker image
Docker has become the de facto standard way to package applications for deployment, and Cloud Run conveniently uses Docker images as its input format. Here we’ll create a Docker image to deploy your site.
Our desired image will serve our static site directly from Nginx, a high-performance web server. It’s a static site, so we don’t need Jekyll or even Ruby at runtime. However, we do need Jekyll to build the static site. That is, building and running have different requirements, so we’re going to separate them into different phases, as diagrammed below.
We will write the items in the blue boxes:
- Site content and Jekyll configs as inputs to Jekyll
- Nginx config files and startup scripts that launch Nginx with the correct configuration.
- A Dockerfile that describes the build process.
Then when we perform a
docker build, it will proceed in two phases. First, the build phase runs, taking our blog posts and Jekyll configs, and running Jekyll to produce HTML output. Second, the built HTML, along with the Nginx configs and startup scripts, are installed into the runtime image.
mysite directory, create a subdirectory called
_app. This directory will contain our Nginx configuration files and startup script. Because it begins with an underscore, Jekyll won’t try to build it as part of your site html. It will just pass directly through into your final runtime image.
Let’s write the Nginx configuration. Create a file called
_app/nginx.conf.in with the following content:
This isn’t an Nginx tutorial, so I won’t go over everything here in detail. However, I’ll point out a couple of things.
First, we intentionally set
worker_connections to 80. Cloud Run currently has a maximum concurrency of 80 (meaning it will allow up to 80 simultaneous connections to each instance). Nginx can often handle more, but because Cloud Run currently has this limit, we’ll pass that info on to Nginx so it can optimize itself.
Second, notice that we’re listening to port
$PORT. This is actually not “valid” Nginx config syntax by itself. Instead, we’re going to write a startup script that treats this Nginx config as a template, and substitutes the actual port number here at runtime. This is because Cloud Run’s runtime specification states that the port isn’t actually known until runtime: it will tell you what port to listen to via the
PORT environment variable.
So our next task is to write a script that reads the environment variable and substitutes the correct value into the config template. Create a file called
_app/start.sh with the following content:
Let’s pick apart what this is doing. First, it checks that the
PORT variable is set, and if not, it sets it to a default value of
8080. Cloud Run always sets the variable, but we’re also going to test this image locally outside Cloud Run, so we’ll make sure it has a value in that case.
Next, we substitute the value of the
PORT environment variable in the
nginx.conf.in file, and write the result to the final
nginx.conf that we’ll use. Finally, we start Nginx.
It’s important to tell
envsubst to substitute only the
PORT environment variable (because our Nginx configuration file also includes syntax like
$uri that we want
envsubst to leave alone.)
It’s also important to prefix our Nginx command with
exec. This causes Nginx to replace the script process so that it receives signals. This is important for Cloud Run to be able to control the container effectively.
Save the two files, and set the execute bit on your start script:
You should now have the two files
start.sh inside the
_app directory in your
Writing the Dockerfile
Next we’re going to write a Dockerfile to build a Docker image of your site.
Go back to your
mysite project directory, and create another subdirectory called
_build. Again, because this name begins with an underscore, Jekyll won’t try to treat any of its files as site content.
Create a file called
_build/Dockerfile with the following content:
This may look a bit more complex than other “getting started” Dockerfiles you may have seen, so let’s take a closer look at what it’s doing.
Remember that our build process was going to proceed in two stages. You can see that now in this multi-stage Dockerfile. The first stage stage starts with the standard Ruby-Debian base image, installs your bundle (which should include Jekyll), and performs a production Jekyll build. The results are left in the
Then the second stage creates the final image that we will deploy to Cloud Run. It starts with the standard Nginx base image, copies in our Nginx config file and startup script, and also copies in the built html files from the first stage. Note that the final image includes only what is needed to serve your site: Nginx, but not Ruby or Jekyll. This two-stage strategy is a common best practice when building Docker images.
Testing your image locally
Now that we have a Dockerfile, we can build the image locally. Return to your
mysite directory, and perform a docker build, pointing at our Dockerfile.
This will build your site as a Docker image and tag it with the name
mysite. We can now try running it.
This will run your image with your static site, and expose port 8080. Now you can test it by pointing your web browser to localhost:8080.
C to stop your Docker image.
Deploying to Cloud Run
Now that we have a working Docker image, it’s time to deploy to Cloud Run.
Setting up Google Cloud
If you do not yet have a Google Cloud project, go to the console and create one. You’ll need to enable billing in order to use Cloud Run. But don’t worry—unless your site has a truly massive amount of traffic, you’ll easily fit into the free tier for this tutorial.
Enable Cloud Build and Cloud Run in your project, if you haven’t already:
- Navigate to Cloud Build in the console and click “Enable Cloud Build API”.
- Navigate to Cloud Run in the console and click “Start Using Cloud Run”.
You’ll also need the Google Cloud SDK installed. Set the default project as follows (substituting your project ID for
Building in the cloud
You could push a local image to the cloud in preparation to deploy to Cloud Run, but it is easier and safer to build in the cloud. We’ll create a simple configuration to build your site image in Google Cloud Build.
Create a file
_build/cloudbuild.yaml. Copy the following into it:
This configuration performs a Docker build using the
_build/Dockerfile you created, and tags it with an image name that you need to specify when you invoke the build.
Move back into the root directory for your Jekyll site, and build using this command (substituting your project ID for
This will build your site’s Docker image, and upload it to Google Container Registry. If you like, you can view your images by visiting your container registry in the cloud console. You can also view your build results and logs in the console.
The image name you provide as the value of
_IMAGE should be of the form
gcr.io/$MY_PROJECT_ID/$SITE_NAME:$TAG in order to upload to Google Container Registry. In that name,
$MY_PROJECT_ID must be your project ID.
$SITE_NAME should be some identifying name for this image. (We used
mysite in this case.)
$TAG should be a name for this build. (We used
v1 here, but you might consider using a timestamp, git hash, or other system of generating build IDs.)
Deploying to Cloud Run
Now, to deploy to Cloud run, type this command (substituting your project ID for
Unless you have a very large site, this should take only a few seconds. When deployment is done, the command will output your site’s URL. It will look something like
https://mysite-somecode.a.run.app. Open that URL in your web browser to view your site.
If this is a real site, you’ll probably want to point your own domain at it. You can do this in the console. Go to the Cloud Run section and click “Manage custom domains”.
When you have updates, you should repeat the build and run steps above. I recommend using a different
$TAG for each update. This will let you identify each build uniquely, making it easy to roll your site forward and back as needed.
For example, our initial deployment used a tag of
v1. Make some edits to your site (maybe add or edit a post), and test it out locally using
jekyll serve. Then, let’s build
As you work with your site, you’ll probably want to create a rake task or similar script to generate new tags and automate those commands. I use Toys for this purpose, and my
.toys.rb file looks something like this:
When you’re done with this tutorial, if you do not want to continue serving your site, you can delete the project so you do not incur any expenses related to it.
Note that deleting the project will delete all resources related to it, including any VMs, databases, storage, and networking resources. If you are still using some of the project’s resources and do not want to delete the entire project, you can clean up after this tutorial by doing this:
- Go to the Cloud Run console and delete the service you deployed for your site. (It might be called “mysite”.)
- Go to your container registry in the console and delete the images for your site.
Where to go from here
The Cloud Run documentation includes a lot of additional information about deploying and running your site. Of particular interest are:
- How to map a custom domain
- Setting up continuous deployment from Cloud Build and triggering on pushes to GitHub
- Monitoring your site
- Pricing and quotas.
For more information about the runtime environment, or if you want to customize your container further, you should refer to the container runtime contract.
There’s a lot of hype around serverless these days, and not all of it is justified. For me, Cloud Run is the first product I’ve actually been somewhat excited about, because of how it successfully fuses serverless with containers, and because of how well it works for common use cases such as static sites.