![](https://img.shields.io/github/license/rchakode/`hugo-mx-gateway`.svg?label=License) [![Actions Status](https://github.com/rchakode/`hugo-mx-gateway`/workflows/Build/badge.svg)](https://github.com/rchakode/`hugo-mx-gateway`/actions) ![](https://img.shields.io/docker/pulls/rchakode/`hugo-mx-gateway`.svg?label=Docker%20Pulls) # Overview 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. ![](`hugo-mx-gateway`-architecture-overview.png) # Table of contents - [Overview](#overview) - [Table of contents](#table-of-contents) - [Why `hugo-mx-gateway`](#why-hugo-mx-gateway) - [How it Works](#how-it-works) - [Prerequisites](#prerequisites) - [Deployment](#deployment) - [Deployment on Google Appp Engine](#deployment-on-google-appp-engine) - [Deployment on a Kubernetes cluster](#deployment-on-a-kubernetes-cluster) - [Deployment on Docker](#deployment-on-docker) - [Create a Contact/Demo Request Form for Hugo](#create-a-contactdemo-request-form-for-hugo) - [Configuration variables](#configuration-variables) - [License & Copyrights](#license--copyrights) - [Support & Contributions](#support--contributions) # Why `hugo-mx-gateway` 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? You're at the right place. 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. ![Screenshot of a successful submission](./screenshots/form-submitted-and-processed-with-success.png) ## How it Works `hugo-mx-gateway` is built upon a simple request handling workflow: * 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. ## Prerequisites `hugo-mx-gateway` is deployable in minutes, subject to fillful the following requirements: * 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. # Deployment `hugo-mx-gateway` is deployable in minutes on the following platforms: * Google Appp Engine * Kubernetes * Docker ## Deployment on Google Appp Engine This requires to have an active GCP account. * Make sure to have [Google Cloud SDK](https://cloud.google.com/sdk) (gcloud) installed on your work station. * Create/select a GCP project to deploy `hugo-mx-gateway`. Note that each GCP project can hold only a single App Engine instance. * Create the Google App Engine configuration file ``` cp app.yaml.sample app.yaml ``` * Open the `app.yaml` file with your favorite editor. * Set the configuration variables as described [here](#configuration-variables). * Apply the deployment as follows: ``` make deploy-gcp ``` * Check that `hugo-mx-gateway` is up and functioning ``` curl https://PROJECT-ID.REGION.r.appspot.com/healthz ``` Replace `PROJECT-ID` with the GCP project ID, and `REGION` with the deployment region. ## Deployment on a Kubernetes cluster There is a [Helm chart](./helm/) to ease the deployment on Kubernetes clusters. This chart has been validated with Helm 3. * 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. ``` $ helm template \ hugo-mx-gateway \ --namespace hugo-mx-gateway \ helm/ | \ kubectl apply -f - ``` * Check that the Service is up and running. ``` kubectl -nhugo-mx-gateway port-forward service/hugo-mx-gateway 8080:80 curl https://127.0.0.1:8080/healthz ``` ## Deployment on Docker `hugo-mx-gateway` is released as a Docker image, so you can quickly start an instance in any machine running Docker. An instance can be started with the next command; please consider to adapt the [configuration variables](#configuration-variables) appropriately. ``` $ docker run -d \ --publish 8080:8080 \ --name '`hugo-mx-gateway`' \ -e SMTP_SERVER_ADDR="smtp.example.com:465" \ -e SMTP_VERITY_CERT=true \ -e SMTP_CLIENT_USERNAME="postmaster@example.com" \ -e SMTP_CLIENT_PASSWORD="postmasterSecretPassWord" \ -e CONTACT_REPLY_EMAIL="noreply@example.com" \ -e CONTACT_REPLY_BCC_EMAIL="contact@example.com" \ -e DEMO_URL="https://demo.example.com/" \ -e ALLOWED_ORIGINS="127.0.0.1,example.com" \ rchakode/`hugo-mx-gateway` ``` Check that `hugo-mx-gateway` is up and functionning. ``` curl https://127.0.0.1:8080/healthz ``` # Create a Contact/Demo Request Form for Hugo The file `./samples/hugo-partial-contact-form.html` contains a sample HTML form for Hugo. It can be used for both contact and demo requests. Open the file in a your favorite editor and review it. 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. The integration works as follows: * Copy the HTML form content in your target **Hugo HTML template**. * Modify the **