Configuring S3

1. Create a bucket

Create a bucket in AWS in any region. (And keep public access blocked.)

2. Grant permissions

Grant the appropriate read, write, delete, list, and multipart upload permissions on the bucket. You may apply this directly to the actor, or as a separate role assigned to the actor:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET"
    }
  ]
}

3. Set the credentials

If your environment is already configured for AWS CLI usage, the standard AWS environment variables should be picked up automatically:

export AWS_ACCESS_KEY_ID={access_key_id}
export AWS_SECRET_ACCESS_KEY={secret_access_key}
export AWS_SESSION_TOKEN={session_token}   # only for temporary credentials

Otherwise, pass them explicitly with --access-key-id, --secret-access-key, and --session-token.

4. Create the profile

loonfs --no-input profile create s3 production \
  --bucket {bucket_name} \
  --region {aws_region}

loonfs profile use production

Optional flags: --key-prefix to scope LoonFS within the bucket, --endpoint-url and --force-path-style for S3-compatible stores that aren’t AWS.

S3 vs. S3-compatible

“Real” AWS S3 endpoints (not just S3-compatible) support direct GET, direct PUT with SHA-256, and direct multipart transfers. S3-compatible endpoints can be used via the proxied path, but LoonFS does not support direct transfers until that S3-compatible store has passed the provider test.

CORS

For browser clients using direct transfers, configure bucket CORS to allow the returned methods and signed headers from your application origin. It’s also best practiceto set up an S3 lifecycle rule to abort incomplete multipart uploads after a reasonable window.

5. Verify

loonfs maintenance store probe