In a nutshell, ``hugo-mx-gateway`` provides a RESTful POST endpoint for static contact/demo request pages. It's a simple, yet a powerful tool for this only-designed purpose.
Did you ever experience building a static website (e.g. using [Hugo](https://gohugo.io/) or whatever alternative), then did get stuck when coming the time to add a contact/demo request form?
This project, namely `hugo-mx-gateway`, is meant to provide a RESTful endpoint that adds the dynamicity required to handle contact/demo requests for static web sites. It's a simple, yet a powerful tool for this only-designated purpose.
* Create an HTML form with a POST action pointing towards the `hugo-mx-gateway` service. This service is a RESTful HTTP POST endpoint backed by an application easily deployable on [Google App Engine](https://cloud.google.com/appengine), Kubernetes, and Docker engines.
* For each form request, `hugo-mx-gateway` retrieves information submitted by the user (email, subject, message details...), then it **automatically generates and sends** a **templated email** towards the user-provided email address, while **bcc**ing a copy of that email to an address that you do define for internal tracking and follow up.
* Once a request is processed (upon success or failure), `hugo-mx-gateway` copes with the reply towards the origin web site (static page) by redirecting the browser to the originated page with additional URL parameters describing the status of the processing (e.g. `/contact.html?status=success&message=request%20submitted`). With this, you can then add a few lines of Javascript to retrieve and display the reply message on the page.
*`hugo-mx-gateway` is shipped with a sample HTML form including some common fields for contact and demo requests, as well as a sample Javascript code to handle the processing response. That said, this is a open source software, so you're free to adapt it for your specific use cases.
* Deployment platform: Google App Engine, a Kubernetes cluster, or a Docker machine.
* An SMTP account along with the server supporting TLS. While it can be tempting to use a personal account, it's highly recommended to not do that for an internet-hosted service. Therefore, according to your situation, you may need to ask for an SMTP account to your corporate's IT staff. If you're an individual or a small business, you can opt for a cloud-based SMTP service like SendGrid, Mailgun, and Mailjet--they all offer free tier for small usage.
* Note that the `hugo-mx-gateway`'s pod is run in an unprivileged mode with a **Security Context**.
* First check the Helm's [values.yaml](./helm/values.yaml) file to set [configuration options](#configuration-variables) appropriately.
* Choose the deployment namespace. In the deployment commands hereafter, it's assumed that the target namespace is `hugo-mx-gateway`. If you opt for another namespace, do consider to adapt the commands accordingly.
* Deployment with Helm (validated with Helm 3)
```
helm upgrade \
--namespace hugo-mx-gateway \
--install hugo-mx-gateway \
helm/
```
* Installation using Kubectl (if not using Helm). The Helm client is required to generate a raw template for kubectl.
Notice that the form is configured to be rendered specifically according to a Hugo parameter named **tags**, which is actually a **list of tags**. If the parameter holds a tag named `contact` then, the form will be rendered as a contact form. Otherwise, it'll be rendered as a demo form.
* Copy the HTML form content in your target **Hugo HTML template**.
* Modify the **<form>** HTML tag to make the **action** point to the URL of the sendmail backend deployed previously.
* On Google App Engine, the endpoint shall be: https://PROJECT-ID.REGION.r.appspot.com/sendmail. Replace `PROJECT-ID` and `REGION`, repectively, with the GCP's project ID and the deployment region.
* On Kubernetes, the in-cluster endpoint shall be: http://`hugo-mx-gateway`.`hugo-mx-gateway`.svc.cluster.local/sendmail
* On Docker, the endpoint shall be: http://DOCKER-HOST:8080/sendmail. Replace `DOCKER-HOST` with the IP adress or the hostname of the Docker machine.
* Edit the **Hugo Markdown content** of the target contact/demo page to ensure that the **tags** parameter holds a appropriate value (i.e. `contact` for a contact form, or `demo` for a demo request form).
Here is an example of header for a Hugo Markdown page. Since the `tags` parameter holds a tag named `contact`), the page will be rendered as a contact request form.
```
---
title: "Contact Us"
description: "Contact request page"
date: 2020-04-25T00:20:27+02:00
tags: [contact]
---
```
# Configuration variables
According to the deployment platform (Google App Engine, Kubernetes, Docker), the following configuration parameters must be provided as environment variables:
*`SMTP_SERVER_ADDR`: Set the address of the SMTP server in the form of `host:port`. It's required that the SMTP server being supporting TLS.
*`SMTP_VERITY_CERT`: Tell whether the SMTP certificate should be validated against top level authorities. If you're using a self-signed certificate on the SMTP server, this value must be set to `false`.
*`SMTP_CLIENT_USERNAME`: Set the username to connect to the SMTP server.
*`SMTP_CLIENT_PASSWORD`: Set the password to connect to the SMTP server.
*`CONTACT_REPLY_EMAIL`: Set an email address for the reply email. It's not necessary a valid email address, for example if don't want the user to reply you can use something like `noreply@example.com`.
*`CONTACT_REPLY_BCC_EMAIL`: Sets an email address for bcc copy of the email sent to the user. This is useful for tracking and follow up.
*`DEMO_URL`: Specific for demo forms, it can be used to set the URL of the demo site that will be included to the user reply email (e.g. `https://demo.example.com/`).
*`ALLOWED_ORIGINS`: Set a list of comma-separated domains that the `hugo-mx-gateway` App shoudl trust. This is for security reason to filter requests. Only requests with an `Origin` header belonging to the defined origins will be accepted, through it's only required that the request has a valid `Referer` header. It's expected in the future to these request filtering and admission rules.
*`TEMPLATE_DEMO_REQUEST_REPLY` (optional): Specify the path of the template to reply a demo request. The default templare is `templates/template_reply_demo_request.html`
*`TEMPLATE_CONTACT_REQUEST_REPLY` (optional): Specify the path of the template to reply a contact request. The default templare is `templates/template_reply_contact_request.html`.
This tool (code and documentation) is licensed under the terms of Apache 2.0 License. Read the [LICENSE](LICENSE) file for more details on the license terms.
The tool may inlcude third-party libraries provided with their owns licenses and copyrights, but always compatible with the Apache 2.0 License terms of use.
# Support & Contributions
We encourage feedback and do make our best to handle any troubles you may encounter when using this tool.