# On-premise setup

On on-premise instances, UI Bakery Storage needs an external object storage backend. UI Bakery creates storage buckets automatically when users create buckets from the Storage tab, and then uses signed URLs for browser uploads and reads.

UI Bakery Storage supports two backend types:

* Azure Blob Storage
* S3-compatible storage

Set the storage provider before users start creating UI Bakery Storage buckets. Existing buckets keep the provider that was used when they were created; changing the provider later does not migrate existing buckets.

### Azure Blob Storage

Azure Blob Storage is the default backend for UI Bakery Storage.

**1. Create an Azure storage account**

Open the Azure portal and go to **Storage accounts** -> **Create**.

UI Bakery Storage only needs a storage account. It creates containers automatically when users create buckets, so you do not need to create containers manually in advance.

Use the following settings:

* Preferred storage type: **Blob storage or Azure Data Lake Storage (ADLS) Gen2**
* Performance: **Standard**
* Redundancy: **Locally-redundant storage (LRS)** is the simplest default for most on-premise installations
* Enable hierarchical namespace: **Disabled**
* Access tier: **Hot**
* Allow anonymous access to blobs or containers: **Disabled**
* Enable storage account key access: **Enabled**
* Require secure transfer for REST API operations: **Enabled**

If you need a different redundancy option for compliance or disaster recovery, you can use it. UI Bakery Storage does not depend on a specific redundancy mode.

After the account is created, open **Security + networking** -> **Access keys** and copy one of the connection strings. You will use it in the UI Bakery environment variables.

**2. Configure CORS for Blob service**

UI Bakery uploads files from the browser directly to Azure by using signed URLs. Because of that, the Blob service must allow cross-origin requests from your UI Bakery domain.

Open your storage account in Azure and go to **Resource sharing (CORS)**. Under **Blob service**, add a rule with these values:

* Allowed origins: your UI Bakery URL, for example <https://uibakery.example.com>
* Allowed methods: GET, HEAD, PUT, OPTIONS
* Allowed headers: content-type,x-ms-blob-type,baggage,sentry-trace,x-ms-\*
* Exposed headers: \*
* Max age: 3600

If you use more than one domain, add all of them to the CORS rule. For example, if users open UI Bakery from separate internal and external URLs, both origins should be allowed.

**3. Configure environment variables**

Add the Azure connection string to your on-premise .env file:

```shellscript
UI_BAKERY_STORAGE_PROVIDER=AZURE_BLOB
UI_BAKERY_AZURE_BAKERY_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
UI_BAKERY_ENABLED_FEATURE_FLAGS=storageToolEnabled
```

`UI_BAKERY_STORAGE_PROVIDER=AZURE_BLOB` is optional because Azure is the default provider. Set it explicitly if you want the configuration to be self-documenting.

If `UI_BAKERY_ENABLED_FEATURE_FLAGS` already contains other flags, keep them and add storageToolEnabled to the comma-separated list.

After updating the environment file, restart the on-premise services so the backend picks up the new variables.

### S3-compatible storage

Use this option when your on-premise instance should store UI Bakery Storage data in an S3-compatible service, for example AWS S3, MinIO, Ceph, Cloudflare R2, or another object storage provider that supports the S3 API.

UI Bakery creates one physical bucket for each UI Bakery Storage bucket. The generated bucket name uses the uib-... prefix, so make sure your storage policy allows the UI Bakery backend to create and delete buckets with that naming pattern.

**1. Prepare S3-compatible access**

Create or choose S3 credentials for UI Bakery. The credentials must be able to:

* Create buckets
* Check bucket existence
* List objects
* Put objects
* Get objects
* Delete objects
* Delete buckets

If your provider requires a fixed region, use that region in the UI Bakery configuration. If it does not, use the provider's recommended default, commonly us-east-1.

**2. Configure CORS**

UI Bakery uploads files from the browser directly to the S3-compatible backend by using signed URLs. Configure CORS on your S3-compatible service to allow requests from your UI Bakery domain.

Use the equivalent of this rule:

```json
[
  {
    "AllowedOrigins": [ "https://uibakery.example.com" ],
    "AllowedMethods": [ "GET", "HEAD","PUT" ],
    "AllowedHeaders": [ "content-type", "x-ms-blob-type", "x-amz-*" ],
    "ExposeHeaders": [ "ETag" ],
    "MaxAgeSeconds": 3600
  }
]
```

Replace <https://uibakery.example.com> with your UI Bakery URL. If users access UI Bakery from multiple internal or external URLs, add every URL to the allowed origins list.

Some S3-compatible providers support \* for exposed headers. If yours does, you can use it instead of ETag.

**3. Configure environment variables**

Add the S3-compatible storage settings to your on-premise .env file:

```bash
UI_BAKERY_STORAGE_PROVIDER=S3_COMPATIBLE
UI_BAKERY_STORAGE_S3_ENDPOINT=https://s3.example.com
UI_BAKERY_STORAGE_S3_REGION=us-east-1
UI_BAKERY_STORAGE_S3_ACCESS_KEY=...
UI_BAKERY_STORAGE_S3_SECRET_KEY=...
UI_BAKERY_STORAGE_S3_PATH_STYLE=true
UI_BAKERY_STORAGE_S3_PRESIGN_VALIDITY=15m
UI_BAKERY_ENABLED_FEATURE_FLAGS=storageToolEnabled
```

Configuration details:

* `UI_BAKERY_STORAGE_S3_ENDPOINT` is the S3 API endpoint. If you omit the scheme, UI Bakery treats it as HTTPS. For local or non-TLS endpoints, include http\:// explicitly.
* `UI_BAKERY_STORAGE_S3_REGION` is required by the S3 client.
* `UI_BAKERY_STORAGE_S3_ACCESS_KEY` and `UI_BAKERY_STORAGE_S3_SECRET_KEY` are used by the backend and datasource runtime.
* `UI_BAKERY_STORAGE_S3_PATH_STYLE` defaults to true. Keep it enabled for most S3-compatible providers and local MinIO setups. Set it to false only if your provider supports virtual-hosted-style bucket URLs.
* `UI_BAKERY_STORAGE_S3_PRESIGN_VALIDITY` controls how long backend-generated upload and read URLs stay valid. The default is 15m.

If `UI_BAKERY_ENABLED_FEATURE_FLAGS` already contains other flags, keep them and add storageToolEnabled to the comma-separated list.

After updating the environment file, restart the on-premise services so the backend picks up the new variables.

**4. Verify the setup**

After the restart:

1. Open UI Bakery and go to the **Storage** tab.
2. Create a new bucket.
3. Upload a test file.
4. Open the uploaded file from UI Bakery to verify that signed read URLs work.
5. Delete the test bucket if you do not need it.

If bucket creation fails, check that the endpoint, region, credentials, and bucket-creation permissions are correct. If file upload fails in the browser, check the CORS rule for the exact UI Bakery origin and allowed headers.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uibakery.io/extras/ui-bakery-storage/on-premise-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.