Merge branch 'development' v0.9.0

Author: atoa

.gitattributes

@@ -1,3 +1,4 @@
 dist/*.js -diff
 dist/*.css -diff
 dist/*.map -diff
+dist/*.zip -diff

.npmignore

@@ -0,0 +1,5 @@
+build
+config
+img
+lex-web-ui
+Makefile

CHANGELOG.md

@@ -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

Makefile

@@ -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

README.md

@@ -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`:
 
@@ -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
@@ -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.

build/Makefile

@@ -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
@@ -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