Deploying locally

After you have forked our repository, cloned it to your local machine and done some changes, you'll surely want to see the results of your work. To do so, you'll have to deploy the website locally on your machine. This can be done as follows:

Option 1: Manual Installation

Tip

Getting Ruby up and running on Windows can be quite a challenge. You're likely better off using Docker (see below for instructions) to deploy the website if you're developing on Windows.

1. Install a full Ruby development environment as described in the official Jekyll guide.
2. Install the Jekyll and Bundler gems, if you haven't done so in the previous step:

gem install jekyll bundler

3. In your working directory (this is where you cloned the website to), install the other dependencies of the gemfile:

bundle install

4. Then you can deploy the Jekyll site locally:

bundle exec jekyll serve

which outputs:

> Configuration file: /Users/octocat/my-site/_config.yml
>            Source: /Users/octocat/my-site
>       Destination: /Users/octocat/my-site/_site
> Incremental build: disabled. Enable with --incremental
>      Generating...
>                    done in 0.309 seconds.
> Auto-regeneration: enabled for '/Users/octocat/my-site'
> Configuration file: /Users/octocat/my-site/_config.yml
>    Server address: http://127.0.0.1:4000/
>  Server running... press ctrl-c to stop.

Note

If you want to display scheduled sites as well, add a --future parameter at the end: bundle exec jekyll serve --future. To enable other devices in your local network to connect to the site as well, add a --host 0.0.0.0 parameter.

The local site can the be viewed at http://localhost:4000/. It is automatically rebuilt after modifying a file.

Option 2: Use Docker

1. Install Docker Desktop on Windows or macOS. Alternatively you can install Docker directly on Linux.
2. Start the docker daemon by starting Docker Desktop (on Windows or macOS) or via the CLI (on Linux).
3. Open a terminal in your working directory (this is where you cloned the website to) and use docker compose up to start your local server.

Warning

To prevent performance issues on Windows when using the WSL 2 engine in Docker Desktop, make sure that your website files are located on a Linux subsystem (which can be accessed in the explorer via the path \\wsl$) and you start Docker via the corresponding WSL shell (the default one can be started with the wsl command in a PowerShell or Windows Command Prompt).

The local site can the be viewed at http://localhost:4000/ (even though the console points to http://0.0.0.0:4000/ as the server address). It is automatically rebuilt after modifying a file.

For future runs, you can also use the Docker Desktop app (on Windows or macOS) to start the website.

Note

If your Docker image becomes outdated after Jekyll or Gemfile updates which cause the build to fail, you can rebuild the image via docker compose up --build.