Aliyun OSS static files upload for serverless

Installation

npm install --save serverless-aliyun-oss

Dependencies

This plugin needs serverless-aliyun-function-compute installed and configured to be able to interact with Aliyun.

Notice on usage in Mainland China

Even if the files are uploaded to OSS, they are not usable right away, a CDN needs to be bound to it to be able to access them directly as indicated in an Aliyun communication.

Other regions, such as HongKong allow direct access to the files as normal HTML pages.

Usage

First, update your serverless.yml by adding the following:

plugins:
  - serverless-aliyun-function-compute
  - serverless-aliyun-oss

Second, Create a website folder in the root directory of your Serverless project. This is where your distribution-ready website should live. By default the plugin expects the files to live in a folder called client/dist. But this is configurable with the distributionFolder option (see the Configuration Parameters below).

The plugin uploads the entire distributionFolder to S3 and configures the bucket to host the website and make it publicly available, also setting other options based the Configuration Parameters specified in serverless.yml.

Third, run the plugin, and visit your new website!

serverless client deploy

WARNING: The plugin will overwrite any data you have in the bucket name you set above if it already exists.

If later on you want to take down the website you can use:

serverless client remove

Configuration Parameters

domain

optional, default null

custom:
  client:
    domain: example.com

Use this parameter to specify the domain used for the CDN configuration to allow access to the OSS static site. If not specified, no CDN will be created.

cdnScope

optional, default global

custom:
  client:
    cdnScope: overseas

Use this parameter to specify the scope used for the CDN configuration to allow access to the OSS static site.

Possible values:

• domestic - Only within Mainland China
• global - Both Mainland China and Overseas
• overseas - Outside Mainland China only (Does not require ICP)

Notice: If you want to use global or domestic, the domain you are using needs to have an ICP license.

bucketName

optional, default: sls-{aliyun_account_id}-client

custom:
  client:
    bucketName: unique-oss-bucketname

Use this parameter to specify a unique name for the OSS bucket that your files will be uploaded to.

distributionFolder

optional, default: client/dist

custom:
  client:
    ...
    distributionFolder: path/to/files
    ...

Use this parameter to specify the path that contains your website files to be uploaded. This path is relative to the path that your serverless.yaml configuration files resides in.

indexDocument

optional, default: index.html

custom:
  client:
    ...
    indexDocument: file-name.ext
    ...

The name of your index document inside your distributionFolder. This is the file that will be served to a client visiting the base URL for your website.

errorDocument

optional, default: error.html

custom:
  client:
    ...
    errorDocument: file-name.ext
    ...

CLI Parameters

The region can be specified as a CLI parameter, like for the serverless-aliyun-function-compute plugin.

For example:

serverless client deploy --region cn-hongkong

Acknowledgements

This package has been inspired by serverless-finch and uses a similar configuration.