Added detailed documentation for building MXNet and other minor changes

README.md

@@ -18,16 +18,16 @@ In order to complete this workshop you'll need an AWS Account, and an AWS IAM us
 - AWS CodeBuild
 - AWS CodePipeline
 - AWS CodeDeploy
-- AWS CloudWatch event
+- Amazon CloudWatch
 
 **Use Your Own Account:** The code and instructions in this workshop assume only one student is using a given AWS account at a time. If you try sharing an account with another student, you'll run into naming conflicts for certain resources. You can work around these by appending a unique suffix to the resources that fail to create due to conflicts, but the instructions do not provide details on the changes required to make this work. Use a personal account or create a new AWS account for this workshop rather than using an organization’s account to ensure you have full access to the necessary services and to ensure you do not leave behind any resources from the workshop.
 
-**Costs:** Some, but NOT all, of the resources you will launch as part of this workshop are eligible for the AWS free tier if your account is less than 12 months old. See the **[AWS Free Tier](https://aws.amazon.com/free/)** page for more details. To avoid charges for endpoints and other resources you might not need after you've finished a workshop, please refer to the **[Cleanup Guide](https://github.com/awslabs/amazon-sagemaker-workshop/blob/master/CleanupGuide)**.
+**Costs:** Some, but NOT all, of the resources you will launch as part of this workshop are eligible for the AWS free tier if your account is less than 12 months old. See the **[AWS Free Tier](https://aws.amazon.com/free/)** page for more details. To avoid charges for endpoints and other resources you might not need after you've finished a workshop, please refer to this **[Cleanup Guide](https://github.com/awslabs/amazon-sagemaker-workshop/blob/master/CleanupGuide)**.
 
 
 ### AWS Region
 
-SageMaker is not available in all AWS Regions at this time.  Accordingly, we recommend running this workshop in one of the following supported AWS Regions:  N. Virginia, Oregon, Ohio, or Ireland. However, the instructions assume the selected region is **N. Virginia**.
+Amazon SageMaker is available in the following AWS Regions:  N. Virginia, Oregon, Ohio, Ireland, Frankfurt, Seoul, Sydney, Tokyo and AWS GovCloud (US). However, the instructions assume the selected region is **N. Virginia**.
 
 Once you've chosen a region, you should create all of the resources for this workshop there, including a new Amazon S3 bucket and a new SageMaker notebook instance. Make sure you select your region from the dropdown in the upper right corner of the AWS Console before getting started.
 

building/README.md

@@ -1,28 +1,80 @@
-#Compiling MXNet
+# Build the Apache MXNet deployment package for AWS Lambda
 
-In order to compile MXNet for the Lambda function, you would need an environment running the AMI that the Lambda service is using. Currently the version is:
+In the previous sections of the workshop, and more specifically while executing the steps related to hosting in AWS Lambda, we have been using the contents of a GitHub repository to download the libraries required to run Apache MXNet in a Lambda function.  
 
-AMI – amzn-ami-hvm-2017.03.1.20170812-x86_64-gp2
+This section will show how to build the deployment package for an AWS Lambda function from scratch, by compiling the Apache MXNet framework libraries for the Lambda execution environment.
+This is required since there isn't yet a pre-compiled release package of Apache MXNet that would run smoothly in a Lambda function.
+Once the package is ready, it will be enough to add the Lambda handler to be ready to use MXNet in Lambda for hosting models and executing inferences.
 
-https://docs.aws.amazon.com/lambda/latest/dg/current-supported-versions.html
+The instructions in this section assume that you already have familiarity with Amazon EC2 service to execute operations like starting a new instance, configure the security groups, logging in through SSH and terminating it. In case you are not experienced with these tasks, you can refer to the wizards below:
 
+- [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html)
+- [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html)
+- [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html)
+
+## Launch an Amazon EC2 instance with the proper AMI
+
+In order to compile MXNet for the Lambda function, you would need an environment running the AMI that the Lambda service is using. The current version is:
+
+**amzn-ami-hvm-2017.03.1.20170812-x86_64-gp2**
+
+We suggest double-checking that the current version is still the one above by visiting 
+[https://docs.aws.amazon.com/lambda/latest/dg/current-supported-versions.html](https://docs.aws.amazon.com/lambda/latest/dg/current-supported-versions.html).
+
+You will have to launch an Amazon EC2 instance with that AMI and then access it by using an SSH client.
+
+## Install the required libraries
+
+First, install development tools and the libraries required to compile MXNet. Apache MXNet requires several libraries as prerequisites. In this tutorial we will be using:
+
+- **Atlas** (Linear Algebra Library) [http://math-atlas.sourceforge.net/](http://math-atlas.sourceforge.net/)
+- **OpenBlas** (Basic Linear Algebra Subprograms) [https://www.openblas.net/](https://www.openblas.net/)
+- **Lapack** (Linear Algebra Package) [http://www.netlib.org/lapack/](http://www.netlib.org/lapack/)
+
+We are NOT going to use OpenCV, required by MXNet for image processing functions, and NVIDIA CUDA / cuDNN since we do not need to run Apache MXNet with GPU support.
+
+If you want to know more on the dependencies and options to build Apache MXNet from sources, please visit (https://mxnet.incubator.apache.org/install/build\_from\_source.html)[https://mxnet.incubator.apache.org/install/build\_from\_source.html].
+
+Execute the following commands in your home folder:
 
 ```
 sudo yum groupinstall -y "Development Tools" && sudo yum install -y git
 
 sudo yum install atlas-devel
 
 sudo yum install openblas openblas-devel.x86_64 lapack-devel.x86_64
+```
+
+## Build Apache MXNet
 
+We are now ready to build Apache MXNet from sources. We are going to get the sources from the GitHub repository where MXNet is maintained and then build with the proper settings.
+
+```
 git clone --recursive https://github.com/apache/incubator-mxnet mxnet
 cd mxnet
 
 make -j $(nproc) USE_OPENCV=0 USE_CUDNN=0 USE_CUDA=0 USE_BLAS=openblas USE_LAPACK=1
+```
+
+## Install language bindings
 
+When the build process is completed, we will need to install the Python bindings as we want to use Python as programming language. All language bindings supported by MXNet are configured after building the framework, except C++ that needs to be included during the compilation.
+
+To install language bindings, execute the following commands:
+
+```
 cd python
 
 sudo python setup.py install
+```
 
+## Build the package
+
+Once the bindings are installed, we are ready to build a package that will contain all the relevant libraries to run MXNet in Lambda.
+
+Please note that these instructions assume using the latest version of Apache MXNet and Numpoy, which, at the time being, are 1.3.1 and 1.15.2. This means that, if a new version is released, you might have to update the paths below.
+
+```
 cd
 
 mkdir mxnetpackage
@@ -63,8 +115,20 @@ cp /usr/lib64/atlas/libptf77blas.so.3 lib/
 
 cp /usr/lib64/libquadmath.so.0 lib/
 
+```
+
+## Save the package
+
+We are now going to compress and save the package to Amazon S3 as the final step.
+
+```
 tar cfz mxnet.tar.gz *
 
 aws s3 cp mxnet.tar.gz s3://{your_bucket}/
 
-```
+```
+
+Now you can run a test by creating an AWS Lambda function starting from the package content and write a simple Python lambda handler that executes some basic MXNet code.
+
+Finally, after ensuring the package works as expected, you can terminate the EC2 instance to avoid incurring in unexpected charges.
+