Ember CLI Deploy S3 Index Plugin

4.0.3 · active · verified Wed Apr 22

This plugin for Ember CLI Deploy specializes in uploading the `index.html` (bootstrap) file of an Ember application to an Amazon S3 bucket. It is commonly used as part of the 'lightning method' of deployment, where both application assets and the index file are served from S3. The current stable version is 4.0.3, with recent bug fixes focusing on robust S3 response handling, including 'NotFound' and empty responses. It integrates into the `ember-cli-deploy` pipeline, implementing `configure`, `upload`, `activate`, and `fetchRevisions` hooks. It's actively maintained with a moderate release cadence addressing bug fixes and minor enhancements, distinguishing itself by managing *only* the index file, often alongside `ember-cli-deploy-s3` which handles other application assets.

Common errors

```
Error: Access Denied
```
cause The AWS credentials (accessKeyId, secretAccessKey, profile, or IAM role) used by the plugin lack the necessary S3 permissions (e.g., `s3:PutObject`, `s3:GetObject`, `s3:ListBucket`) for the target bucket and prefix.

fix Verify that your AWS credentials are correct and that the associated IAM user or role has the required S3 permissions configured for the specified bucket and prefix in your AWS IAM console.
```
Error: The specified key does not exist.
```
cause The plugin attempted to fetch a previous revision of the index file from S3, but the file was not found at the expected location. This could be due to an incorrect `filePattern`, `prefix` configuration, or manual deletion of S3 objects.

fix Double-check the `filePattern` and `prefix` settings in `config/deploy.js`. Use the AWS S3 console or CLI to inspect your bucket contents and confirm the path and existence of expected index files and revision history.
```
Error: An empty S3 response was encountered.
```
cause An unexpected empty response was received from AWS S3 during an operation (e.g., listing revisions). This might indicate an S3 misconfiguration, an intermittent AWS service issue, or a bug in previous plugin versions.

fix Ensure your S3 bucket configuration is valid and accessible. Check the AWS Service Health Dashboard for S3 issues. This specific bug was addressed and resolved in plugin versions 4.0.2 and 4.0.3; upgrading the plugin might be necessary.

Warnings

gotcha Do NOT share a single configuration object between `ember-cli-deploy-s3` (for static assets) and `ember-cli-deploy-s3-index` (for index.html). The internal configuration parsing can lead to side effects and break your deployment pipeline if a shared object is used.
Fix: Always define separate and distinct configuration objects for `ENV.s3` and `ENV['s3-index']` in your `config/deploy.js`, even if properties like `bucket` or `region` are identical.
breaking Version 3.0.0 introduced significant breaking changes, primarily updating Node.js version requirements and internal dependencies. Projects must meet the new Node.js compatibility.
Fix: Upgrade your Node.js environment to `14.* || 16.* || 18.* || >= 20`. Review and update your project's `package.json` dependencies to ensure compatibility with `ember-cli-deploy` and its ecosystem plugins.
gotcha AWS SDK credential resolution: If `accessKeyId` and `secretAccessKey` are not explicitly defined in `config/deploy.js`, the plugin will fall back to standard AWS SDK credential resolution methods (e.g., environment variables like `AWS_ACCESS_KEY_ID`, shared credentials file, or IAM roles).
Fix: For production and secure deployments, prioritize using IAM roles for EC2 instances/CI environments or setting AWS credentials as environment variables over hardcoding them in configuration files.
gotcha By default, objects uploaded will have an ACL (Access Control List) of `public-read`. If you do not wish to apply any ACLs, you must explicitly set the `acl` option to `false`.
Fix: In your `config/deploy.js`, explicitly set `ENV['s3-index'].acl = false;` to prevent the plugin from applying any ACLs during upload. Ensure your bucket policy grants appropriate public access if needed.

Install

npm install ember-cli-deploy-s3-index npm
yarn add ember-cli-deploy-s3-index yarn
pnpm add ember-cli-deploy-s3-index pnpm

Imports

Installation
wrong:
```
npm install ember-cli-deploy-s3-index
```
correct:
```
ember install ember-cli-deploy-s3-index
```
Ember CLI plugins are installed using `ember install` to integrate them correctly into the project's build system and hook into the deploy pipeline.

Configuration

// config/deploy.js
ENV['s3-index'] = {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
  bucket: 'your-app-bucket',
  region: 'us-east-1'
};

The plugin is configured via an object under the `ENV['s3-index']` key in your `config/deploy.js`. Use environment variables for sensitive AWS credentials.

Deployment Command
```
ember deploy <environment>
```
The plugin runs automatically as part of the `ember deploy` pipeline once installed and configured. No direct JavaScript `import` or function call is typically made by users.

Quickstart

Demonstrates how to install the plugin and configure it in `config/deploy.js` for an Ember CLI project, preparing for index file deployment to AWS S3.

ember install ember-cli-deploy-s3-index

// Add the following configuration to config/deploy.js
// Ensure ember-cli-deploy-build and ember-cli-deploy-revision-data are also installed and configured.
// For production deployments, strongly recommend using environment variables or AWS profiles for credentials.
ENV['s3-index'] = {
  accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', // Placeholder: set this in your CI/CD or local environment
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '', // Placeholder: set this securely
  bucket: 'my-ember-app-index-bucket',
  region: 'us-east-1',
  prefix: 'app-prefix' // Optional: deploys index.html into a sub-directory within the S3 bucket
};

// To run the deployment:
// Ensure your AWS credentials (e.g., AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) are set as environment variables
// or configured via an AWS profile.
// Execute in your terminal: `ember deploy production`

view raw JSON →