Storage
Generated PDFs go to one storage driver per install, set by STORAGE_DRIVER. Everything else (templates, assets, uploaded PDFs, users, the generation log) stays in Postgres. Every API and worker node must reach the same storage: workers write outputs, API nodes stream them to downloads.
Readiness (/api/health/ready) checks storage: a probe write, read and delete on disk, a bucket or container check otherwise. A node with a missing mount or bad credentials goes unready.
Object keys are the file’s id, sharded two levels deep (ab/cd/abcd…), under STORAGE_PREFIX if set (S3 and Azure only; disk ignores it). Deleting a generation, or running retention, deletes its object.
STORAGE_DRIVER=diskSTORAGE_DIR=/data/files # the image's defaultOne host: a Docker volume (Compose does this). Several hosts or pods: a shared mount (NFS, EFS, Azure Files, a ReadWriteMany PVC). Readiness catches a node without the directory, but not two nodes with separate disks that both pass, so make sure it really is shared.
AWS S3
Section titled “AWS S3”STORAGE_DRIVER=s3S3_BUCKET=necodoc-outputsS3_REGION=eu-west-1# Optional: SSE-KMS with your keyS3_SSE=aws:kmsS3_KMS_KEY_ID=arn:aws:kms:eu-west-1:123456789012:key/...Leave the keys unset to use the AWS default credential chain: an IAM role through IRSA or EKS Pod Identity, an instance profile, or env. The role needs s3:GetObject, s3:PutObject, s3:DeleteObject and s3:ListBucket on the bucket.
MinIO and other S3-compatible stores
Section titled “MinIO and other S3-compatible stores”STORAGE_DRIVER=s3S3_BUCKET=necodocS3_ENDPOINT=http://minio:9000S3_FORCE_PATH_STYLE=trueS3_ACCESS_KEY_ID=necodocS3_SECRET_ACCESS_KEY=...Create the bucket first. The Compose minio profile does it for you.
Cloudflare R2
Section titled “Cloudflare R2”STORAGE_DRIVER=s3S3_BUCKET=necodocS3_REGION=autoS3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.comS3_ACCESS_KEY_ID=...S3_SECRET_ACCESS_KEY=...Azure Blob Storage
Section titled “Azure Blob Storage”Pick one way to authenticate:
STORAGE_DRIVER=azureAZURE_STORAGE_CONTAINER=necodoc
# 1. Connection stringAZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
# 2. Account and keyAZURE_STORAGE_ACCOUNT=necodocprodAZURE_STORAGE_KEY=...
# 3. Managed or workload identity (DefaultAzureCredential): the account aloneAZURE_STORAGE_ACCOUNT=necodocprodWith an identity, grant it Storage Blob Data Contributor on the container. AZURE_STORAGE_ACCOUNT_URL overrides the endpoint (sovereign clouds, Azurite).
Presigned downloads
Section titled “Presigned downloads”By default every download streams through the API after its permission check, with ETag and range support. STORAGE_REDIRECT=presigned instead redirects to a short-lived S3 presigned URL or Azure SAS, which takes the bytes off the API. Browsers must be able to reach the bucket’s endpoint, so it doesn’t suit an internal-only S3_ENDPOINT such as http://minio:9000. With managed identity, Azure SAS URLs are user-delegation SAS, so the identity also needs permission to request a user delegation key.
Moving outputs
Section titled “Moving outputs”Installs from before object storage existed kept generated outputs in Postgres. storage-migrate copies them to the configured driver, checks each copy’s SHA-256, then clears them from the database. It’s safe to stop and rerun.
docker compose run --rm api storage-migrate # Composekubectl -n necodoc exec deploy/necodoc-api -- docker-entrypoint.sh storage-migrate # KubernetesIt only moves outputs stored in Postgres.
Switching drivers
Section titled “Switching drivers”Each file row records which driver holds its bytes, and a node only reads through the driver it’s configured for. After you change STORAGE_DRIVER, outputs written under the old driver fail to download, and deleting them leaves their objects behind. There’s no tool to move outputs between drivers yet, so pick the driver before going live.