Quick Start

This guide will:

1. Ensure you have all prerequisites
2. Set up your base Lapis server
3. Set up Graphite and SPA

This guide assumes you are using Ubuntu and using the recommended setup by running the services with docker.

Some general technical onboarding information (software, online courses, etc.) can be found here.

Account access

Before beginning this guide, ensure you have access to the accounts listed in the self-signup info page.

Setup script

intelliHR has a .dotfiles repo designed to automate most of this setup process. If you have your account access sorted, download / clone a copy of the repo into either ~/.dotfiles or ~/dotfiles and follow the instructions in the readme.

Prerequisites

1Password

Make sure that you have access to the intelliHR 1Password account. If you do not have access to this, please email it@intellihr.com.

Set up a SSH key

Generate a key for use when cloning via SSH

ssh-keygen -t ed25519 -C "<first>.<last>@intellihr.com"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub

You will see some output similar to the following

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAmlCEgfePcCM00y08gYokUUjHgl487IHVJynqMdwkUQ john.doe@intellihr.com

Copy all of this text and paste it into the form to add an SSH key to you GitLab account.

Optionally, if you also require access to GitHub you will need to add an SSH key to your GitHub account.

Global Git Config

Configure your installed Git to globally use the same username / email address so you don’t have to configure per repository:

git config --global user.name "<first> <last>"
git config --global user.email "<first>.<last>@intellihr.com"

intelliHR uses a rebase=true pull strategy to avoid issues when submitting merge requests. You can read more about this strategy and why it’s more useful than a simple fast-forward strategy here. Configure your Git to globally use this strategy:

git config --global pull.rebase true

Since all engineers work in the same repositories, there are lots of branches created over time. Because of this, it is highly recommended that you also configure Git to prune dead branches on fetch/pull:

git config --global fetch.prune true

Docker

The intelliHR stack run on top of Docker and Docker Compose. Both of these will be needed to run the application locally during development.

Docker recently released a version of Docker Desktop for Linux. This is not recommended at this point in time due to slowdowns when running the application via Docker Desktop.

Instead it is recommended that the latest version of Docker is installed instead, via the apt repositories.

Once Docker has been installed, you will need to make sure that you can run Docker containers without sudo access. You can follow the guide on the Docker site on how to Manage Docker as a non-root user, or run the following

sudo groupadd docker
sudo usermod -aG docker $USER

