13 Local development - 18F/federalist-jekyll-netlify-cms-guides GitHub Wiki

For local development, you'll need to install Ruby and NodeJS or Docker.

Ruby

  • Ruby is included on Mac, but it needs to be installed on Windows. The included Mac version might need to be upgraded.
  • Check to see if it’s installed and in the path with ruby -v inside the terminal. A version number should be returned if it’s set up correctly.
  • Also run bundler -v to see if Bundler is installed. Bundler is a dependency bundler for Ruby, similar to NPM for NodeJS or Composer for PHP. If not, run gem install bundler.

NodeJS

  • Download NodeJS. The installation includes Node’s package manager (NPM).
  • Check to see if it’s installed and in the path with node -v and npm -v in the terminal. You should see each command return a version number if everything is working properly.
  • If you’re not seeing a version number and you’re on Windows, it’s usually an issue with the PATH system environment variable. You’ll want to make sure the NodeJS and NPM installation directories were added to the PATH. You can follow the steps in the accepted answer here.

There are popular tools for managing multiple versions of Ruby and Node, called RVM and NVM respectively. They are not required for local development and unless you’re going to be working with multiple Jekyll sites or JavaScript projects, it’s fine to forgo using these tools. They also aren’t the most straightforward tools to install and set up if you’re developing on a Windows machine.

With the dependencies out of the way, beginning local development is a snap:

  • git clone [https://github.com/HHS/childcare-gov](https://github.com/HHS/childcare-gov)&& cd childcare-gov
  • npm i && bundle install
  • jekyll serve

Once you initiate the local server with jekyll serve, the site will be available in your web browser at http://localhost:4000 and any changes to local files will automatically rebuild so you can refresh to see the changes. A dockerized version is also available in case you encounter local development issues with the method listed above.

Docker

Using Docker for local development means you’ll trade installing Ruby and NodeJS for installing Docker, but Docker seems to be a slower local development experience overall. To use Docker for local development, once Docker is installed:

  • git clone https://github.com/HHS/childcare-gov && cd childcare-gov
  • docker compose up

This build takes a few minutes to complete but once the server is running, the local site is accessible at https://docs.docker.com/get-docker/. If you’d like to have it accessible on a different port locally, edit docker-compose.yml and change the port value on the left side of the colon for the ports key which is the HOST_PORT, the right side should remain as 4000 since that’s the CONTAINER_PORT.