import { Callout } from 'fumadocs-ui/components/callout';

Struktur is published as an npm package and runs on Node.js 20 or newer. Install it in your image; there is no standalone binary to download.

Prerequisites [#prerequisites]

* Docker Engine 24 or newer.
* An API key for your LLM provider.

Dockerfile [#dockerfile]

```dockerfile
FROM node:22-trixie-slim

RUN npm install -g @struktur/cli

ENV OPENAI_API_KEY=""
```

PHP application [#php-application]

PHP images do not ship Node, so install it next to the CLI:

```dockerfile
FROM php:8.4-cli-bookworm

# The CLI is a Node program, so the image needs a Node runtime.
RUN apt-get update \
    && apt-get install -y --no-install-recommends nodejs npm \
    && rm -rf /var/lib/apt/lists/* \
    && npm install -g @struktur/cli

# Install PHP dependencies
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-interaction
COPY . .

ENV OPENAI_API_KEY=""
```

`npm install -g` puts the executable in `/usr/local/bin/struktur`. If you install it elsewhere, point the PHP SDK at it with `STRUKTUR_BINARY` or the `binaryPath` constructor argument:

```php
new Client(binaryPath: '/usr/local/bin/struktur');
```

<Callout type="info">
  `@struktur/cli` ships prebuilt native dependencies for Linux x64 and arm64, so the image needs no build toolchain. Native modules such as `sharp` and the PDF parsers are loaded from `node_modules` at runtime, which is why the CLI is installed as a package rather than copied in as a single file.
</Callout>

docker-compose.yml [#docker-composeyml]

```yaml
services:
  app:
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
```

Authentication [#authentication]

Docker containers do not have macOS Keychain. Use environment variables to authenticate. Set one or more of these variables:

| Variable                       | Provider   |
| ------------------------------ | ---------- |
| `OPENAI_API_KEY`               | OpenAI     |
| `ANTHROPIC_API_KEY`            | Anthropic  |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Google     |
| `OPENCODE_API_KEY`             | OpenCode   |
| `OPENROUTER_API_KEY`           | OpenRouter |
| `OLLAMA_BASE_URL`              | Ollama     |

You can also mount a `tokens.json` file for authentication:

```yaml
volumes:
  - ./tokens.json:/root/.config/struktur/tokens.json:ro
```

<Callout type="warn">
  Do not put API keys in your Dockerfile. Use Docker secrets, an `.env` file, or a secrets manager.
</Callout>

Per-command tokens [#per-command-tokens]

Prefix the command with environment variables for per-command token overrides:

```bash
docker run --rm my-app \
  sh -c 'OPENAI_API_KEY=sk-xxx struktur extract --model openai/gpt-4o --input doc.pdf --fields "title"'
```

In the [PHP SDK](/docs/sdk/php), pass tokens as an array. The SDK builds the env prefix automatically:

```php
$result = $client->extract(new ExtractionRequest(
    inputs: [Input::fromPath('./invoice.pdf')],
    schema: $schema,
    model: 'openai/gpt-4o',
    tokens: ['openai' => 'sk-xxx'],
));
```

Set a default model [#set-a-default-model]

```bash
docker run --rm \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  my-app \
  struktur config models use openai/gpt-4o-mini
```

Examples [#examples]

Extract data from a PDF [#extract-data-from-a-pdf]

```bash
docker run --rm \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $(pwd)/documents:/docs:ro \
  my-app \
  struktur extract \
    --input /docs/invoice.pdf \
    --model openai/gpt-4o-mini \
    --fields "invoice_number, date, total, line_items"
```

Parse a PDF into artifacts [#parse-a-pdf-into-artifacts]

```bash
docker run --rm \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $(pwd)/documents:/docs:ro \
  my-app \
  struktur parse --input /docs/report.pdf --output -
```

Building from source [#building-from-source]

```bash
pnpm install
pnpm --filter @struktur/cli build
node packages/cli/dist/cli.js --version
```

The CLI depends on native modules and separate parser files that are resolved from `node_modules` at runtime, so a bundled single-file build cannot replace the installed package.

See also [#see-also]

* [Installation & Setup](/docs/cli/installation) — all environment variables
* [Config](/docs/cli/config) — provider and model management
* [PHP SDK](/docs/sdk/php) — use Struktur from PHP