Learn the basics

This guide will help you understand the basic concepts of Lunar and get started with monitoring your engineering practices.

Prerequisites

Before you begin, make sure you have:

1. Installed Lunar following the installation guide

2. Access to your code repositories

3. Basic understanding of your CI/CD pipeline setup

Basic Concepts

Lunar operates on a few key concepts:

1. Components: These are your software projects (services, libraries, repositories)

2. Collectors: These gather information about your components

3. Policies: These define rules and standards for your components

4. Checks: These are the results of policy evaluations

Your First Lunar Setup

1. Populate your Lunar Configuration

Start by creating a lunar-config.yml file in your project root:

hub:
  host: <host>:<port>

domains:
  team1:
    name: My Organization
    description: Main organization domain

components:
  github.com/my-org/my-service:
    owner: [e-mail]
    domain: team1

collectors:
  - name: readme-lines
    runBash: |-
      if [ -f README.md ]; then
        wc -l README.md | lunar collect '.readme.lines' -
        lunar collect '.readme.missing' false
      else
        lunar collect '.readme.missing' true
      fi
    hook:
      type: code

You will need to replace github.com/my-org/my-service with a real repository you want to monitor.

Note

Lunar can also auto-discover components from external systems like GitHub, Backstage, and other sources using catalogers. See the catalogers documentation for details on setting up automated component discovery. For now, this example will focus on manually declared components.

To apply this configuration, run

lunar config apply

You should be able to see the new domain, the new component, and its component JSON being populated in the Lunar UI.

2. Define Your First Policy

Add a policy to check your component:

policies:
  - name: readme
    description: "README.md standards"
    on: ["domain:team1"]
    runPython: |-
      from lunar_policy import Check, Path

      with Check("readme-exists") as check:
          check.assert_false(Path(".readme.missing"), "README.md file is missing")

      with Check("readme-length") as check:
          lines = check.get(".readme.lines")
          check.assert_greater_or_equal(
              lines, 50,
              f'README.md should have at least 50 lines. Current count: {lines}'
          )

Apply the new configuration:

lunar config apply

You should be able to see the new policy, and the checks being populated for this component in the Lunar UI.

See also

1. Learn more about key concepts

2. Explore configuration options

3. Check out the plugin SDKs for advanced usage