> ## Documentation Index
> Fetch the complete documentation index at: https://cloud.laravel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Configuration

> Install additional software into your application's build image.

## Introduction

Private Cloud customers may install additional software, known as add-ons, into their application's build image beyond Laravel Cloud's supported PHP extensions. Add-ons are useful when your application depends on a PHP extension or other system-level software, such as media processing libraries or monitoring agents, that is not included in the default build image.

<Note>
  Build add-ons must be enabled for your organization by Laravel. If you do not see the "Build configuration" section in your environment's settings, [contact support](/docs/support) to request access.
</Note>

## Managing add-ons

Add-ons are configured per environment. The add-ons available to your organization are determined by Laravel and shown in the "Add-ons" selector.

<Steps>
  <Step title="Open the environment's settings">
    Navigate to "Environment > Settings > General" and find the "Build configuration" section.
  </Step>

  <Step title="Select your add-ons">
    Open the "Add-ons" selector and choose the add-ons your application needs. The available options are scoped to your organization.
  </Step>

  <Step title="Save and redeploy">
    Save your changes and trigger a new deployment. Like PHP version and extension changes, add-ons are baked into a freshly built image, so changes only take effect after the environment is redeployed.
  </Step>
</Steps>

The first deployment that includes a new add-on may take longer than usual while Laravel Cloud builds and caches the updated build image. Subsequent deployments will use the cached image.

Once deployed, you may confirm a PHP extension add-on is loaded by running `php -m` from the environment's "Commands" tab.

## Available add-ons

The following add-ons are currently available:

* Datadog
* FFmpeg
* Kafka
* Puppeteer
* wkhtmltopdf

<Note>
  Additional add-ons are available on request. [Contact us](/docs/support) if your application requires software that is not listed above.
</Note>

## Configuring Datadog

Once the Datadog add-on is enabled for your environment, you must configure it before your application will send traces to Datadog. You have two options:

* Send traces to a remote Datadog trace agent that you host and manage yourself.
* Run a local Datadog trace agent inside each of your application's instances.

Create the configuration files using your environment's build commands. If you run a local agent, also configure it as a background process. After changing your configuration, redeploy the environment for the changes to take effect.

<Note>
  The local trace agent does not currently work with [Managed Queues](/docs/queues). If your environment uses Managed Queues, send traces to a remote agent instead.
</Note>

### Sending traces to a remote agent

Datadog's trace agent may run on infrastructure that you host outside of Laravel Cloud. Laravel Cloud connects to it from stable egress IP addresses, so you may restrict access to the agent using IP allowlists. For Private Cloud environments, use the dedicated egress IP addresses Laravel provided during onboarding, rather than the addresses [documented for Laravel Cloud's public platform](/docs/network#ip-addresses).

PHP loads its Datadog configuration when the process starts, which is best handled through a `php.ini` file. Add the following to your build commands, updating `datadog.trace.agent_url` with the protocol, hostname, and port of your remote agent:

```bash theme={null}
cat > /usr/local/etc/php/conf.d/99-datadog.ini <<'EOF'
datadog.trace.agent_url = https://your-hostname.tld:8126
datadog.trace.agent_connect_timeout = 2000
datadog.trace.agent_timeout = 5000
datadog.service = foo-bar-api
datadog.env = staging
datadog.trace.sample_rate = 1.0
datadog.trace.enabled = On
EOF
```

### Running a local trace agent

Alternatively, you may run the trace agent locally within each application instance. This approach requires three steps: configuring PHP, configuring the trace agent, and running the agent as a background process.

<Steps>
  <Step title="Configure PHP">
    Add a `php.ini` file through your build commands, just as you would for a remote agent. Point `datadog.trace.agent_url` at `localhost`, or remove the setting entirely to use the default:

    ```bash theme={null}
    cat > /usr/local/etc/php/conf.d/99-datadog.ini <<'EOF'
    datadog.trace.agent_url = http://localhost:8126
    datadog.trace.agent_connect_timeout = 2000
    datadog.trace.agent_timeout = 5000
    datadog.service = foo-bar-api
    datadog.env = staging
    datadog.trace.sample_rate = 1.0
    datadog.trace.enabled = On
    EOF
    ```
  </Step>

  <Step title="Configure the trace agent">
    Add your Datadog API key to the environment as a custom environment variable or linked secret, such as `DD_API_KEY`. Then update your build commands to write the trace agent's configuration file:

    ```bash theme={null}
    cat > /opt/datadog-agent/etc/datadog.yaml <<'EOF'
    log_level: "warn"
    remote_configuration:
      enabled: false
    EOF

    echo "api_key: $DD_API_KEY" >> /opt/datadog-agent/etc/datadog.yaml
    ```

    Adjust the variable name if you used something other than `DD_API_KEY`.
  </Step>

  <Step title="Run the trace agent">
    On each App or Worker compute cluster that runs your application, configure a custom background process with the `datadog-trace-agent` command.
  </Step>
</Steps>

### Adding further configuration

You may add any additional Datadog settings to either file: the `99-datadog.ini` file for PHP configuration and the `datadog.yaml` file for the trace agent. To see the PHP options available for the `.ini` file, run `php --info | grep datadog` from the environment's "Commands" tab. To find environment variables that help identify your application within Datadog, run `printenv | grep LARAVEL_CLOUD`.

<Tip>
  If you would prefer application monitoring built for Laravel without managing agents or external configuration, take a look at [Laravel Nightwatch](https://laravel.com/nightwatch).
</Tip>