Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/k1LoW/serverless-s3-sync
A plugin to sync local directories and S3 prefixes for Serverless Framework :zap:
https://github.com/k1LoW/serverless-s3-sync
aws s3 serverless-framework
Last synced: about 2 months ago
JSON representation
A plugin to sync local directories and S3 prefixes for Serverless Framework :zap:
- Host: GitHub
- URL: https://github.com/k1LoW/serverless-s3-sync
- Owner: k1LoW
- Created: 2017-07-26T09:20:05.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-01T01:41:36.000Z (4 months ago)
- Last Synced: 2024-10-19T13:25:11.701Z (2 months ago)
- Topics: aws, s3, serverless-framework
- Language: JavaScript
- Homepage:
- Size: 556 KB
- Stars: 183
- Watchers: 4
- Forks: 70
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Serverless S3 Sync [](https://www.npmjs.com/package/serverless-s3-sync)
> A plugin to sync local directories and S3 prefixes for Serverless Framework :zap: .
## Use Case
- Static Website ( `serverless-s3-sync` ) & Contact form backend ( `serverless` ) .
- SPA ( `serverless` ) & assets ( `serverless-s3-sync` ) .
## Install
Run `npm install` in your Serverless project.
```sh
$ npm install --save serverless-s3-sync
```
Add the plugin to your serverless.yml file
```yaml
plugins:
- serverless-s3-sync
```
### Compatibility with Serverless Framework
Version 2.0.0 is compatible with Serverless Framework v3, but it uses the legacy logging interface. Version 3.0.0 and later uses the [new logging interface](https://www.serverless.com/framework/docs/guides/plugins/cli-output).
|serverless-s3-sync|Serverless Framework|
|---|---|
|v1.x|v1.x, v2.x|
|v2.0.0|v1.x, v2.x, v3.x|
|≥ v3.0.0|v3.x|
## Setup
```yaml
custom:
s3Sync:
# A simple configuration for copying static assets
- bucketName: my-static-site-assets # required
bucketPrefix: assets/ # optional
localDir: dist/assets # required
# An example of possible configuration options
- bucketName: my-other-site
localDir: path/to/other-site
deleteRemoved: true # optional, indicates whether sync deletes files no longer present in localDir. Defaults to 'true'
acl: public-read # optional
followSymlinks: true # optional
defaultContentType: text/html # optional
params: # optional
- index.html:
CacheControl: 'no-cache'
- "*.js":
CacheControl: 'public, max-age=31536000'
bucketTags: # optional, these are appended to existing S3 bucket tags (overwriting tags with the same key)
tagKey1: tagValue1
tagKey2: tagValue2
# This references bucket name from the output of the current stack
- bucketNameKey: AnotherBucketNameOutputKey
localDir: path/to/another
# ... but can also reference it from the output of another stack,
# see https://www.serverless.com/framework/docs/providers/aws/guide/variables#reference-cloudformation-outputs
- bucketName: ${cf:another-cf-stack-name.ExternalBucketOutputKey}
localDir: path
# Setting the optional enabled field to false will disable this rule.
# Referencing other variables allows this rule to become conditional
- bucketName: DisabledSync
localDir: path
enabled: false
resources:
Resources:
AssetsBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: my-static-site-assets
OtherSiteBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: my-other-site
AccessControl: PublicRead
WebsiteConfiguration:
IndexDocument: index.html
ErrorDocument: error.html
AnotherBucket:
Type: AWS::S3::Bucket
Outputs:
AnotherBucketNameOutputKey:
Value: !Ref AnotherBucket
```
## Usage
Run `sls deploy`, local directories and S3 prefixes are synced.
Run `sls remove`, S3 objects in S3 prefixes are removed.
Run `sls deploy --nos3sync`, deploy your serverless stack without syncing local directories and S3 prefixes.
Run `sls remove --nos3sync`, remove your serverless stack without removing S3 objects from the target S3 buckets.
### `sls s3sync`
Sync local directories and S3 prefixes.
### Offline usage
If also using the plugins `serverless-offline` and `serverless-s3-local`, sync can be supported during development by placing the bucket configuration(s) into the `buckets` object and specifying the alterate `endpoint` (see below).
```yaml
custom:
s3Sync:
# an alternate s3 endpoint
endpoint: http://localhost:4569
buckets:
# A simple configuration for copying static assets
- bucketName: my-static-site-assets # required
bucketPrefix: assets/ # optional
localDir: dist/assets # required
# ...
```
As per [serverless-s3-local's instructions](https://github.com/ar90n/serverless-s3-local#triggering-aws-events-offline), once a local credentials profile is configured, run `sls offline start --aws-profile s3local` to sync to the local s3 bucket instead of Amazon AWS S3
> `bucketNameKey` will not work in offline mode and can only be used in conjunction with valid AWS credentials, use `bucketName` instead.
run `sls deploy` for normal deployment
### Always disable auto sync
```yaml
custom:
s3Sync:
# Disable sync when sls deploy and sls remove
noSync: true
buckets:
# A simple configuration for copying static assets
- bucketName: my-static-site-assets # required
bucketPrefix: assets/ # optional
localDir: dist/assets # required
# ...
```
### Sync on other hooks
```yaml
custom:
s3Sync:
hooks:
# This hook will run after the deploy:finalize hook
- after:deploy:finalize
buckets:
# A simple configuration for copying static assets
- bucketName: my-static-site-assets # required
bucketPrefix: assets/ # optional
localDir: dist/assets # required
# ...
```