185 lines
11 KiB
Markdown
185 lines
11 KiB
Markdown
![](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 **<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`.
|
|
|
|
# License & Copyrights
|
|
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.
|
|
|
|
Here is the link to submit issues: https://github.com/rchakode/`hugo-mx-gateway`/issues.
|
|
|
|
New ideas are welcomed, please open an issue to submit your idea if you have any one.
|
|
|
|
Contributions are accepted subject that the code and documentation be released under the terms of Apache 2.0 License.
|
|
|
|
To contribute bug patches or new features, please use the Github Pull Request model. |