You will need to log out and log back in again. Once complete you should be able to run Docker containers without requiring `sudo

docker run hello-world

Docker compose (deprecated)

Docker Compose used to require its own installation, however, the latest versions of the Installing Docker Engine guide will make sure that docker-compose-plugin is installed as part of the process.

Configuring local SSL certificates for HTTPS

When working locally you will be required to work on an HTTPS version of your site, similar to how the site is hosted in production. The standard Lapis containers support hosting an HTTPS version of the site, however, we will need to generate some SSL certificates and mount them into the container, along with the configuration file for it to work.

Follow the instructions in Local SSL Certificates for HTTPS in order to set this up.

GitLab Container Registry

Most of the main intelliHR Docker images are stored within GitLab Container Registries. In order to access these you must authenticate yourself with the Docker daemon.

1. Generate a token with your GitLab profile that has Read registry permissions and copy the token to the clipboard

2. Register your username and token with the Docker daemon

   docker login \
     -u="<gitlab.username>" \
     -p="<gitlab.token>" \
     registry.gitlab.com
   

Quay.io Container Registry (optional)

There are some containers that remain on our Quay.io container registry. You should only need to do this if your team say that it is required, otherwise you can skip this step.

1. Log in to Quay.io

2. Go to Account Settings -> Docker CLI Password -> Generate encrypted password

3. Copy the full login details from the “Docker” tab on the left hand side

4. Register your username and token with the Docker daemon by pasting the command into your terminal

   docker login \
     -u="<quay.username>" \
     -p="<quay.token>" \
     quay.io
   

For UI Components (optional)

These steps will only be needed if you plan on making changes to the ui-components repository. Unless your team tells you that this is needed, you can skip these steps.

Install Node.js 18

curl -fsSL "https://deb.nodesource.com/setup_18.x" | sudo -E bash -
sudo apt update
sudo apt autoremove
sudo apt install -y nodejs

If you have an issue in upgrading node, you can uninstall old NodeJS completely by using the following commands.

sudo apt-get purge nodejs
sudo apt-get autoremove

Install yarn 1.x

curl -sS "https://dl.yarnpkg.com/debian/pubkey.gpg" | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update
sudo apt install yarn

Extras

VSCode users may want to check out Useful VSCode Extensions.

Setting up the Lapis service

This will set up the core Lapis service and legacy Blade/React frontend.

• Create a folder locally to store your code by running

  mkdir ~/Workspace
  

• Inside the new folder we will clone the Lapis repository

  cd ~/Workspace
  git clone git@gitlab.com:intellihr/engineering/lapis.git
  

• Navigate to the lapis folder created by this clone

  cd ~/Workspace/lapis
  

• Copy the example environment file to .env

  cp .env.example .env
  

• Open up the .env file for editing and update the APP_URL setting so that it includes your name before the local part, for example

  APP_URL="http://john.doe.local.internihr.ninja"
  

• Copy the example Docker Compose override file to docker-compose.override.yml

  cp docker-compose.override.yml.example docker-compose.override.yml
  

• In the new docker-compose.override.yml file you will need to configure your local tenant names for the local service

  local:
    networks:
      gateway:
        aliases:
          - master-large-demo.john.doe.local.internihr.ninja
          - master-intellihr.john.doe.local.internihr.ninja
          - qa-intellihr.john.doe.local.internihr.ninja
  
  federation:
    environment:
      - FEDERATION_LAPIS_ENDPOINT=http://master-intellihr.john.doe.local.internihr.ninja/graphql
  
  micro:
    environment:
      - GRAPHITE_LAPIS_ENDPOINT=http://<tenant>.john.doe.local.internihr.ninja
  

NPM Registry Configuration

• Create a .npmrc file in the root lapis directory with the following contents

  @fortawesome:registry=https://npm.fontawesome.com/
  //npm.fontawesome.com/:_authToken=<AUTH_TOKEN_HERE>
  @humanforce:registry=https://npm.pkg.github.com
  //npm.pkg.github.com/:_authToken=<HF_GITHUB_NPM_TOKEN>
  

  • Replace <AUTH_TOKEN_HERE> with the Font Awesome Pro auth token which can be found in 1Password. This npm configutation file will allow you to retrieve the fontawesome-pro package from a private registry

  • Replace <HF_GITHUB_NPM_TOKEN> with a classic access token from github that has the read:packages scope. You will need access to the Humanforce repositories in github. If you need to create a new token, be sure click on the [Configure SSO] button and follow the prompts to authorise they key

• To install the latest packages, and fetch the latest containers, there is a helper script inside the lapis repository

  ./bin/fetch-containers.sh
  

• Start the Lapis application containers. The terminal will start a real-time tail of the logs from the containers listed

  docker compose up local lapis postgres
  

• You should now be able to connect to the application in your browser using the default tenant and your local domain, for example http://master-large-demo.john.doe.local.internihr.ninja

• The local master-large-demo tenant is cloned exactly from the tenant in the dev stack. You can log in using lyanna (the system administrator) details from 1Password

Setting up GraphQL

• GraphQL should be hosted in a container called federation when starting up lapis. Try running

  docker compose up local lapis postgres micro federation
  

• You should see a log message with Federation ready at http://localhost:4001/graphql. You can access this URL to use the GraphQL playground and start sending queries

• To test it works, open the GraphQL playground, setup the HTTP header, and then perform a login auth request and see if graphite is able to contact Lapis

  HTTP Header

  {
    "X-Tenant": "master_large_demo"
  }
  

  GraphQL Request

  mutation {
    auth {
      login(input: {
        username: "lyanna"
        password: "<refer to 1Password>"
      }) {
        accessToken
      }
    }
  }
  

Setting up SPA

This will set up the single page React app using Graphite, giving you the full stack.

• As with Lapis and Graphite, clone the SPA repository into your Workspace folder

  cd ~/Workspace
  git clone git@gitlab.com:intellihr/engineering/spa.git
  

• Copy the example environment file to .env

  cp .env.example .env
  

• Copy the .npmrc file from your Lapis folder into the SPA folder

  cp ~/Workspace/lapis/.npmrc ~/Workspace/spa/.npmrc
  

• Double check that your .npmrc file contains all expected repositories across all repositories (e.g. @fortawesome and @humanforce)

• Start the SPA service. When the service is started, the NPM packages will be automatically installed

  docker compose up local
  

• Once the React build has completed, and service has started, you should be able to access SPA pages when browsing through the intelliHR site. As an example, try visiting the Settings page after logging in as Lyanna

Troubleshooting

401 or 403 errors when building npm/yarn packages

Double check that your .npmrc file contains all expected repositories across all repositories (e.g. @fortawesome and @humanforce)

Network gateway declared as external, but could not be found

Our system requires a docker network called gateway to exist prior to being run. Follow the directions given with the error to make this network.

“ERROR: unauthorized: access to the requested resource is not authorized” when running docker commands

You require access to registry.gitlab.com or quay.io in order to pull docker containers.

Follow the instructions to set up GitLab Container Registry access or Quay.io Container Registry access as required.

“Unable to send lapis request: Tenant could not be determined” when running GraphQL queries

Graphite requires an X-Tenant header or an Authorisation header to be provided when making Lapis requests. Add an X-Tenant header (in the HTTP headers section in GraphQL Playground) with the tenant (usually master_large_demo).

{
  "X-Tenant": "master_large_demo"
}

“request to https://master-large-demo.local.internihr.ninja/api/batch failed, reason: connect ECONNREFUSED” error when running GraphQL queries

Your Graphite GRAPHITE_LAPIS_ENDPOINT env is pointing to https instead of http. Update it to use http instead.

When running docker compose up local: ERROR: for postgres Cannot start service postgres: driver failed programming external connectivity on endpoint lapis_postgres_1 (<SOME_HASH>): Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use

When a local instance of Postgres is configured to boot on startup of your machine (potentially toggled automatically when updating Ubuntu versions), Lapis won’t be able to start the Postgres service and will crash. To fix this first stop the local Postgres server and disable the option to launch it on startup:

sudo service postgresql stop
sudo update-rc.d postgresql disable

When running git clone: Host key verification failed. fatal: Could not read from remote repository

When connecting via the SSH protocol, every host has a key. Clients remember the host key associated with a particular address and refuse other connections. To fix this, add github to the list of known hosts:

ssh-keyscan -t rsa gitlab.com >> ~/.ssh/known_hosts
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts

When attempting to run docker compose --rm yarn on lapis: EACCES: permission denied error

When your user ID is not 1000 you will receive this error. Specifically mkdir /app/node_modules. In order to fix:

• Check your ID by running id <your_username>
• If your ID is not 1000, open a support ticket requesting an Ubuntu ID change