This application uses AWS managed services to process images from IP cameras with AI and trigger actions.
THIS IS AN EXPERIMENTAL PROJECT AND MUST NOT BE CONSIDERED AS A RELIABLE, TRUSTWORTHY SOFTWARE TO DEPEND ON. IT COMES WITH NO WARRANTY OF ANY KIND, USE IT AT YOUR OWN RISK. DO NOT USE IT IN ANY "PRODUCTION", "LIVE" or "MISSION-CRITICAL" ENVIRONMENT AND DO NOT EXPECT IT TO EITHER PROTECT YOUR SAFETY, THE SAFETY OF OTHERS OR THE SAFETY OF YOUR PROPERTIES. PLEASE ALSO READ THE LICENSE CAREFULLY BEFORE INSTALLING AND RUNNING THE CODE.
dev
- development branch, latest and greatest version of the code that shoud not be expected to workmaster
- distribution branch, this code is expected to work (NO WARRANTIES GIVEN, PLEASE READ THE DISCLAMER PARAGRAPH!)
- 1+ IP cameras able to send e-mails with attached pictures (triggered by any event of your choice)
- An Internet Domain Name to set up a recipient e-mail address with
- An
Amazon Web Services (AWS)
account Python 3.7.x
Terraform
- (optional) A
SendGrid
account
Assuming that all the Prerequisites are met and AWS
tools have been
installed and configured
on your machine, deploying this application is as easy as running:
$ cd terraform
$ terraform init
$ terraform apply
You will be prompted to input a few settings. If you opted to use SendGrid
to
receive and send e-mails, you will also need to manually set up your SendGrid
account
and Inbound Parse Webhook
, pointing it to the AWS
Lambda
API Gateway
URL
provisioned during the installation. For more information, please see:
- https://sendgrid.com/docs/API_Reference/Parse_Webhook/inbound_email.html
- https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/
Terraform
supports several means of providing credentials for authentication.
The most safe and convenient ways of providing said credentials are:
- Environment variables
- Shared credentials file
DO NOT statically store credentials in
Terraform
plans. They could be accidentally committed to a repository.
Terraform
will automatically try to read default credentials from the environment variables
or the shared credentials file. Such information can be manually overridden from the command line:
$ AWS_PROFILE=my_profile AWS_DEFAULT_REGION=eu-west-1 terraform plan
Please see the AWS documentation linked above and the
Terraform AWS provider
documentation
for more information.
By default the included Terraform
plan
will store its
state
locally.
In order to safely store your state remotely, have an automated backup
and manage your installation from multiple computers, you can enable the
S3 backend
uncommenting (and updating, if needed) its configuration
in the main.tf
file. For more information, please read the
S3 backend
documentation.
Inbound e-mails can either be received through Amazon Amazon Simple Email Service (SES)
or SendGrid
.
Please note that at the time of writing all new mail domains
created in SES
are put in sandbox mode. In order to send
mails, recipients MUST be verified from the SES
console first
(after the SES
domain has been provisioned).
See: https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html
In order to prevent abuse and unwanted charges, this application
enforces rate limiting on the API Gateway
(used for SendGrid
).
Check the terraform/api_gateway.tf
file for details. Also, do not forget to set an
AWS Budget
on your account to automatically monitor the costs.
From the project root, run:
$ cd lambda
$ python -m unittest discover -s test
Image attachments are extracted from the message body and passed to Rekognition
as a base64-encoded byte stream. Limits apply, see the
official documentation
on the AWS
website for details.
The SES
domain
needs to be validated before it can be used. Validation is
achieved through a DNS
record that MUST be set to a SES
-provided value.
SES
will read this record from the domain
DNS
records and validate it
to prove that you actually own the domain
.
For this to work, the local DNS
client MUST be able to read the DNS
records for the domain
and look for the validation record.
If you have registered a domain in Route 53
itself, this should work
out-of-the-box. If you have registered a domain
with a third-party registrar,
after the Hosted Zone
is created you will need to get the NS
records values
for the Hosted Zone
from Route 53
and update them in your domain registrar's
configuration dashboard. It will possibly take some time for local DNS
client
to get the updated NS
records and be able to verify the SES
domain
.
In this case, if the plan
fails (timing out) while you update the NS
records
and wait for the update to be propagated, just re-apply the plan
at a later
time and it will work.
If $ terraform apply
yields the following error:
Error: Error applying plan:
1 error(s) occurred:
* data.archive_file.lambda_release: data.archive_file.lambda_release: error archiving directory: could not archive missing directory: /{...}/../.deploy
the temporary .zip
file containing the Lambda
function code was deleted. The Terraform
plan
is
configured to package the Lambda
function if it detects changes to the source code files. You can repackage
the Lambda
function manually:
$ cd ../lambda
$ shovel package nozip
then re-apply the plan
.
The following pages provided valuable documentation to build this project:
- https://anil.io/blog/aws/use-ses-lambda-mail-server-with-custom-domain-to-receive-emails/
- https://github.com/martysweet/aws-lambda-attachment-extractor
- https://github.com/alexbiship/lambda-ses-s3
- https://github.com/onnimonni/terraform-ses-lambda-demo
- https://github.com/cloudposse/terraform-aws-ses-lambda-forwarder
- https://learn.hashicorp.com/terraform/aws/lambda-api-gateway#configuring-api-gateway