Skip to content

Commit

Permalink
Merge branch 'development' v0.9.0
Browse files Browse the repository at this point in the history
  • Loading branch information
atoa committed Aug 5, 2017
2 parents 5642573 + 1ac170a commit bffca94
Show file tree
Hide file tree
Showing 55 changed files with 3,765 additions and 518 deletions.
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
dist/*.js -diff
dist/*.css -diff
dist/*.map -diff
dist/*.zip -diff
5 changes: 5 additions & 0 deletions .npmignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
build
config
img
lex-web-ui
Makefile
73 changes: 73 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,79 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).

## [0.9.0] - 2017-08-04
This release adds a couple of simplified deployment options:
1. Simplfied CloudFormation stack without a deployment pipeline.
It uses CodeBuild to create the config files and to deploy directly
to S3.
This mode is the new default of the CloudFormation setup so if
you want to keep using the deployment pipeline setup (CodeCommit,
CodeBuild, CodePipeline), you are going to need to explicitly set the
`CreatePipeline` parameter to true.
2. AWS Mobile Hub project file that deploys the Web UI to S3 fronted
by a CloudFront distribution. The Mobile Hub project also creates the
Cognito Identity Pool, Lex Bot and IAM Roles. This allows to deploy the
application from a single file hosted in github.

**NOTE**: At this point, there is a Content-Type issue with the files
deployed using the Mobile Hub project file. The Mobile Hub deployed
files seem to have its content-type set to octect-stream which causes the
browser to download the files instead of rendering. To work around this
issue, you can re-upload the files using the S3 console or aws cli. The
Makefile in the root dir can be used to upload the files with the right
content type. Use the command: `make sync-website` (requires setting
the bucket name with the `WEBAPP_BUCKET` environmental variable). This
issue will be further investigated.

### Added
- Added Mobile Hub deployment
- Added new CloudFormation template `codebuild.yaml` used to deploy the
application without a pipeline
- Added `CreatePipeline` parameter to the master.yaml template to control
whether the stack should create a deployment pipeline
- Added build-time support to set web UI config fields that are commonly
changed using environmental variables. This is in preparation to set
these variables from CloudFormation parameters. The new variables include:
* BOT_INITIAL_TEXT
* BOT_INITIAL_SPEECH
* UI_TOOLBAR_TITLE
* UI_TOOLBAR_LOGO
- Added a new `config` directory in the root of the repo that includes
build configuration
- Added a new `src` directory in the root of the repo to hold the
website files. This includes a modified version of the iframe parent
page and bot-loader that resides in the `lex-web-ui/static/iframe`
directory. Eventualy, this new version should replace, somehow get
merged with the other, or sourced in both places from a single file.
- Added a `server.js` file for quick development and testing. It loads
the sample page from the dist and source directories. It can be used
with the command `npm start` from the root directory. You may need to put
the right values in the config files under `src/config` to make it work.
- Added CloudFormation format statement to all templates files
- Added .npmignore file
- Added sample code on how to use the Vue plugin for including the
component into an existing Vue application

### Changed
- **[BREAKING]** CloudFormation setup now defaults to not creating a
development pipeline and just copy the prebuilt files to an S3 bucket.
To use the pipeline, you now have to set the `CreatePipeline` parameter
to true
- Refactored the build scripts and Makefiles to have better separation
of config and code. The config config used by the Makefiles now resides
under: `config/env.mk`. Some of the names of the Makefile have changed so
you may need to change your environment if you were using the Makefiles
from other script.
- The `update-lex-web-ui-config.js` build script now takes its config from
a node js module in the `config` directory. The config is driven by the
`BUILD_TYPE` environmental variable which controls whether the deployment
is building the app from full source or using the dist dir. For this, the
value of the `BUILD_TYPE` variable can be set to either `full` or `dist`.
- Updated CodeBuild environment to node js v6.3.1 using ubuntu
- Renamed iframe bot.css to bot-loader.css
- Updated dependency versions
- Clarified READMEs

## [0.8.3] - 2017-07-29
### Changed
- Moved default icons from config to sample application
Expand Down
95 changes: 70 additions & 25 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,56 +1,101 @@
# this Makefile is mainly meant to be called from CodeBuild
# or to setup/run the local dev environment
BUILD_DIR := build
# This Makefile is used to configure and deploy the sample app.
# It is used in CodeBuild by the CloudFormation stack.
# It can also be run from a local dev environment.
# It can either deploy a full build or use the prebuilt library in
# in the dist directory

# environment file provides config parameters
CONFIG_ENV := config/env.mk
include $(CONFIG_ENV)

all: build
.PHONY: all

WEBAPP_DIR := ./lex-web-ui
build: config
@echo "[INFO] Building web app in dir [$(WEBAPP_DIR)]"
cd $(WEBAPP_DIR) && npm run build
.PHONY: build

dev: config
@echo "[INFO] Running web app in dev mode"
cd $(WEBAPP_DIR) && npm run dev
.PHONY: dev
BUILD_DIR := build
DIST_DIR := dist
SRC_DIR := src
CONFIG_DIR := $(SRC_DIR)/config
WEBSITE_DIR := $(SRC_DIR)/website

PACKAGE_JSON := $(WEBAPP_DIR)/package.json
install-deps: $(PACKAGE_JSON)
# this install all the npm dependencies needed to build from scratch
install-deps:
@echo "[INFO] Installing npm dependencies"
cd $(WEBAPP_DIR) && npm install
.PHONY: install
.PHONY: install-deps

# BUILD_TYPE controls whether the configuration is done for a full build or
# for using the prebuilt/dist libraries
# Expected values: full || dist
# If empty, probably this is being run locally or from an external script
BUILD_TYPE ?= $()

# updates the config files with values from the environment
UPDATE_CONFIG_SCRIPT := $(BUILD_DIR)/update-lex-web-ui-config.js
export IFRAME_CONFIG ?= $(realpath $(WEBAPP_DIR)/static/iframe/config.json)
export WEBAPP_CONFIG_PROD ?= $(realpath $(WEBAPP_DIR)/src/config/config.prod.json)
export WEBAPP_CONFIG_DEV ?= $(realpath $(WEBAPP_DIR)/src/config/config.dev.json)
CONFIG_FILES := $(IFRAME_CONFIG) $(WEBAPP_CONFIG_PROD) $(WEBAPP_CONFIG_DEV)
export WEBAPP_CONFIG_PREBUILT ?= $(realpath $(SRC_DIR)/config/bot-config.json)
export IFRAME_CONFIG_PREBUILT ?= $(realpath $(CONFIG_DIR)/bot-loader-config.json)
CONFIG_FILES := $(IFRAME_CONFIG) $(WEBAPP_CONFIG_PROD) $(WEBAPP_CONFIG_DEV) \
$(WEBAPP_CONFIG_PREBUILT) $(IFRAME_CONFIG_PREBUILT)
config: $(UPDATE_CONFIG_SCRIPT) $(CONFIG_ENV) $(CONFIG_FILES)
@echo "[INFO] Running config script: [$(<)]"
node $(<)
.PHONY: config

DIST_DIR := $(WEBAPP_DIR)/dist
s3sync:
@echo "[INFO] synching to S3 webapp bucket: [$(WEBAPP_BUCKET)]"
aws s3 sync --acl public-read "$(DIST_DIR)" "s3://$(WEBAPP_BUCKET)/"
.PHONY: s3sync
build: config
@echo "[INFO] Building web app in dir [$(WEBAPP_DIR)]"
cd $(WEBAPP_DIR) && npm run build
.PHONY: build

s3deploy:
# used by the Pipeline deployment mode when building from scratch
WEBAPP_DIST_DIR := $(WEBAPP_DIR)/dist
CODEBUILD_BUILD_ID ?= none
deploy-to-s3:
@[ "$(WEBAPP_BUCKET)" ] || \
(echo "[ERROR] WEBAPP_BUCKET env var not set" ; exit 1)
@echo "[INFO] deploying to S3 webapp bucket: [$(WEBAPP_BUCKET)]"
@echo "[INFO] copying build: [$(CODEBUILD_BUILD_ID)]"
aws s3 cp --recursive "$(DIST_DIR)" \
aws s3 cp --recursive "$(WEBAPP_DIST_DIR)" \
"s3://$(WEBAPP_BUCKET)/builds/$(CODEBUILD_BUILD_ID)/"
@echo "[INFO] copying new version"
aws s3 cp --recursive --acl public-read \
"s3://$(WEBAPP_BUCKET)/builds/$(CODEBUILD_BUILD_ID)/" \
"s3://$(WEBAPP_BUCKET)/"
@[ "$(PARENT_PAGE_BUCKET)" ] && \
( echo "[INFO] synching parent page to bucket: [$(PARENT_PAGE_BUCKET)]" ; \
aws s3 sync --acl public-read "$(DIST_DIR)/static/iframe" \
aws s3 sync --acl public-read "$(WEBAPP_DIST_DIR)/static/iframe" \
"s3://$(PARENT_PAGE_BUCKET)/static/iframe" ) || \
echo "[INFO] no parent bucket to deploy"
@echo "[INFO] all done deploying"
.PHONY: s3deploy
.PHONY: deploy-to-s3

# Run by CodeBuild deployment mode when which uses the prebuilt libraries
# Can also be used to easily copy local changes to a bucket
# (e.g. mobile hub created bucket)
# It avoids overwriting the aws-config.js file when using outside of a build
sync-website:
@[ "$(WEBAPP_BUCKET)" ] || \
(echo "[ERROR] WEBAPP_BUCKET variable not set" ; exit 1)
@echo "[INFO] copying libary files"
aws s3 sync --acl public-read \
--exclude Makefile \
--exclude lex-web-ui-mobile-hub.zip \
$(DIST_DIR) s3://$(WEBAPP_BUCKET)
@echo "[INFO] copying website files"
aws s3 sync --acl public-read \
$(WEBSITE_DIR) s3://$(WEBAPP_BUCKET)
@echo "[INFO] copying config files"
aws s3 sync --acl public-read \
--exclude '*' \
--include 'bot-*config.json' \
$(CONFIG_DIR) s3://$(WEBAPP_BUCKET)
@[ "$(BUILD_TYPE)" = 'dist' ] && \
echo "[INFO] copying aws-config.js" ;\
aws s3 sync --acl public-read \
--exclude '*' \
--include 'aws-config.js' \
$(CONFIG_DIR) s3://$(WEBAPP_BUCKET)
@echo "[INFO] all done deploying"
.PHONY: sync-website
131 changes: 101 additions & 30 deletions README.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,108 @@
> Sample Amazon Lex Web Interface
## Overview
This repository provides a sample [Amazon Lex](https://aws.amazon.com/lex/)
web interface that can be integrated in your website. This web interface
allows to interact with a Lex bot directly from a browser using by text
or voice (from a webRTC capable browser).
Here is a screenshot of it:
This is a sample [Amazon Lex](https://aws.amazon.com/lex/)
web interface. It provides a chatbot UI component that can be integrated
in your website. The interface allows to interact with a Lex bot directly
from a browser using text or voice (on webRTC capable browsers).

<img src="./img/webapp-screenshot.png" width=480>
## Quick Launch
Click the button below to test drive this project using
[AWS Mobile Hub](https://aws.amazon.com/mobile/).
It will deploy the chatbot UI to
[S3](https://aws.amazon.com/s3/) and
[CloudFront](https://aws.amazon.com/cloudfront/). It also deploys
the sample [Order Flowers Lex bot](http://docs.aws.amazon.com/lex/latest/dg/gs-bp-create-bot.html)
automatically for you.

<p>
<a target="_blank" href="https://console.aws.amazon.com/mobilehub/home?#/?config=https://github.com/awslabs/aws-lex-web-ui/blob/master/dist/lex-web-ui-mobile-hub.zip">
<span>
<img height="100%" src="https://s3.amazonaws.com/deploytomh/button-deploy-aws-mh.png"/>
</span>
</a>
</p>

**NOTE**: If the Mobile Hub deployed site causes the browser to download
the files instead of rendering it, you can re-upload the files to the
S3 bucket using the S3 console or aws cli.

## Integrating into your Site
You can consume this project as a library that renders the chatbot
UI component in your site. The library can be included in your web
application by importing it as a module in a
[webpack](https://webpack.github.io/)
based project or by directly sourcing it in an HTML `<script>` tag.
Additionally, this project provides a set of
[AWS CloudFormation](https://aws.amazon.com/cloudformation/) templates
that can be used to automatically build and deploy the chatbot UI and
related resources.

### Script Tag
This project provides a pre-built version of the library under the
[dist](dist) directory. You can copy the JavaScript and CSS files from
that directory to your web server and use them to load the chatbot
UI. Similarly, for quick testing, you could directly source the library
and other dependencies from a CDN distribution.

You would need to pass required parameters such as the
[Amazon Cognito Identity Pool](http://docs.aws.amazon.com/cognito/latest/developerguide/identity-pools.html) and Lex bot when you instantiate the
component. See an example here: [index.html](dist/index.html).
This project provides a sample page showing how to load the chatbot
UI and related dependencies in a full page. There is also a sample
page showing how to load the chatbot UI into an existing site
using an iframe. These pages and their configuration can be
automatically deployed using the Mobile Hub button above.

This project also provides a set of
[AWS CloudFormation](https://aws.amazon.com/cloudformation/)
templates that can be used to automatically build and deploy the chatbot
UI and related resources. Additionally, you can consume this project as an
[npm](https://www.npmjs.com/) package that provides a component library.


### Full Page
To display the chatbot UI as a full page, you can use the JavaScript
and CSS files in the [dist](dist) directory. You can copy those files
to your web server or host them in an S3 bucket. The JavaScript and CSS
can be loaded in a web page by including them with `script` and `link`
HTML tags.

<img src="./img/webapp-full.gif" width=600>

The chatbot UI component depends on libraries that should also be
loaded in the page. For quick testing, you could directly source these
dependencies from a CDN distribution. A sample page illustrating this
setup is found in here: [index.html](src/website/index.html).

#### Configuration
You need to pass the chatbot UI configuration including
required parameters such as the [Amazon Cognito Identity
Pool](http://docs.aws.amazon.com/cognito/latest/developerguide/identity-pools.html)
and Lex bot name. The [index.html](src/website/index.html)
sample page loads this configuration from the both the
[bot-config.json](src/config/bot-config.json) and Mobile Hub AWS SDK
[aws-config.js](src/config/aws-config.js) files. You can modify the values
in those files to change the chatbot UI configuration. When deploying
with Mobile Hub or with the CloudFormation templates described below,
the configuration will be done automatically for you. For details about
the component configuration, see the
[Configuration and Customization](https://github.com/awslabs/aws-lex-web-ui/tree/master/lex-web-ui#configuration-and-customization)
section of its README file.

#### Running Locally
If you want to quickly test the [src/website](src/website) pages on
your local host, modify the values in the `bot-config.json` and/or
`aws-config.js` files under the `src/config` directory. Specifically,
you would need to pass a Cognito Pool Id and Lex Bot name. If
you deploy the site using Mobile Hub or CloudFormation, you can
copy the configuration files from the S3 buckets automatically
created in there. After you setup the configuration files in
the `src/config` directory, issue the command: `npm start`. For
a more advanced local host test, see the
[Dependencies and Build Setup](https://github.com/awslabs/aws-lex-web-ui/tree/master/lex-web-ui#dependencies-and-build-setup)
documentation of the component.

### Iframe
You can embed the *Full Page* setup described above in an iframe to
display it on your site as a chatbot widget. This project provides a
sample page showing this setup here:
[parent.html](src/website/parent.html). This includes a loader script
that creates an API between the iframe and the parent page. For details,
see its:
[README](https://github.com/awslabs/aws-lex-web-ui/tree/master/lex-web-ui/static/iframe).

<img src="./img/webapp-iframe.gif" width=600>

### Npm Install
You can use the [npm](https://docs.npmjs.com/)
command to install this project. The npm install provides a library that
you can import as a module into your JavaScript code.
you can import as a module into your JavaScript code. The library can
be npm installed in your web application and imported as a module in a
[webpack](https://webpack.github.io/) based project. The component is
built as a reusable [Vue.JS](https://vuejs.org/) plugin. The library
bundle files are found under the [dist](dist) directory.


Package installation using `npm`:

Expand All @@ -55,6 +123,8 @@ You can then import the library in your project:
import LexWebUi from 'aws-lex-web-ui';
// or using require
var LexWebUi = require('aws-lex-web-ui');
// import the debug non-minimized version
import LexWebUi from 'aws-lex-web-ui/dist/lex-web-ui';
```

### CloudFormation Deployment
Expand All @@ -64,6 +134,7 @@ the accompanying [templates](templates) directory and its

## Details
The source of the chatbot UI component resides under the
[lex-web-ui](lex-web-ui) directory. The library provided here packages
this component and distributes it as a pre-built library. For details
about the chatbot UI component, see its [README](lex-web-ui/README.md)
[lex-web-ui](lex-web-ui) directory. The library provided in the
[dist](dist) directory packages this component and distributes it as
a pre-built bundle. For details about the chatbot UI component and its
configuration, see its [README](lex-web-ui/README.md) file.
6 changes: 5 additions & 1 deletion build/Makefile
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# This Makefile is used to update the bootstrap bucket containing
# the project source and CloudFormation templates

# environment file controls config parameters
CONFIG_ENV := ./config.env
CONFIG_ENV := ../config/env.mk
include $(CONFIG_ENV)

# cfn templates
Expand Down Expand Up @@ -31,6 +34,7 @@ upload-templates: $(TEMPLATES) | $(OUT)
aws s3 sync --acl public-read --exclude "*" --include "*.yaml" \
"$(TEMPLATES_DIR)" "s3://$(BOOTSTRAP_BUCKET_PATH)/templates/" \
| tee "$(OUT)/$(@)"
@echo "[INFO] master template: https://s3.amazonaws.com/$(BOOTSTRAP_BUCKET_PATH)/templates/master.yaml"

# cfn custom resource lambda files are found under this directory
CUSTOM_RESOURCES_DIR := $(TEMPLATES_DIR)/custom-resources
Expand Down
Loading

0 comments on commit bffca94

Please sign in to comment.