Configure AI Smart Redact

AI Smart Redact runs as three services: Manager, Worker, and Orchestrator. This guide covers operational tasks for configuring them, including encryption-key generation, key rotation, file storage backends, and GPU deployment.

For the complete settings catalog per service, refer to:

Apply configuration changes

Each service is configured through environment variables on its Docker container, using the Section__Field (double underscore) naming convention. For example:

Encryption__EncryptionKey=<ENCRYPTION_KEY>
Database__DatabaseType=PostgreSql

Settings are read once at container startup, so changing a variable requires recreating the container. The encryption key is the only setting that hot-reloads (refer to Key rotation).

The procedures below show settings in appsettings.json form for clarity; the equivalent environment-variable form works the same way. For the full naming convention, refer to Configuration reference > Environment variables.

Mount a custom appsettings.json

As an alternative to environment variables, mount your own appsettings.json into the container at /app/appsettings.json:

services:
  smart-redact-manager:
    volumes:
      - ./manager-appsettings.json:/app/appsettings.json:ro

Mounting the file is what enables hot-reload of the encryption key (refer to Key rotation). All other settings still require recreating the container.

Tune chunk size for performance

Setting used (Worker): Inference.MaxChunkSize.

The chunk size affects the trade-off between detection accuracy and processing speed:

MaxChunkSize	Use case	Trade-off
384-512	High accuracy	Maximum context, slower processing
256	Balanced (default)	Good accuracy and speed
128-256	High throughput	Faster processing, less context per chunk

GPU deployment

A separate Docker Compose file is provided for GPU deployments. It uses a GPU-specific Dockerfile and reserves NVIDIA GPU devices:

Use the GPU variant from the samples repository:

cd smart-redact-samples/docker-compose/gpu
cp .env.example .env
# Fill in your license key and secrets
docker compose up -d

The GPU Compose file uses the -cuda Worker image (pdftoolsag/smart-redact-worker:latest-cuda) with NVIDIA device reservations. The NVIDIA Container Toolkit must be installed on the host.

For image variants, throughput trade-offs, and inference tuning, refer to Scale > Vertical scaling.

Produce an encryption key

Setting used (Manager + Worker): Encryption.EncryptionKey. Generate the value with one of the commands below.

The encryption key must be exactly 32 bytes (256 bits), Base64-encoded. Both the Manager and Worker must use the same key.

# Using OpenSSL (recommended)
openssl rand -base64 32

# Using Python
python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"

warning

Store the encryption key in a secret manager for production deployments. Don’t commit it to appsettings.json in a shared repository.

How encryption works

The system uses a two-tier encryption model for GDPR-compliant crypto-erasure:

KEK (Key Encryption Key): Stored in configuration. Encrypts per-file DEKs in tokens.
DEK (Data Encryption Key): Per-file random key, encrypted in a client-held token.

Each file (uploaded PDF, output FDF, redacted PDF) has its own unique DEK token. Discarding a token makes that specific file cryptographically inaccessible (crypto-erasure).

Key rotation

Rotating the KEK invalidates all existing DEK tokens, because tokens encrypted with the old KEK can’t be decrypted with the new one. The KEK is the only setting that supports hot-reload, so you can rotate it without restarting the service. However, you still need to drain in-flight work first to avoid stranding files. To rotate safely:

Stop accepting new jobs.
Wait for in-flight jobs to complete (tokens expire based on DekTokenTtlMinutes).
Verify the storage is empty (all files deleted).
Update the encryption key. The service picks up the new key automatically.
Resume accepting jobs.

All other configuration settings are read once at startup. To change them, recreate the container.

AWS S3 file storage

Settings used (Manager + Worker): FileStorage.FileStorageType, FileStorage.ConnectionString.

Store files in an S3 bucket instead of the local file system. Configure both the Manager and Worker:

{
  "FileStorage": {
    "FileStorageType": "AwsS3",
    "ConnectionString": "my-bucket-name;eu-west-1"
  }
}

The connection string format is bucket-name;region. The service uses the AWS default credential chain (SSO, IAM roles, environment variables).

Before starting the services, authenticate with AWS:

aws sso login
aws sts get-caller-identity

The IAM role or user must have s3:GetObject, s3:PutObject, s3:DeleteObject, and s3:ListBucket permissions on the bucket.

MinIO file storage

Settings used (Manager + Worker): FileStorage.FileStorageType, FileStorage.ConnectionString.

Store files in a self-hosted MinIO instance (S3-compatible). Configure both the Manager and Worker:

{
  "FileStorage": {
    "FileStorageType": "MinIO",
    "ConnectionString": "minio.s3://keyId=<MINIO_ACCESS_KEY>;key=<MINIO_SECRET_KEY>;bucket=<BUCKET_NAME>;serviceUrl=<MINIO_URL>"
  }
}

Replace the following:

<BUCKET_NAME>: The name of the MinIO bucket that holds AI Smart Redact files.
<MINIO_URL>: The MinIO server URL, including scheme and port. For example: http://minio:9000.
<MINIO_ACCESS_KEY>: The MinIO access key.
<MINIO_SECRET_KEY>: The MinIO secret key.

You can also use the aws.s3:// prefix with a serviceUrl= parameter, which is automatically converted to the MinIO format.

Docker Compose reference

These are the key environment variables for a production Docker Compose deployment:

services:
  smart-redact-manager:
    environment:
      Database__DatabaseType: "PostgreSql"
      Database__ConnectionString: "User ID=smartredact;Password=smartredact;Server=smart-redact-manager-db;Port=5432;Database=smartredact;Maximum Pool Size=50;Timeout=30;"
      FileStorage__FileStorageType: "HostFileSystem"
      FileStorage__FilesDirectoryPath: "/app/storage_folder"
      Encryption__EncryptionKey: "${ENCRYPTION_KEY}"
      Encryption__DekTokenTtlMinutes: 1440
      ServiceCommunication__ConnectionString: "http://smart-redact-worker:4885/"
      Licensing__LicenseKey: "${PDFTOOLS_LICENSE_KEY}"
      OTEL_EXPORTER_OTLP_ENDPOINT: "${OTEL_EXPORTER_OTLP_ENDPOINT:-}"
    volumes:
      - storage:/app/storage_folder
      - logs:/app/logs

  smart-redact-orchestrator:
    environment:
      ManagerApi__BaseUrl: "http://smart-redact-manager:9982/"
      ManagerApi__PollingIntervalSeconds: 3
      Database__DatabaseType: "PostgreSql"
      Database__ConnectionString: "User ID=smartredact;Password=smartredact;Server=smart-redact-orchestrator-db;Port=5432;Database=smartredact;Maximum Pool Size=50;Timeout=30;"
      Jwt__SecretKey: "${ORCHESTRATOR_JWT_SECRET}"
      Licensing__LicenseKey: "${PDFTOOLS_LICENSE_KEY}"

Apply configuration changes​

Mount a custom appsettings.json​

Tune chunk size for performance​

GPU deployment​

Produce an encryption key​

How encryption works​

Key rotation​

AWS S3 file storage​

MinIO file storage​

Docker Compose reference​