# Contributing Quickstart

Welcome to Daemonless! Whether you're fixing a bug in an existing image or bringing a completely new service to the FreeBSD container ecosystem, this guide will get you set up and submitting your first Pull Request in under 10 minutes.

> [!WARNING]
>
> **Using a coding agent?**
>
> Read the [LLM / AI Contribution Policy](<https://daemonless.io/guides/llm-policy/index.md>) **before** you generate anything: understand what you commit, test it locally, and write your PR description in your own words. If you're porting an image, see [AI-Assisted Porting](<https://daemonless.io/guides/ai-assisted-porting/index.md>).

---

## 1\. Environment Setup

Before you start building, you need to prepare your FreeBSD host.

### Prerequisites

- **FreeBSD Host** (physical machine or VM).
- A GitHub account.

### Installation

Install the required tools, the `dbuild` engine, and optionally the testing dependencies.

```
pkg install sysutils/py-dbuild podman-suite ocijail jq security/trivy devel/py-pyyaml devel/git
# Optional: for screenshot-based visual regression testing
pkg install chromium www/py-selenium graphics/py-scikit-image # (1)!
```

1. **Optional:** Only required if you intend to run screenshot-based visual regression tests locally.

### Clone the Repositories

The Daemonless project is organized into multiple repositories under the `@daemonless` organization. You'll need the main repository for scripts and documentation.

```
git clone https://github.com/daemonless/daemonless
cd daemonless
```

> [!TIP]
>
> **Clone the entire fleet**
>
> To clone all daemonless image repositories at once, you must first install the GitHub CLI (`pkg install gh`), then run:
>
> ```
> gh repo list daemonless --no-archived -L 1000 | awk '{print $1}' | while read repo; do git clone "https://github.com/$repo.git"; done
> ```

### Verify Setup

Ensure everything is configured correctly:

```
dbuild ci-test-env
```

---

## 2\. Your First Contribution

Daemonless uses a standardized toolchain. Choose your path below:

1. **Scaffold the project:** Use `dbuild init` to generate the boilerplate.

   ```
   mkdir myapp && cd myapp
   git init
   dbuild init
   ```
2. **Configure Metadata:** Edit `compose.yaml` to define the `x-daemonless` metadata (title, category, ports, volumes, etc.).
3. **Edit the Containerfiles:** Define how your app installs and runs in `Containerfile` and `Containerfile.pkg`. See [Containerfile Patterns](<https://daemonless.io/guides/development/index.md#containerfile-patterns>).
4. **Fetch Assets & Generate Docs:** Run `dbuild logo` (used in the app grid), `dbuild screenshot` (used on the website to showcase the app), and `dbuild baseline` (used for CIT visual regression tests) to pull down the app's visual assets. Then, run `dbuild generate` to auto-generate the `README.md` and inject labels into the Containerfiles.
5. **Configure testing:** Edit `.daemonless/config.yaml` to define how the image should be tested.

1. **Find the repository:** Each image has its own repository (e.g., `@daemonless/radarr`).
2. **Fork and clone:** Fork the repository on GitHub, then clone it locally.

   ```
   git clone https://github.com/YOUR_USERNAME/radarr
   cd radarr
   ```
3. **Make your changes:** Edit `compose.yaml` (if modifying metadata), the `Containerfile`, or the scripts under `root/daemonless/` (the launcher in `libexec/`, setup in `init.d/`). Always run `dbuild generate` after modifying `compose.yaml`.

---

## 3\. Build & Test Loop

We use **CIT** (Container Integration Testing) to ensure every image works natively on FreeBSD.

Build your image locally:

```
dbuild build
```

Run the automated tests:

```
dbuild test
```

> [!TIP]
>
> **Test Modes**
>
> Tests are defined in `.daemonless/config.yaml`. Most web apps should use `mode: health`. For apps with complex UIs, use `mode: screenshot` to catch visual regressions. See [Quality Gates (CIT)](<https://daemonless.io/guides/dbuild/cit/index.md>) for details.

To manually verify your image, run it with Podman:

```
podman run -d --name test-app -p 8080:8080 localhost/YOUR_IMAGE:build-latest
```

---

## 4\. Submitting Your PR

Before you open a Pull Request, run through this checklist to ensure a smooth review process:

### Pre-Flight Checklist

- [ ] **License Check:** Upstream license verified using the [SPDX identifier](<https://spdx.org/licenses/>). Never guess a license; if none exists, use `NOASSERTION`.
- [ ] **Metadata Sync:** `dbuild generate` has been run to sync `compose.yaml` metadata into `Containerfile`, `Containerfile.pkg`, and `README.md`.
- [ ] **Permissions:** The app runs as `bsd`, not root: on base-exec `/init` drops to it before running `CMD`; on base-rcd each unit's launcher uses `exec dsu bsd ...`.
- [ ] **Testing:** `.daemonless/config.yaml` is configured and `dbuild test` passes locally.
- [ ] **CI Pipeline:** `.github/workflows/` is present and configured (Woodpecker is maintained as a fallback Plan B).
- [ ] **AI policy:** if you used a coding agent, the PR description is in your own words and you can explain every line of the diff — see the [LLM / AI Contribution Policy](<https://daemonless.io/guides/llm-policy/index.md>).

### How to Submit

**For existing images:** Push your branch to your fork and open a Pull Request against the `main` branch of the respective repository. Our CI will automatically run the CIT suite against your changes.

**For new images:** You cannot open a PR until a repository exists in the Daemonless organization! Please hop on our [Discord](<https://discord.gg/Kb9tkhecZT>) and ask us to create a new repository for your image. Once created, you can push your scaffolded project there.

---

## 5\. Golden Rules & Conventions

To keep the fleet consistent, adhere to these core rules:

- **Use `fetch`:** FreeBSD provides `fetch` in the base system. Do not install or use `curl`/`wget` unless absolutely necessary.
- **Clean Caches:** Always clean up after installing packages: `pkg clean -ay && rm -rf /var/cache/pkg/*`.
- **Permissions:** Use `chown -R bsd:bsd /config /app` in your Containerfile.
- **Configuration:** Always use `/config` as the persistent volume mount point.

For the complete list of rules, labels, and architectural details, read the full **[Development Guide](<https://daemonless.io/guides/development/index.md>)**.

---

## Need Help?

Stuck on a build error or have questions about ocijail? Join us on [Discord](<https://discord.gg/Kb9tkhecZT>) — it's the fastest way to get help from the Daemonless community.
