---
title: "Configure the Java SDK"
description: "YAML, environment overrides, HTTP and AMQP settings, validation and configuration precedence."
category: "Java SDK"
---

Keep connection and worker settings in one file. Business stages do not select transports or construct API clients.

## Start with one YAML file

Create `pipelogiq.yml` in the application's working directory:

```yaml
pipelogiq:
  api-url: ${PIPELOGIQ_API_URL:http://localhost:8081}
  api-key: ${PIPELOGIQ_API_KEY}
  worker-name: orders-java
  environment: development
  transport: http
  max-concurrency: 4
```

Export `PIPELOGIQ_API_KEY` before starting the process. It belongs to a Pipelogiq application; workers and producers using that key operate in the same application. A worker name identifies a worker, not a separate routing or authorization boundary.

```java
Pipelogiq.worker().config("pipelogiq.yml")
    .stages(ValidateOrder.class, RecordOrder.class).run();
```

A producer uses the same configuration:

```java
try (var client = Pipelogiq.connect("pipelogiq.yml")) {
  var pipeline = client.pipelines().get(123);
  System.out.println(pipeline.status());
}
```

These fragments use the classes and imports from [getting started](/docs/java/getting-started). Replace `123` with an existing pipeline ID.

## Precedence and locations

Standalone precedence is **defaults → YAML → `PIPELOGIQ_*` environment variables**. Environment overrides are applied before placeholder resolution. `${NAME}` requires a value; `${NAME:fallback}` supplies a fallback.

`config("pipelogiq.yml")` resolves a filesystem path relative to the working directory. Use an absolute path for a service with a different working directory, or `config("classpath:pipelogiq.yml")` for a packaged resource. Configuration is loaded once; editing the file does not reload a running worker.

Omit `.config(...)` on the worker builder to use environment variables and defaults. Programmatic loading is available through `PipelogiqConfig.load(...)` and `PipelogiqConfig.fromEnvironment()`.

The standalone YAML loader rejects unknown settings, duplicate keys, unresolved placeholders and invalid values before connecting. The document must have one `pipelogiq` root mapping. [Spring Boot](/docs/java/spring-boot) uses Spring's configuration sources and binding instead of the standalone loader.

## Supported settings

All YAML names below are relative to `pipelogiq`.

| YAML setting | Standalone environment variable | Default / rule |
| --- | --- | --- |
| `api-url` | `PIPELOGIQ_API_URL` | `http://localhost:8081`; absolute HTTP(S) URL without credentials, query or fragment |
| `api-key` | `PIPELOGIQ_API_KEY` | Required, nonblank |
| `worker-name` | `PIPELOGIQ_WORKER_NAME` | `java-worker` |
| `environment` | `PIPELOGIQ_ENVIRONMENT` | `prod` |
| `transport` | `PIPELOGIQ_TRANSPORT` | `http`; `http` or `amqp` |
| `max-concurrency` | `PIPELOGIQ_MAX_CONCURRENCY` | `4`; positive integer |
| `api-timeout` | `PIPELOGIQ_API_TIMEOUT` | `30s`; positive |
| `startup-timeout` | `PIPELOGIQ_STARTUP_TIMEOUT` | `30s`; positive |
| `drain-grace-period` | `PIPELOGIQ_DRAIN_GRACE_PERIOD` | `30s`; zero or positive |
| `heartbeat-interval` | `PIPELOGIQ_HEARTBEAT_INTERVAL` | `5s`; positive |
| `lease-renew-interval` | `PIPELOGIQ_LEASE_RENEW_INTERVAL` | `5s`; positive |
| `amqp.url` | `PIPELOGIQ_RABBITMQ_URL` | No override; use broker settings returned by the server |

Durations accept integers with `ms`, `s`, `m` or `h`, or ISO-8601 such as `PT30S`. Use `250ms`, `30s` or `2m`, rather than a bare number. Stage execution timeouts and schedule intervals are separate settings on stages and schedules.

## Switch to AMQP

Change the YAML value or override it in the process environment:

```sh
export PIPELOGIQ_TRANSPORT=amqp
```

The SDK still contacts the API to bootstrap and authenticate, then uses the server-supplied RabbitMQ settings. The same dependency, worker entry point and business stages apply.

If the server advertises a broker address this worker cannot reach, set a deployment-specific override:

```sh
export PIPELOGIQ_RABBITMQ_URL='amqp://user:password@reachable-broker:5672/vhost'
```

Keep this value in deployment secret configuration. No override is needed merely to select AMQP. AMQP does not enable automatic HTTP fallback.

## Separate three time limits

| Limit | What it bounds |
| --- | --- |
| `startup-timeout` | Waiting for worker readiness during startup |
| `api-timeout` | An SDK request to the Pipelogiq API |
| `StageOptions.timeout(Duration)` | A stage execution attempt |

`pipelines().waitForCompletion(id, timeout)` has another, local observation deadline. Reaching it does not cancel the durable pipeline. See [workflow management](/docs/java/workflows#observe-and-cancel-a-pipeline).

## Advanced and Spring-only settings

The standalone YAML schema includes only the settings above. Low-level `PipelogiqOptions` exposes worker metadata, capabilities and other integration controls; those names are not additional YAML properties.

Spring adds `pipelogiq.auto-startup`, default `true`. Set it to `false` when a test or host manages startup explicitly. Spring environment binding follows Spring's rules; explicit placeholders in `application.yml` are a clear way to use the environment names from the standalone examples.