Setup Frigg with Docker

Follow these steps to set up your Frigg repository in GitLab.

Prerequisites:

one or more GitLab groups (with potential subgroups) that you want to start managing through Frigg
access to Avisi’s Frigg Public GitLab project
access to GitLab runners with the ability to run pipelines using Docker containers
access to Frigg images (found within Frigg Public’s container registry)

Set up repository

Create a Group Access Token called “Frigg API Token” with the scope api on the GitLab group you want to manage. Hold onto the token.
Make a new GitLab project called “frigg” under the GitLab group you want to manage with Frigg. (In case you do not want to let Frigg manage itself as well, you can place Frigg outside this group.)
Go to your Frigg project > Settings > CI/CD and add the following environment variables:

DOCKER_AUTH_CONFIG: the Docker authentication JSON which you will have received from the Frigg team in order to access the image registry.
GITLAB_BASE_GROUP: the GitLab short url of the base group you want to display your auth matrix for. E.g. foo/bar.
GITLAB_FRIGG_PROJECT: the short GitLab ID of your Frigg project. E.g. 12345678.
GITLAB_TOKEN: the Group Access Token as created in step 1. Ensure to mark it as masked.
GITLAB_URL: the URL of your GitLab instance. If using GitLab cloud it should be https://gitlab.com.
RESOURCES_PATH: the absolute path to the folder holding your resource files within your Frigg pipeline runner. This guide assumes /builds/[group_path]/frigg/resources.

The following environment variables are optional:

REQUEST_TIMEOUT: Global request timeout in milliseconds, defaults to 20 000.
RATE_LIMIT: Request rate limit in RPS (Requests Per Seconds), defaults to 300.
QUERY_TIMEOUT: Timeout for bundled queries in milliseconds, defaults to 300 000.
STATIC_PAGE_TIMEOUT: Timeout for the generation of the Gitlab pages in seconds, defaults to 60.

Note: By decreasing the rate limit, the query timeout is more likely to trigger, in other words, decreasing this may require to increase the query timeout.

Local environment

Before pushing any files to your Frigg project and attempting to apply any resources, let’s set up the local environment first.

Make sure you download the Makefile from the Frigg Public repository, because this greatly simplifies what commands need to be manually run. The given Makefile looks as followed:

# A Makefile that simplifies local usage of Frigg, simply copy and paste this into the repo that you want to use for your Frigg configuration.
# Specify which version of Frigg's docker image you want to use		e.g. 1.0.0
frigg_tag = latest
# Path to Frigg Public registry		e.g. registry.gitlab.com/organization/group/project
frigg_registry = registry.gitlab.com/avisi/team-labs/frigg/frigg-public
# path to your local Frigg repo, if the pwd command doesn't work, please add the absolute path manually		e.g. home/git/Frigg
frigg_path = $(shell pwd)
 
# Initializes your repository by creating an .env file, resource folder, README and .gitlab-ci
frigg-init:
	docker run -v $(frigg_path):/app/initialize $(frigg_registry)/frigg-backend:$(frigg_tag) ./initialize_frigg.sh
 
# Specify which groups in your GitLab instance you wish to export		e.g. company/path/group,company/path/other/group
gitlab_groups = <group_path1,group_path2...>
 
# Exports the desired GitLab groups and creates resource files for the underlying Groups and Projects
frigg-export:
	docker run -v $(frigg_path)/resources:/app/resources --env-file .env $(frigg_registry)/frigg-backend:$(frigg_tag) yarn start --export-gitlab=$(gitlab_groups)
 
# Validate the YAML-files within te resource folder
frigg-validate:
	docker run -v $(frigg_path)/resources:/app/resources --env-file .env $(frigg_registry)/frigg-backend:$(frigg_tag) yarn start --validate
 
# Dry run apply the resources to check for changes
frigg-dry-run:
	docker run -v $(frigg_path)/resources:/app/resources --env-file .env $(frigg_registry)/frigg-backend:$(frigg_tag) yarn start --apply
 
# Dry run apply the resources to check for changes
frigg-apply:
	docker run -v $(frigg_path)/resources:/app/resources --env-file .env $(frigg_registry)/frigg-backend:$(frigg_tag) yarn start --apply --dry-run=false

Initialize Frigg Repository

The Frigg Docker image has the ability to do the initial setup of your repository, using a script within the container. To do this, do the following:

Ensure you have access to the Frigg Docker images through the Frigg Public registry (follow this GitLab guide on how to login to GitLab registries)
Create a local directory name Frigg at the desired location of your repository
Move the given Makefile into the Frigg directory
Make sure you set the frigg_tag variable within the Makefile to the desired Frigg version, e.g. latest
Run the command make frigg-init

Now you should have the necessary files in order to start using Frigg. If you are unable to access the Docker image, you might lack the correct authentication, for this, contact the Frigg support team.

Project Structure

The structure of the Frigg repository will be as followed:

