# 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](/install.md)
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

{% stepper %}
{% step %}

### Populate your Lunar configuration

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

{% code title="lunar-config.yml" %}

```yaml
hub:
  host: <host>:<port>

# Use the official Lunar image for running scripts in containers
default_image: earthly/lunar-scripts:1.0.0

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

components:
  github.com/my-org/my-service:
    owner: jane@example.com
    domain: team1

collectors:
  - name: readme-lines
    runBash: |-
      if [ -f ./README.md ]; then
        lunar collect -j \
          "repo.readme_exists" true \
          "repo.readme_num_lines" "$(wc -l < ./README.md)"
      else
        lunar collect -j "repo.readme_exists" false
      fi
    hook:
      type: code
```

{% endcode %}

The `default_image` setting runs all collectors and policies inside Docker containers using the official `earthly/lunar-scripts` image. This image includes Python, Bash, the `lunar` CLI, and the `lunar-policy` package pre-installed. For more details on image configuration, see [Images](/configuration/lunar-config/images.md).

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

{% hint style="info" %}
Lunar can also auto-discover components from external systems like GitHub, Backstage, and other sources using catalogers. See the [catalogers documentation](/configuration/lunar-config/catalogers.md) for details on setting up automated component discovery. For now, this example will focus on manually declared components.
{% endhint %}

Commit this code to a new repository called `lunar`. To apply this configuration, run the following command:

```bash
lunar hub pull -r github://my-org/lunar@main
```

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

{% step %}

### Define your first policy

Add a policy to check your component:

{% code title="lunar-config.yml" %}

```yaml
policies:
  - name: readme
    description: "README.md standards"
    on: ["domain:team1"]
    runPython: |-
      from lunar_policy import Check
      with Check("readme-exists", "Repository should have a README.md file") as c:
        c.assert_true(c.get_value(".repo.readme_exists"), "README.md file not found")
```

{% endcode %}

Since we're using the official `earthly/lunar-scripts` image (via `default_image`), the [Lunar Policy SDK](/plugin-sdks/python-sdk/policy.md) is already pre-installed—no `requirements.txt` needed.

Commit the code, and apply the new configuration:

```bash
lunar hub pull -r github://my-org/lunar@main
```

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

Congratulations! You've just set up your first Lunar collector and policy.
{% endstep %}
{% endstepper %}

## See also

1. Learn more about [key concepts](/docs/key-concepts.md)
2. Explore [configuration options](/configuration/lunar-config.md)
3. Browse [100+ pre-built guardrails](https://earthly.dev/lunar/guardrails/) and [30+ integrations](https://earthly.dev/lunar/integrations/) instead of writing everything from scratch
4. Install [AI skills](/install/skills.md) for Claude Code, Codex, or Cursor to help build collectors and policies


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-lunar.earthly.dev/basics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.