5.4.0
ForgeBox Enterprise
S3
Packages hosted in private S3 buckets can be installed directly from S3 URLs.
Installation
To install a package from a S3 bucket, use a URL like so:
1
install s3://my-private-bucket/myPackage.zip
Copied!
The S3 endpoint will automatically determine which region your bucket is in order to download your package. You can, however, bypass this automatic bucket region resolution by encoding the region of your bucket into the S3 path by using a
: after the bucket name:1
install s3://my-private-bucket:eu-west-2/myPackage.zip
Copied!
Info If your S3 path does not end in.zipthe S3 endpoint will make a HEAD request to S3 for the package path to determine if your package exists at that location. If it does not, then.zipwill be appended to your S3 path and that new path will be used as the location of your package. This means it is possible for you to specify a package without adding the.zipextension:s3://my-private-bucket/myPackage.
In box.json
You can specify packages from S3 endpoints as dependencies in your
box.json in this format:1
{
2
"dependencies" : {
3
"myPackage" : "s3://my-private-bucket/myPackage.zip"
4
}
5
}
Copied!
Authentication
In order for S3 endpoints to be resolved, CommandBox needs an AWS access key and AWS secret key belonging to an AWS IAM user or role that has permission to get objects from the S3 bucket where the package is stored. The access and secret keys can be set in CommandBox settings either globally:
1
config set endpoint.s3.aws_access_key_id=XXXXXXXXXX
2
config set endpoint.s3.aws_secret_access_key=XXXXXXXXXX
Copied!
or on a per bucket basis:
1
config set endpoint.s3.my-private-bucket.aws_access_key_id=XXXXXXXXXX
2
config set endpoint.s3.my-private-bucket.aws_secret_access_key=XXXXXXXXXX
Copied!
If
aws_access_key_id and aws_secret_access_key are not set in your CommandBox settings, the S3 endpoint checks for credentials in the same places and order as the AWS CLI and SDKs:It checks for
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables containing the credentials.It checks for an AWS credentials ini file. (If you use the AWS CLI, this file is created by the CLI when you enter your credentials during setup. The default location for this file is at
~/.aws/credentials.)Info The location of the credentials ini file can be overwritten by setting anAWS_SHARED_CREDENTIALS_FILEenvironment variable to an alternate file path (this can also be set in your CommandBox settings:endpoint.s3.aws_shared_credentials_file). Further, the AWS credentials file has the concept of "profiles", where the default profile is named "default". The profile to use can be changed from "default" by setting an alternate profile name in anAWS_PROFILEenvironment variable or CommandBox endpoint setting (endpoint.s3.aws_profile).
Finally the S3 endpoint will check for the presence of an IAM role from which credentials can be obtained. This credential location is only valid on AWS EC2 instances.
The full list of possible credential locations and the order in which they are checked is as follows:
- Per bucket credentials in your CommandBox endpoint settings
- Global credentials in your CommandBox endpoint settings
- Environment variables
- AWS credentials file
- IAM role
Last modified 3yr ago
Copy link
Edit on GitHub