# How to Configure MinIO for File Storage in OpenCTI: Complete Setup Guide

> Learn to configure MinIO for file storage in OpenCTI. Follow this complete guide to deploy MinIO and set environment variables for seamless file handling.

- Repository: [OpenCTI Platform/opencti](https://github.com/opencti-platform/opencti)
- Tags: how-to-guide
- Published: 2026-02-19

---

**To configure MinIO for file storage in OpenCTI, deploy a MinIO container, set the `MINIO__*` environment variables for endpoint and credentials, and let the platform automatically initialize the bucket on startup.**

OpenCTI stores binary data—such as attachments, exported reports, and malware samples—through an S3-compatible object store. MinIO serves as the default lightweight implementation for both development and production deployments. This guide explains how to configure MinIO for file storage in OpenCTI based on the actual source code implementation in the [OpenCTI-Platform/opencti](https://github.com/OpenCTI-Platform/opencti) repository.

## Understanding OpenCTI's File Storage Architecture

OpenCTI delegates all file operations to an S3-compatible client, with MinIO being the reference implementation. The architecture separates low-level storage logic from high-level file management.

### Core Storage Components

The platform implements a two-layer storage system:

* **[`raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/raw-file-storage.ts)** – Located at [`opencti-platform/opencti-graphql/src/database/raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-platform/opencti-graphql/src/database/raw-file-storage.ts), this module builds the S3 client from `@aws-sdk/client-s3`, initializes the bucket, and handles direct upload/download streams.
* **[`file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/file-storage.ts)** – Located at [`opencti-platform/opencti-graphql/src/database/file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-platform/opencti-graphql/src/database/file-storage.ts), this higher-level wrapper applies exclusion rules (filtering files listed in `minio:excluded_files`) before delegating to the raw implementation.

### Configuration Flow

OpenCTI reads MinIO settings through a `conf` helper that resolves environment variables or JSON configuration files. The initialization sequence in [`opencti-platform/opencti-graphql/src/initialization.js`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-platform/opencti-graphql/src/initialization.js) verifies MinIO availability on startup, while [`raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/raw-file-storage.ts) ensures the target bucket exists before accepting uploads.

## Deploying MinIO for OpenCTI

The OpenCTI repository provides ready-to-use Docker Compose definitions for running MinIO in different environments.

### Development Setup

For local development, use the service definition in [`opencti-dev/docker-compose.yml`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-dev/docker-compose.yml):

```yaml
opencti-dev-minio:
  container_name: opencti-dev-minio
  image: minio/minio:RELEASE.2025-06-13T11-33-47Z
  command: server /data
  environment:
    MINIO_ROOT_USER: ${MINIO_ROOT_USER:-ChangeMe}
    MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-ChangeMe}
  ports:
    - "9000:9000"
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
    interval: 30s
    timeout: 5s
    retries: 3

```

This exposes MinIO on port 9000 and includes a health check endpoint used by the OpenCTI initialization routine.

### CI and Testing Setup

For automated testing, the repository includes a minimal MinIO service in [`scripts/ci/docker-compose.yml`](https://github.com/OpenCTI-Platform/opencti/blob/main/scripts/ci/docker-compose.yml). This lightweight configuration is used by the CI workflow defined in [`.github/workflows/ci-test-backend.yml`](https://github.com/OpenCTI-Platform/opencti/blob/main/.github/workflows/ci-test-backend.yml) to validate file storage operations without external dependencies.

## Configuring MinIO Connection Settings

OpenCTI accepts MinIO configuration through environment variables or JSON configuration files. The platform merges these sources using the `conf` helper, with environment variables taking precedence.

### Environment Variables

Map your MinIO settings using the `MINIO__*` prefix. These variables override values in [`config/default.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/default.json):

```bash
MINIO__ENDPOINT=minio
MINIO__PORT=9000
MINIO__USE_SSL=false
MINIO__ACCESS_KEY=ChangeMe
MINIO__SECRET_KEY=ChangeMe
MINIO__BUCKET_NAME=opencti-bucket
MINIO__BUCKET_REGION=us-east-1
MINIO__USE_AWS_ROLE=false
MINIO__EXCLUDED_FILES=[".DS_Store"]

```

In a Docker Compose stack, define these in the `opencti` service environment section to establish connectivity with the MinIO container.

### JSON Configuration Files

The default configuration schema resides in [`opencti-platform/opencti-graphql/config/default.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-platform/opencti-graphql/config/default.json):

```json
{
  "minio": {
    "endpoint": "localhost",
    "port": 9000,
    "use_ssl": false,
    "access_key": "ChangeMe",
    "secret_key": "ChangeMe",
    "bucket_name": "opencti-bucket",
    "bucket_region": "us-east-1",
    "use_aws_role": false,
    "use_aws_logs": false,
    "disable_checksum_validation": false,
    "excluded_files": [".DS_Store"]
  }
}

```

For production deployments, create a [`config/production.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/production.json) file containing only the keys you wish to override. OpenCTI merges these layers at runtime, with environment variables taking final precedence.

## Bucket Initialization and File Operations

OpenCTI handles bucket provisioning and file transfers automatically once configured.

### Automatic Bucket Creation

During platform initialization ([`src/initialization.js`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/initialization.js)), OpenCTI verifies MinIO connectivity. The [`raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/raw-file-storage.ts) module then checks for the configured bucket and creates it if absent:

```typescript
// From raw-file-storage.ts - S3 client initialization and bucket check
const s3Client = new S3Client({
  endpoint: `http${useSsl ? 's' : ''}://${endpoint}:${port}`,
  region: bucketRegion,
  credentials: { accessKeyId: accessKey, secretAccessKey: secretKey }
});
// Bucket creation logic executes on first use if bucket does not exist

```

This eliminates manual bucket provisioning steps.

### Upload and Download Process

File operations flow through two layers:

1. **[`file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/file-storage.ts)** – Validates files against `excluded_files` patterns (e.g., filtering `.DS_Store`) and prepares metadata.
2. **[`raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/raw-file-storage.ts)** – Executes the actual S3 operations:
   * **`uploadFile`** – Streams data to the MinIO bucket using the AWS SDK `PutObjectCommand`.
   * **`downloadFile`** – Generates presigned URLs or returns streams via `GetObjectCommand`.

All binary data—including malware samples, threat intelligence reports, and exported STIX bundles—flows through this pipeline.

## Advanced MinIO Configuration Options

OpenCTI supports several advanced settings for production deployments and specific infrastructure requirements.

| Feature | Configuration Key | Environment Variable | Description |
|---------|-------------------|----------------------|-------------|
| **AWS IAM Role** | `minio:use_aws_role` | `MINIO__USE_AWS_ROLE` | When `true`, the SDK retrieves temporary credentials from EC2/ECS metadata instead of static keys. |
| **CloudWatch Logging** | `minio:use_aws_logs` | `MINIO__USE_AWS_LOGS` | Enables S3 event logging to AWS CloudWatch for audit trails. |
| **Checksum Validation** | `minio:disable_checksum_validation` | `MINIO__DISABLE_CHECKSUM_VALIDATION` | Disables integrity checks—useful for large files on resource-constrained nodes. |
| **Credentials Provider** | `minio:credentials_provider` | `MINIO__CREDENTIALS_PROVIDER` | Supports external secret managers (e.g., CyberArk) for runtime credential retrieval. |

These options are documented in [`docs/docs/deployment/configuration.md`](https://github.com/OpenCTI-Platform/opencti/blob/main/docs/docs/deployment/configuration.md) and parsed by the configuration loader in [`opencti-platform/opencti-graphql/src/config/conf.js`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-platform/opencti-graphql/src/config/conf.js).

## Summary

Configuring MinIO for file storage in OpenCTI requires three core steps:

* **Deploy MinIO** using the provided Docker Compose definitions in [`opencti-dev/docker-compose.yml`](https://github.com/OpenCTI-Platform/opencti/blob/main/opencti-dev/docker-compose.yml) or [`scripts/ci/docker-compose.yml`](https://github.com/OpenCTI-Platform/opencti/blob/main/scripts/ci/docker-compose.yml).
* **Configure connection parameters** via `MINIO__*` environment variables or JSON config files to match your MinIO endpoint, credentials, and bucket name.
* **Allow automatic initialization**—OpenCTI creates the bucket on startup and handles all uploads/downloads through [`raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/raw-file-storage.ts) and [`file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/file-storage.ts).

## Frequently Asked Questions

### What is the default MinIO bucket name used by OpenCTI?

The default bucket name is `opencti-bucket`, as defined in [`config/default.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/default.json). You can override this by setting the `MINIO__BUCKET_NAME` environment variable or providing a custom value in your [`config/production.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/production.json) file.

### Does OpenCTI automatically create the MinIO bucket?

Yes. During platform initialization, the code in [`src/database/raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/database/raw-file-storage.ts) checks for the configured bucket and creates it automatically if it does not exist. No manual bucket provisioning is required.

### Can I use AWS S3 instead of MinIO for file storage?

Yes. OpenCTI uses the standard AWS SDK (`@aws-sdk/client-s3`) in [`raw-file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/raw-file-storage.ts), so any S3-compatible storage—including AWS S3, MinIO, or Ceph—works. Simply configure the `endpoint`, `access_key`, `secret_key`, and `bucket_region` parameters to match your provider.

### How do I exclude specific files from being uploaded to MinIO?

Set the `minio:excluded_files` configuration key (or `MINIO__EXCLUDED_FILES` environment variable) to an array of filename patterns. By default, this includes `.DS_Store` files. The filtering logic is applied in [`src/database/file-storage.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/database/file-storage.ts) before delegating to the raw storage layer.