Run Website Locally

The instructions below are aimed at developers using Linux, particularly Debian or Ubuntu. This page shows you how to install and run the website server locally, so that you can test your documentation changes before merging.


High-Level Overview

To build the Forseti Security website locally:

  1. Install Docker
  2. Install Ruby & RubyGems
  3. Install Website Build Dependencies
  4. Install Bundler
  5. Install Jekyll
  6. Fetch, Build, and Run Forseti Web Code

Step by Step Instructions

Install Docker

sudo apt-get update
sudo apt-get install docker-ce

NOTE: If Docker is not available in the repository, follow the steps here from the Docker website to add Docker to the package index.

NOTE: If the previous command fails even after ensuring that Docker is in the package repository list, you may need to clear your docker lib (rm -rf /var/lib/docker) as well. Doing this will delete all images on disk. Ensure that they are backed up somewhere if you don’t want this to happen.

In order to avoid permission issues later on, add your user to the docker group:

sudo adduser $USER docker

Before continuing, test that Docker is running correctly by doing the following:

docker run hello-world

Install Ruby & RubyGems

To install Ruby and RubyGems, execute the following:

sudo apt-get install ruby ruby-dev

Install Website Build Dependencies

In order to build the website code in the last step, you will need a few Linux dependencies installed.

To add these dependencies, run the following:

sudo apt-get install imagemagick libmagickwand-dev zlib1g-dev

Install Bundler

gem install bundler

You may encounter the following error:

ERROR:  While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /var/lib/gems/2.3.0 directory.

If you do, you can setup a Ruby virtual environment like RVM or rbenv. If you do not want to setup a virtual environment, follow the steps documented here which are listed below:

cd /var/lib
sudo chmod -R a+w gems/

If you get the error again with You don't have write permissions for the /var/lib/bin the solution is listed below:

cd /usr/local/
sudo chmod -R a+w gems/

Install Jekyll

Install Jekyll by executing the following command:

gem install jekyll

If you run into the following error

ERROR: Error installing jekyll:
ERROR: Failed to build gem native extension.
...
mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

the root issue is that Jekyll has dependencies with Ruby on Linux that are not installed by default such as ruby-dev. This should not happen if you installed Ruby per above.

Additional context here.

To install these additional dependencies, you need to execute the following:

sudo apt-get install ruby ruby-dev

With the dependencies now present, try installing Jekyll again:

gem install jekyll

Fetch, Build, and Run Forseti Web Code

Fetch Code

Create a folder for the Forseti website and pull down the code.

mkdir forseti-web
cd forseti-web/
user@host:~/forseti-web$ git init
user@host:~/forseti-web$ git remote add origin https://github.com/GoogleCloudPlatform/forseti-security.git
user@host:~/forseti-web$ git pull origin forsetisecurity.org-dev

Build Website

Build the Forseti website:

user@host:~/forseti-web$ bundle install

Serve the Website locally

Generate the Sphinx docs:

user@host:~/forseti-web$ ./scripts/generate_sphinx_docs.sh "dev"

NOTE: You do not have to run this scrit to get the website running locally.

To launch and run the website locally, run:

user@host:~/forseti-web$ bundle exec jekyll serve