# Configure Storage

## Local Storage

By default, homebox uses local storage at the `.data` folder relative path to the binary, or `/data` in the docker
container.
You can change the storage path by setting the `HBOX_STORAGE_CONN_STRING` to `file:///full/path/you/want`. The
`HBOX_STORAGE_PREFIX_PATH`
can be used to set a "prefix" for the storage. This "prefix" comes after the path in the connection string.

::: warning
The local storage path must be writable by the user running the Homebox process. Homebox will automatically create the
default directories, if you change the path you must ensure that the directory specified exists and is writable.
:::

## S3 Storage

### Authentication

To authenticate with S3, you will need to set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
Optionally, you can also set `AWS_SESSION_TOKEN` if you are using temporary credentials.

### AWS S3

You can use S3 storage by setting the `HBOX_STORAGE_CONN_STRING` to `s3://my-bucket?region=region-name&awssdk=v2`.

In this case, the `HBOX_STORAGE_PREFIX_PATH` can be used to set a "prefix" for the storage. This "prefix" comes after
the bucket name in the connection string.

### S3-Compatible Storage

You can also use S3-compatible storage by setting the `HBOX_STORAGE_CONN_STRING` to
`s3://my-bucket?awssdk=v2&endpoint=http://my-s3-compatible-endpoint.tld&disableSSL=true&s3ForcePathStyle=true`.

This allows you to connect to S3-compatible services like MinIO, DigitalOcean Spaces, or any other service that supports
the S3 API. Configure the `disableSSL`, `s3ForcePathStyle`, and `endpoint` parameters as needed for your specific
service.

#### Tested S3-Compatible Storage

| Service             | Working | Connection String                                                                                                        |
|---------------------|---------|--------------------------------------------------------------------------------------------------------------------------|
| MinIO               | Yes     | `s3://my-bucket?awssdk=v2&endpoint=http://minio:9000&disableSSL=true&s3ForcePathStyle=true`                              |
| Cloudflare R2       | Yes     | `s3://my-bucket?awssdk=v2&endpoint=https://<account-id>.r2.cloudflarestorage.com&disableSSL=false&s3ForcePathStyle=true` |
| Backblaze B2        | Yes     | `s3://my-bucket?awssdk=v2&endpoint=https://s3.us-west-004.backblazeb2.com&disableSSL=false&s3ForcePathStyle=true`        |

::: info
If you know of any other S3-compatible storage that works with Homebox, please let us know or create a pull request to update the table.
:::

### Extra Connection Parameters

Additionally, the parameters in the URL can be used to configure specific S3 settings:

- `region`: The AWS region where the bucket is located.
- `awssdk`: The version of the AWS SDK to use (e.g., `v2`). (We highly recommend using `v2` for better performance and
  features.)
- `endpoint`: The custom endpoint for S3-compatible storage services.
- `s3ForcePathStyle`: Whether to force path-style access (set to `true` or `false`).
- `disableSSL`: Whether to disable SSL (set to `true` or `false`).
- `sseType`: The server-side encryption type (e.g., `AES256` or `aws:kms` or `aws:kms:dsse`).
- `kmskeyid`: The KMS key ID for server-side encryption.
- `fips`: Whether to use FIPS endpoints (set to `true` or `false`).
- `dualstack`: Whether to use dual-stack endpoints (set to `true` or `false`).
- `accelerate`: Whether to use S3 Transfer Acceleration (set to `true` or `false`).


## Google Cloud Storage

### Authentication

To authenticate with Google Cloud Storage, you will need to set the `GOOGLE_APPLICATION_CREDENTIALS` environment
variable to the path of your service account key file.
This file should be in JSON format and contain the necessary credentials to access your Google Cloud Storage bucket and
must be made available to the application if running docker via read-only volume mounts.

### Using Google Cloud Storage

You can use Google Cloud Storage by setting the `HBOX_STORAGE_CONN_STRING` to `gcs://my-bucket`.

## Azure Blob Storage

### Authentication

To authenticate with Azure blob storage, you will need to set the `AZURE_STORAGE_ACCOUNT` and `AZURE_STORAGE_KEY`
environment variables. Optionally, you can also set `AZURE_STORAGE_SAS_TOKEN` if you are using a Shared Access
Signature (SAS) for authentication.

### Using Azure Blob Storage

You can use Azure Blob Storage by setting the `HBOX_STORAGE_CONN_STRING` to `azblob://my-container`.

### Local Azure Storage Emulator

If you want to use the local Azure Storage Emulator, you can set the `HBOX_STORAGE_CONN_STRING` to
`azblob://my-container?protocol=http&domain=localhost:10001`. This will allow you to use the emulator for development
and testing purposes.