Storage

The Storage category configures where Hawkra stores uploaded files such as report attachments, evidence screenshots, and other workspace file uploads. You can choose between local disk storage (the default) or S3-compatible object storage for scalability and external backups.

Settings Reference

Storage Backend

Key	storage_backend
Type	Dropdown (local or s3)
Default	local
Encrypted	No

Determines where uploaded files are stored:

• local — Files are stored on disk inside the Docker container's file_storage volume. This is the simplest configuration and requires no additional setup.
• s3 — Files are stored in an S3-compatible object storage bucket. Requires configuring the S3 settings below.

S3 Bucket Name

Key	storage_s3_bucket
Type	String
Default	Empty
Encrypted	No

The name of the S3 bucket where files will be stored. The bucket must already exist — Hawkra does not create it automatically.

Example: hawkra-files, my-org-hawkra-storage

S3 Region

Key	storage_s3_region
Type	String
Default	Empty
Encrypted	No

The AWS region where your S3 bucket is located.

Examples: us-east-1, eu-west-1, ap-southeast-2

For S3-compatible services, use the region specified by your provider.

S3 Endpoint URL

Key	storage_s3_endpoint
Type	String
Default	Empty
Encrypted	No

A custom endpoint URL for S3-compatible storage services. Leave this empty when using AWS S3 directly (the SDK uses the default AWS endpoints based on the region).

Set this when using S3-compatible alternatives:

Service	Endpoint Example
MinIO	http://minio:9000 or https://minio.yourdomain.com
DigitalOcean Spaces	https://nyc3.digitaloceanspaces.com
Backblaze B2	https://s3.us-west-002.backblazeb2.com
Wasabi	https://s3.wasabisys.com

AWS Access Key ID

Key	aws_access_key_id
Type	String
Default	Empty
Encrypted	Yes

The access key ID for authenticating with S3. For AWS, this comes from an IAM user with S3 permissions. For S3-compatible services, use the access key provided by your storage provider.

AWS Secret Access Key

Key	aws_secret_access_key
Type	String
Default	Empty
Encrypted	Yes

The secret access key paired with the access key ID. This value is stored encrypted in the database and appears masked on the settings page.

Local Storage

When using the local backend (the default), files are stored on disk inside the Docker container at the path defined by the STORAGE_LOCAL_PATH environment variable (defaults to ./data/files). This path is backed by the file_storage Docker volume, which persists data across container restarts and updates.

No additional configuration is required for local storage. The file_storage volume is defined in the Docker Compose file and automatically mounted.

tip

Local storage is the recommended option for most self-hosted deployments. It is simple, fast, and does not depend on external services. Include the file_storage volume in your backup strategy.

S3 Storage Setup

AWS S3

1. Create an S3 bucket in your desired region through the AWS Console or CLI.
2. Create an IAM user with programmatic access and attach a policy granting s3:PutObject, s3:GetObject, s3:DeleteObject, and s3:ListBucket on the bucket.
3. Copy the access key ID and secret access key.
4. Configure the settings in the admin dashboard:

Setting	Value
Storage Backend	s3
S3 Bucket Name	Your bucket name
S3 Region	Your bucket's region (e.g., us-east-1)
S3 Endpoint URL	Leave empty (uses default AWS endpoints)
AWS Access Key ID	Your IAM access key
AWS Secret Access Key	Your IAM secret key

Example IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::hawkra-files",
        "arn:aws:s3:::hawkra-files/*"
      ]
    }
  ]
}

MinIO (Self-Hosted S3)

MinIO is a self-hosted, S3-compatible object storage server. It is a good choice if you want S3-like storage without depending on a cloud provider.

1. Deploy MinIO on your infrastructure (as a Docker container or standalone).
2. Create a bucket for Hawkra through the MinIO Console or mc CLI.
3. Create an access key and secret key.
4. Configure the settings:

Setting	Value
Storage Backend	s3
S3 Bucket Name	Your MinIO bucket name
S3 Region	us-east-1 (or your configured region)
S3 Endpoint URL	http://minio:9000 (or your MinIO URL)
AWS Access Key ID	Your MinIO access key
AWS Secret Access Key	Your MinIO secret key

DigitalOcean Spaces

Setting	Value
Storage Backend	s3
S3 Bucket Name	Your Space name
S3 Region	Your Space's region (e.g., nyc3)
S3 Endpoint URL	https://<region>.digitaloceanspaces.com
AWS Access Key ID	Your Spaces access key
AWS Secret Access Key	Your Spaces secret key

Backblaze B2

Setting	Value
Storage Backend	s3
S3 Bucket Name	Your B2 bucket name
S3 Region	Your bucket's region
S3 Endpoint URL	https://s3.<region>.backblazeb2.com
AWS Access Key ID	Your B2 application key ID
AWS Secret Access Key	Your B2 application key

Configuration via Environment Variables

Setting	Environment Variable
Storage Backend	STORAGE_BACKEND
S3 Bucket Name	STORAGE_S3_BUCKET
S3 Region	STORAGE_S3_REGION
S3 Endpoint URL	STORAGE_S3_ENDPOINT
AWS Access Key ID	AWS_ACCESS_KEY_ID
AWS Secret Access Key	AWS_SECRET_ACCESS_KEY

caution

Switching the storage backend from local to s3 (or vice versa) does not migrate existing files. Files uploaded under the previous backend remain in their original location. Only new uploads use the new backend. If you need to migrate existing files, you must copy them manually between storage locations.