How to Set Up a Dockerized Jekyll Site in Visual Studio Code with Dev Containers

If you’re developing a static site using Jekyll and want a streamlined setup, using Docker along with Visual Studio Code’s devcontainers feature is an excellent choice. Docker allows you to encapsulate your development environment, and Visual Studio Code offers great tools for working within containers.

In this guide, we will go through setting up a Jekyll site in a Docker container and integrating it with Visual Studio Code using devcontainer.json. This setup ensures consistency across development environments and makes it easy to share or deploy your site.

What You’ll Need

• Docker installed on your machine
• Visual Studio Code with the Dev Containers extension
• Basic knowledge of Docker and Jekyll

Step 1: Understanding the Dockerfile

First, let’s break down the provided Dockerfile, which is the foundation for your Jekyll container.

# Create a Jekyll container from a Ruby Alpine image

# At a minimum, use Ruby 3.0 or later
FROM ruby:3.0-alpine3.16

# Add Jekyll dependencies to Alpine
RUN apk update
RUN apk add --no-cache build-base gcc cmake git

# Update the Ruby bundler and install Jekyll
RUN gem update bundler && gem install bundler jekyll

What the Dockerfile Does:

• Base Image:
  The image ruby:3.0-alpine3.16 is a lightweight Ruby image running on Alpine Linux. This keeps the Docker image small and efficient, which is ideal for development.

• Installing Dependencies:
  We install the basic packages required to build Jekyll, including compilers, build tools, and Git (apk add --no-cache build-base gcc cmake git). These tools help install any additional Ruby gems with native extensions.

• Installing Jekyll:
  We update Ruby’s bundler gem and install Jekyll with the command:
  RUN gem update bundler && gem install bundler jekyll. This prepares the container to run Jekyll commands like jekyll new, jekyll build, or jekyll serve.

Step 2: Configuring Visual Studio Code with devcontainer.json

The devcontainer.json file configures Visual Studio Code to work with Docker containers. It defines how VS Code interacts with the container and customizes the development environment inside the container.

Here’s the devcontainer.json you provided:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
{
	"name": "Existing Dockerfile",
	"build": {
		// Sets the run context to one level up instead of the .devcontainer folder.
		"context": "..",
		// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
		"dockerfile": "../dockerfile"
	}

	// Features to add to the dev container. More info: https://containers.dev/features.
	// "features": {},

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	// "forwardPorts": [],

	// Uncomment the next line to run commands after the container is created.
	// "postCreateCommand": "cat /etc/os-release",

	// Configure tool-specific properties.
	// "customizations": {},

	// Uncomment to connect as an existing user other than the container default. More info: https://aka.ms/dev-containers-non-root.
	// "remoteUser": "devcontainer"
}

What This devcontainer.json Does:

• name: Names the development container as “Existing Dockerfile”, which will appear in VS Code when the dev container is running.

• build.context: The context is set to .., meaning it looks one level above the .devcontainer folder for the context when building the Docker container. This is useful if your Dockerfile is stored outside the .devcontainer directory.

• dockerfile: Points to the Dockerfile in the parent directory with "../dockerfile". If your Dockerfile has a different name or is located elsewhere, update this path accordingly.

• forwardPorts: If you want to forward specific ports (such as for serving your Jekyll site), you can define them here. Uncomment this section to expose ports, for example:

  "forwardPorts": [4000]
  

  This would make the Jekyll development server available on localhost:4000.

• postCreateCommand: This is a placeholder command that runs after the container is created. You can add any initial commands here, like installing additional tools or verifying the setup.

• remoteUser: If you want to connect as a specific user other than the default, you can specify that here.

Step 3: Opening the Folder in a Container

Once your Dockerfile and devcontainer.json are configured, you need to build and run the development container inside Visual Studio Code.

1. Press CTRL + SHIFT + P to open the Command Palette.
2. Type and select Dev Containers: Open Folder in Container….
3. Choose your project folder.

This will initiate the build and launch the Docker container, setting up your development environment inside the container.

Step 4: Running Jekyll in the Container

Once the folder is opened in the remote Container, follow these steps to initialize a Jekyll site inside the container.

1. Create a New Jekyll Site

Open the terminal inside Visual Studio Code’s dev container and run the following command:

jekyll new maheshTestBlog

This creates a new Jekyll site in the maheshTestBlog folder with the default directory structure and sample content.

2. Navigate to the Site Directory

Now, move into the newly created site folder:

cd maheshTestBlog

This command changes the working directory to maheshTestBlog, where you can start editing the content of your Jekyll site.

3. Serve the Jekyll Site Locally

To run the Jekyll development server, execute this command:

bundle exec jekyll serve

The jekyll serve command starts a local development server that watches for changes to your files. You can access the site at http://localhost:4000 in your browser. Any changes you make to the site will automatically trigger a rebuild.

Step 4: Benefits of Using Docker and Dev Containers

• Consistency: Since Docker containers isolate the environment, you can ensure that your Jekyll site runs the same way on every machine, regardless of the host system’s configuration.

• Easy Setup: The Dockerfile and devcontainer.json simplify the process of setting up the environment. You don’t need to manually install Ruby, Jekyll, or any dependencies on your local machine. Everything runs inside the container.

• Portability: Once you have your dev container configured, you can easily share the project with other team members. They only need to clone the repo, open it in VS Code, and the container will spin up with all the tools installed.

• Integrated Development: VS Code’s devcontainer extension integrates seamlessly with Docker, giving you features like terminal access, debugging, and extension support all inside the container.

Conclusion

With Docker and Visual Studio Code’s devcontainers, you can easily create a consistent and isolated environment for Jekyll development. By following the steps outlined in this guide, you’ve learned how to configure a Docker container with Jekyll, set up your development environment with devcontainer.json, and run the Jekyll development server.

This setup streamlines the development process and ensures that your Jekyll site is portable, consistent, and easy to manage across different environments.

Now, you’re ready to focus on building your Jekyll site without worrying about dependencies or configuration issues!

---

Additional Resources

• Jekyll Documentation
• Docker Official Documentation
• VS Code Development Containers

---

This blog post provides a comprehensive guide to setting up and running a Dockerized Jekyll site in Visual Studio Code using devcontainer.json. Let me know if you’d like to tweak any part!