> For the complete documentation index, see [llms.txt](https://docs.biodock.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biodock.ai/files/aws-s3-integration.md).

# AWS S3 integration

Connect an Amazon S3 bucket and import images from it into Biodock.

*What you'll get: your S3 buckets connected to Biodock, and images imported from them into a folder in **Files**.*

## 1. Create read-only AWS keys

{% hint style="info" %}
Skip this step if you already have an AWS access key ID and secret access key that can read the buckets you want.
{% endhint %}

Biodock only needs to list your buckets and read files. Give it a user that can do nothing else.

1. In the AWS console, open **IAM** → **Users** and click **Create user**. Pick any name, such as `biodock-s3-access`.
2. Give the user read access. The safest choice is to attach a policy that only reads the buckets you want: see [Minimum policy](#minimum-policy) below. Or attach the AWS managed policy **AmazonS3ReadOnlyAccess**, which reads every bucket in the account.
3. Create the user, open it, and on its **Security credentials** tab click **Create access key**.
4. Copy the **Access key** and the **Secret access key**. AWS shows the secret only once.

## 2. Connect your bucket

<figure><img src="https://3806122466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk3DfNQKoMy1JXdaDLvpG%2Fuploads%2Fgit-blob-fceabfd74a5d516ad60e610db23d5cf946641839%2Fdocs-files-s3-connect.png?alt=media" alt="The Amazon S3 tab of Files, with the Connect your bucket card and the AWS Access Key ID and AWS Secret Access Key fields above the Connect button"><figcaption><p>The <strong>Amazon S3</strong> tab: paste your keys under <strong>Connect your bucket</strong>, then click <strong>Connect</strong>.</p></figcaption></figure>

1. Click **Files** in the sidebar and open the **Amazon S3** tab.
2. Under **Connect your bucket**, enter your **AWS Access Key ID** and **AWS Secret Access Key**.
3. Click **Connect**.

The tab now lists your buckets. Your keys are stored encrypted and are used only to list and fetch files from your buckets.

## 3. Import files

1. Click a bucket or folder to open it. The path above the list, starting at **Home**, takes you back up. **Search by prefix** finds names that start with what you type (S3 can only search this way).
2. Tick the files you want. You can tick files, not folders: open a folder to pick what is in it. Files in a format Biodock can't read are greyed out.
3. Click **Import to Biodock**.
4. In the **Import from Amazon S3** dialog, choose the folder to import into under **Destination**. Under **Options**, you can tick **Adaptive normalization**.
5. Click **Import here**.

Follow the progress with **Recent uploads** (the upload icon in the top bar). Imports are also listed on the **Past uploads** tab. When processing finishes, the files are in the folder you chose, ready to [analyse](https://docs.biodock.ai/analysis-and-results/running-an-analysis.md).

Imports follow the same rules as uploads: they count against your storage and have the same [upload limits](https://docs.biodock.ai/files/uploading-images.md#upload-limits).

To import a VSI image, put the `.vsi` file and its folder of `.ets` files in a `.zip` archive, and import the `.zip`.

#### If an import fails

*"Failed to import images. Please ensure your credentials have sufficient permissions"* means the keys you connected can't read the files you picked. Check the user's policy.

## Disconnect

Click **Disconnect** next to **Import to Biodock** and confirm. This permanently deletes your AWS keys from Biodock. To import again, connect again.

## Minimum policy

This policy lets Biodock list your buckets and read one bucket. Replace `test-examples-biodock` with the name of your bucket.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ReadOneBucket",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::test-examples-biodock",
                "arn:aws:s3:::test-examples-biodock/*"
            ]
        },
        {
            "Sid": "ListBuckets",
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "*"
        }
    ]
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.biodock.ai/files/aws-s3-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
