Connecting an AWS S3 Bucket to a Project

Projects can be configured to store and serve files from an AWS S3 bucket. This allows your organisation's data to remain in your own AWS account.

Prerequisites

You will need the Configure File Settings permission on the project. See Permissions for details.

Before configuring the project, you will need the following from AWS:

  • An S3 bucket already created in your AWS account
  • The bucket's region (e.g. ap-southeast-2)
  • An IAM user with programmatic access and the following permissions on the bucket:
    • s3:ListBucket
    • s3:GetObject
    • s3:PutObject
    • s3:DeleteObject
    • s3:AbortMultipartUpload (required for multipart uploads)
  • The IAM user's Access Key ID and Secret Access Key

Steps

  1. Navigate to your project and open the Settings tab.
  2. Scroll down to the File Storage Setup section.
  3. Set File Storage Source to AWS S3.
  4. Fill in the fields:
    FieldDescription
    AWS S3 BucketThe name of your S3 bucket (e.g. my-company-data)
    AWS S3 RegionThe region the bucket is in (e.g. ap-southeast-2)
    Key PrefixOptional path prefix for all files in this project (e.g. project-a/). This allows multiple projects to share a single bucket by scoping each to a different prefix. Leave empty to use the bucket root.
    AWS IAM UserThe Access Key ID for your IAM user (e.g. AKIAIOSFODNN7EXAMPLE)
    AWS IAM User SecretThe Secret Access Key for your IAM user
  5. Click Save.

The project will now use the configured S3 bucket for file storage and access.

CORS Configuration

When uploading files, the browser uploads directly to S3 using presigned URLs. For this to work, your S3 bucket must have a CORS (Cross-Origin Resource Sharing) policy that allows requests from the domain where udServer is hosted.

In the AWS Console, navigate to your bucket > Permissions > Cross-origin resource sharing (CORS) and add the following configuration:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "HEAD"],
    "AllowedOrigins": ["https://your-udserver-domain.com"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

Replace https://your-udserver-domain.com with the origin your udServer instance is served from. This is typically https://udcloud.nuclideon.com or https://au-udcloud.nuclideon.com. You can list multiple origins if needed.

FieldWhy it's needed
AllowedMethodsPUT is required for direct uploads. GET and HEAD for file downloads and metadata.
ExposeHeadersETag must be exposed so the browser can read the upload part checksums returned by S3. Without this, uploads will fail at the completion step.
MaxAgeSecondsCaches the preflight response so the browser doesn't send an OPTIONS request before every chunk.

Without this configuration, file uploads from the browser will fail with CORS errors.