Version 3.1.0

README.md

@@ -2,30 +2,73 @@
 A solution to dynamically handle images on the fly, utilizing Thumbor (thumbor.org).
 Published version, additional details and documentation are available here: https://aws.amazon.com/answers/web-applications/serverless-image-handler/
 
-## OS/Python Environment Setup
+_Note:_ it is recommend to build the application binary on Amazon Linux.
+
+## Running unit tests for customization
+* Clone the repository, then make the desired code changes
+* Next, run unit tests to make sure added customization passes the tests
+```
+cd ./deployment
+chmod +x ./run-unit-tests.sh  \n
+./run-unit-tests.sh \n
+```
+
+## Building distributable for customization
+* Configure the bucket name of your target Amazon S3 distribution bucket
+```
+export TEMPLATE_OUTPUT_BUCKET=my-bucket-name # bucket where cfn template will reside
+export DIST_OUTPUT_BUCKET=my-bucket-name # bucket where customized code will reside
+export VERSION=my-version # version number for the customized code
+```
+_Note:_ You would have to create 2 buckets, one named 'my-bucket-name' and another regional bucket named 'my-bucket-name-<aws_region>'; aws_region is where you are testing the customized solution. Also, the assets  in bucket should be publicly accessible.
+
+* OS/Python Environment Setup
 ```bash
+yum install yum-utils epel-release -y
 sudo yum-config-manager --enable epel
 sudo yum update -y
-sudo yum install git libpng-devel libcurl-devel gcc python-devel libjpeg-devel -y
-sudo pip install --upgrade pip
+sudo yum install zip wget git libpng-devel libcurl-devel gcc python-devel libjpeg-devel -y
 alias sudo='sudo env PATH=$PATH'
-sudo  pip install --upgrade setuptools
-sudo pip install --upgrade virtualenv
+sudo pip install setuptools==39.0.1
+sudo pip install virtualenv==15.2.0
+```
+* Clone the github repo
+```bash
+git clone https://github.com/awslabs/serverless-image-handler.git
 ```
 
-## Building Lambda Package
+* Navigate to the deployment folder
 ```bash
-cd deployment
-./build-s3-dist.sh source-bucket-base-name
+cd serverless-image-handler/deployment
 ```
-source-bucket-base-name should be the base name for the S3 bucket location where the template will source the Lambda code from.
-The template will append '-[region_name]' to this value.
-For example: ./build-s3-dist.sh solutions
-The template will then expect the source code to be located in the solutions-[region_name] bucket
 
-## CF template and Lambda function
-Located in deployment/dist
+* Now build the distributable
+```bash
+sudo ./build-s3-dist.sh $DIST_OUTPUT_BUCKET $VERSION
+```
 
+* Deploy the distributable to an Amazon S3 bucket in your account. Note: you must have the AWS Command Line Interface installed.
+```bash
+aws s3 cp ./dist/ s3://$DIST_OUTPUT_BUCKET-[region_name]/serverless-image-handler/$VERSION/ --recursive --exclude "*" --include "*.zip"
+aws s3 cp ./dist/serverless-image-handler.template s3://$TEMPLATE_OUTPUT_BUCKET/serverless-image-handler/$VERSION/
+```
+_Note:_ In the above example, the solution template will expect the source code to be located in the my-bucket-name-[region_name] with prefix serverless-image-handler/my-version/serverless-image-handler.zip
+
+* Get the link of the serverless-image-handler.template uploaded to your Amazon S3 bucket.
+* Deploy the Serverless Image Handler solution to your account by launching a new AWS CloudFormation stack using the link of the serverless-image-handler.template
+```bash
+https://s3.amazonaws.com/my-bucket-name/serverless-image-handler/my-version/serverless-image-handler.template
+```
+
+## SafeURL hash calculation
+* For hash calculation with safe URL, use following snippet to find signed_path value
+```bash
+http_key='mysecuritykey' # security key provided to lambda env variable
+http_path='200x200/smart/sub-folder/myimage.jpg' # sample options for myimage
+hashed = hmac.new(str(http_key),str(http_path),sha1)
+encoded = base64.b64encode(hashed.digest())
+signed_path = encoded.replace('/','_').replace('+','-')
+```
 
 ***