---
description: Initialize Aidbox configuration resources at startup using Init Bundle with transaction or batch bundles via BOX_INIT_BUNDLE environment variable.
coverY: 0
---

# Init Bundle

{% hint style="info" %}
Available since the 2411 release.
{% endhint %}

Init Bundle is a simple approach to creating configuration resources when starting Aidbox.

It is equivalent to just executing [Bundle](../api/batch-transaction.md) in Aidbox using `POST /fhir`. There are some differences:

1. It is executed before the internal HTTP server starts, and before the health check response.
2. Unsuccessful execution of the init bundle of type **transaction** prevents Aidbox from starting.
3. Unsuccessful execution of the init bundle of type **batch** triggers warnings in the log; Aidbox continues the startup process.
4. Aidbox startup will be interrupted if the specified file is unavailable or is not a valid bundle resource of transaction or batch type.
5. Only JSON format is supported.

## Usage

Specify `BOX_INIT_BUNDLE` env. The value must be an URL.

```
BOX_INIT_BUNDLE=<URL>
```

Examples of URLs:

* `file:///tmp/bundle.json`
* `https://storage.googleapis.com/<BUCKET_NAME>/<OBJECT_NAME>`

## Example

If a Bundle file is created at `/tmp/bundle.json`:

```json
{
  "type": "batch",
  "resourceType": "Bundle",
  "entry": [
    {
      "request": {
        "method": "POST",
        "url": "/Observation",
        "ifNoneExist": "_id=o1"
      },
      "resource": {
        "id": "o1",
        "code": {
          "text": "text"
        },
        "status": "final",
        "effectiveDateTime": "2000-01-01"
      }
    }
  ]
}
```

Aidbox will apply it if the `BOX_INIT_BUNDLE` is set to:

```
BOX_INIT_BUNDLE=file:///tmp/bundle.json
```

## Hints

1. First, check that Aidbox handles the Bundle as it should using `POST /fhir`. Try to post it several times to make sure it is idempotent. Then add it to `BOX_INIT_BUNDLE`.
2. Note that the [Aidbox format](../api/rest-api/other/aidbox-and-fhir-formats.md) is not supported.
3. Aidbox handles an `id` in the body of the POST request. That's why posting the resource with an id twice will cause an `duplicate key` error. Use [conditional create](../api/rest-api/crud/create.md) or [update](../api/rest-api/crud/update.md) for that.
4. Most resources support `PUT` for idempotent updates inside an init bundle. **Exception:** [`AidboxTopicDestination`](../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md#updating-a-topicdestination) is immutable and rejects `PUT` / `PATCH` (also inside bundles). Use a [conditional create](../api/rest-api/crud/create.md) — `POST` with `ifNoneExist=_id=<id>` — so the entry is a no-op when the resource already exists and creates it on the first run:

   ```json
   {
     "request": {
       "method": "POST",
       "url": "AidboxTopicDestination",
       "ifNoneExist": "_id=<id>"
     },
     "resource": {
       "resourceType": "AidboxTopicDestination",
       "id": "<id>",
       "...": "..."
     }
   }
   ```

   To change configuration of an already-created destination, delete it manually and let the next bundle run recreate it — see [Updating a TopicDestination](../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md#updating-a-topicdestination).

## See also


{% content-ref url="../deployment-and-maintenance/deploy-aidbox/how-to-inject-env-variables-into-init-bundle.md" %}
[how-to-inject-env-variables-into-init-bundle.md](../deployment-and-maintenance/deploy-aidbox/how-to-inject-env-variables-into-init-bundle.md)
{% endcontent-ref %}
{% content-ref url="../tutorials/other-tutorials/how-to-run-sql-via-init-bundle.md" %}
[how-to-run-sql-via-init-bundle.md](../tutorials/other-tutorials/how-to-run-sql-via-init-bundle.md)
{% endcontent-ref %}
{% content-ref url="../tutorials/artifact-registry-tutorials/upload-fhir-implementation-guide/how-to-load-fhir-ig-with-init-bundle.md" %}
[how-to-load-fhir-ig-with-init-bundle](../tutorials/artifact-registry-tutorials/upload-fhir-implementation-guide/how-to-load-fhir-ig-with-init-bundle.md)
{% endcontent-ref %}