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.
To build the Forseti Security website locally:
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
To install Ruby and RubyGems, execute the following:
sudo apt-get install ruby ruby-dev
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
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 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
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/forseti-security/forseti-security.git
user@host:~/forseti-web$ git pull origin forsetisecurity.org-dev
Build the Forseti website:
user@host:~/forseti-web$ bundle install
To launch and run the website locally, run:
user@host:~/forseti-web$ bundle exec jekyll serve