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

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

Dockerfile

FROM node:22-trixie-slim

RUN npm install -g @struktur/cli

ENV OPENAI_API_KEY=""

PHP application

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

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:

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

@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.

docker-compose.yml

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

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:

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

Do not put API keys in your Dockerfile. Use Docker secrets, an .env file, or a secrets manager.

Per-command tokens

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

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, pass tokens as an array. The SDK builds the env prefix automatically:

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

Set a default model

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

Examples

Extract data from a PDF

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

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

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.

Docker