/resources the folder which holds the resource files, which is the YAML representation of your GitLab projects
.env contains the required environment variables, the .env-file will be mounted to the Frigg container when running Frigg locally
.gitlab-ci.yml contains CI/CD pipelines for applying Frigg resources. More about this file can be found in the section Setup gitlab-ci.yml
Makefile contains pre-written commands that help with running Frigg locally in Docker

When you initialize a repository using Frigg, these files/folders (except for the Makefile) will automatically be added to the repository. Note that you might need to rename some of them and add them to your .gitignore (such as your .env file)

Local .env

The following variables need to be set within the .env file:

RESOURCES_PATH
GITLAB_URL
GITLAB_FRIGG_PROJECT
GITLAB_TOKEN

RESOURCES_PATH needs to point towards the location of the resource folder being mounted to the local Frigg container. This should be the path within the container. When using the Makefile, this will be ./resources

The rest should correspond to the CI/CD variables in Frigg’s GitLab project.

Export GitLab

Open your terminal in the root of your Frigg project.
Set the variable gitlab_groups with the GitLab groups you want to run an export of. The group paths should be the short GitLab URL, e.g. foo/bar.
Run the command make frigg-export

If all steps run successfully, continue to the next step.

Adjust your defaults

Resources will leave out any configuration that matches the desired default configuration. Open /resource/defaults.yaml. Adjust the default configuration values to your desire. Make sure to re-run your exports to take the new defaults into account.

Dry-run apply

Let’s execute a local dry-run of applying the resource files once you’re content with the files exported to /resources in the previous steps:

Open your terminal in the root of your Frigg project.
Run the command make frigg-dry-run
Observe the change list and resolve any validation errors printed to the console

The change list could contain only minimal changes, especially in case you haven’t adjusted any configuration after exporting resource files.

Finalising setup

To ensure Frigg can succesfully apply resource files, let’s run an actual apply locally before pushing to the repository:

Open your terminal in the root of your Frigg project.
Run the command make frigg-apply
Resolve any issues if they occur
Push Frigg to your Frigg repository on GitLab

This concludes the basic set up.

Setup gitlab-ci.yml

Underneath you will find the gitlab-ci.yml file that gets created during the initialization of your repository. A couple variables need to be set in order to successfully use it:

FRIGG_REGISTRY: registry to pull the Frigg image from. E.g. registry.gitlab.com/path/to/project
FRIGG_BACKEND_VERSION: version of the Frigg backend you wish to use. E.g. 1.0.0
FRIGG_PAGES_VERSION: version of Frigg pages generator you wish to use. E.g. 1.0.0

Using the version latest, as with most Docker images, will simply always default to the latest release.

variables:
    FRIGG_REGISTRY: [link to registry]
    FRIGG_BACKEND_VERSION: latest
    FRIGG_PAGES_VERSION: latest
 
stages:
    - validate
    - deploy
    - pages
 
dry-run:
    stage: validate
    image:
        name: $FRIGG_REGISTRY/frigg-backend:$FRIGG_BACKEND_VERSION
        entrypoint: ['']
    before_script:
        - cd /app
    script:
        - yarn start --merge-request-comment=$CI_MERGE_REQUEST_IID
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
        - if: $CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
deploy:
    stage: deploy
    image:
        name: $FRIGG_REGISTRY/frigg-backend:$FRIGG_BACKEND_VERSION
        entrypoint: ['']
    before_script:
        - |
            if [ $CI_MERGE_REQUEST_APPROVED ]; then \
              echo "Merge request was approved"; \
            elif [ "$CI_PIPELINE_SOURCE" = "schedule" ]; then \
              echo "Running scheduled pipeline"; \
            else \
              echo "Merge request must be approved before you are able to run this step" && exit 1; \
            fi
        - cd /app
    script:
        - yarn start --apply --dry-run=false
    after_script:
        - |
            if [ $CI_JOB_STATUS == 'success' ]; then
              curl -i --request PUT \
                --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
                --header "Content-Type: application/json" \
                --data "{\"squash\":true, \"should_remove_source_branch\":true, \"merge_when_pipeline_succeeds\":true}" \
                "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/merge"
            fi
    needs:
        - dry-run
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
          when: manual
        - if: $CI_PIPELINE_SOURCE == "schedule" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
 
pages:
    stage: pages
    image:
        name: $FRIGG_REGISTRY/frigg-pages:$FRIGG_PAGES_VERSION
        entrypoint: ['']
    script:
        - cd /app
        - yarn build
        - mkdir /builds/$CI_PROJECT_PATH/public
        - mv ./out/* /builds/$CI_PROJECT_PATH/public
    artifacts:
        paths:
            - public
    needs:
        - deploy
    rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
        - if: $CI_PIPELINE_SOURCE == "schedule"
          when: never

Scheduled Pipeline

Some people may accidentally change configuration outside of Frigg. To prevent a drifting discrepancy between your resource files and the actual configuration of your resources, let’s set up a scheduled pipeline which runs Frigg’s apply periodically:

Go to your Frigg’s GitLab project > Build > Pipeline schedules.
Create a new schedule with your default branch as target, and set it to active.

How Frigg Works Pre Docker (deprecated)