Rodrigue Chakode
parent
05ffbf2a32
commit
dc1881eff5
131
README.md
131
README.md
|
|
@ -1,69 +1,73 @@
|
|||
|
||||
[](https://github.com/rchakode/`hugo-mx-gateway`/actions)
|
||||
|
||||
[](https://github.com/rchakode/`hugo-mx-gateway`/actions)
|
||||
|
||||
|
||||
# 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.
|
||||
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 built for this only-designated purpose.
|
||||
|
||||
|
||||
**This project is at its early open source life, but with a production deployment. The documentation is still being refining (notably for wording and typos). Contributions is any form (code/docs/ideas...) are welcomed.**
|
||||
|
||||
|
||||
|
||||
# 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)
|
||||
- [Why hugo-mx-gateway](#why-hugo-mx-gateway)
|
||||
- [How does it work](#how-does-it-work)
|
||||
- [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)
|
||||
- [Use the built-in form for Hugo](#use-the-built-in-form-for-hugo)
|
||||
- [Configuration variables](#configuration-variables)
|
||||
- [License & Copyrights](#license--copyrights)
|
||||
- [Support & Contributions](#support--contributions)
|
||||
|
||||
|
||||
# Why `hugo-mx-gateway`
|
||||
# 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.
|
||||
This project, namely `hugo-mx-gateway`, is meant to provide a RESTful API that adds the dynamicity required to handle contact/demo requests for static web sites. It's a simple, yet a powerful tool built for this only-designated purpose.
|
||||
|
||||
|
||||
|
||||
## How it Works
|
||||
## How does it work
|
||||
`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.
|
||||
* Create an HTML form with a POST action pointing towards the `hugo-mx-gateway` service. This service is a RESTful POST endpoint backed by an application easily deployable on [Google App Engine](https://cloud.google.com/appengine), Kubernetes, or Docker.
|
||||
* For each user request, `hugo-mx-gateway` automatically retrieves information submitted by the user (email, subject, message details...), then **generates and sends** a **templated email** to the user-provided email address, while **bcc**ing a copy of that email to an address that you can define for internal tracking and follow up.
|
||||
* Once a request is processed (upon success or failure), `hugo-mx-gateway` handles the reply back towards the calling static page by redirecting the browser to the origin page with additional URL parameters describing the completion status of the processing (e.g. `/contact.html?status=success&message=request%20submitted`). The parameters can then be easily retrieved and shown to the user, e.g. with a few lines of Javascript within the static page.
|
||||
* The project is shipped with a sample HTML form intending to cover a basic use case of contact and demo requests. 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:
|
||||
`hugo-mx-gateway` is easily deployable in minutes, subject to fulfil 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 platform (at your choice): Google App Engine, Kubernetes, or Docker.
|
||||
* An SMTP account with the server supporting TLS.
|
||||
|
||||
These are basic requirements in the today's Internet world.
|
||||
|
||||
> While it can be tempting to use a personal email account, it's highly recommended for security and privacy reasons 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 free to take the decision, 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
|
||||
Consider one of the following resources according to the selected installation platform.
|
||||
|
||||
## Deployment on Google Appp Engine
|
||||
This requires to have an active GCP account.
|
||||
This requires to have an active GCP account and [Google Cloud SDK](https://cloud.google.com/sdk) (gcloud) installed on your work station.
|
||||
|
||||
* 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/select a GCP project to deploy `hugo-mx-gateway`.
|
||||
|
||||
Note that each GCP project can hold only a single App Engine instance. Several applications can be co-hosted as services for the root App Engine instance. In this case, a new application has to be declared as `service` in the `app.yaml` file.
|
||||
* 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:
|
||||
* Edit the configuration variables as described [here](#configuration-variables).
|
||||
* Start the deployment
|
||||
```
|
||||
make deploy-gcp
|
||||
```
|
||||
|
|
@ -74,60 +78,57 @@ This requires to have an active GCP account.
|
|||
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.
|
||||
There is a [Helm chart](./helm/) to ease the deployment on Kubernetes clusters.
|
||||
|
||||
* 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)
|
||||
> **Important:** The chart is validated with Helm 3 and the pod is run in an unprivileged mode within a **Security Context**.
|
||||
|
||||
Proceed with the deployment as follows:
|
||||
|
||||
* First edit the [values.yaml](./helm/values.yaml) file to set [configuration values](#configuration-variables) appropriately.
|
||||
* Choose a deployment namespace. In the sample commands provided 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.
|
||||
* Apply the deployment with Helm
|
||||
```
|
||||
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.
|
||||
* Check that the application is up and running.
|
||||
```
|
||||
kubectl -nhugo-mx-gateway port-forward service/hugo-mx-gateway 8080:80
|
||||
kubectl -n hugo-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 of `hugo-mx-gateway` can be quickly started on any machine running Docker.
|
||||
|
||||
An instance can be started with the next command; please consider to adapt the [configuration variables](#configuration-variables) appropriately.
|
||||
* Please first review the [configuration variables](#configuration-variables) and adapt them 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`
|
||||
```
|
||||
* Then apply the following command:
|
||||
|
||||
Check that `hugo-mx-gateway` is up and functionning.
|
||||
```
|
||||
$ 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`
|
||||
```
|
||||
|
||||
```
|
||||
curl https://127.0.0.1:8080/healthz
|
||||
```
|
||||
* Check that the container is up and functionning.
|
||||
|
||||
# Create a Contact/Demo Request Form for Hugo
|
||||
```
|
||||
curl https://127.0.0.1:8080/healthz
|
||||
```
|
||||
|
||||
# Use the built-in 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.
|
||||
|
|
@ -136,13 +137,13 @@ Notice that the form is configured to be rendered specifically according to a Hu
|
|||
|
||||
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.
|
||||
* Modify the `<form>` 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.
|
||||
Here is an example of header for a Hugo Markdown page. The `tags` parameter holds a tag named `contact`) meaning that the page will be rendered as a contact request form.
|
||||
|
||||
```
|
||||
---
|
||||
|
|
@ -155,7 +156,7 @@ Here is an example of header for a Hugo Markdown page. Since the `tags` paramete
|
|||
|
||||
|
||||
# Configuration variables
|
||||
According to the deployment platform (Google App Engine, Kubernetes, Docker), the following configuration parameters must be provided as environment variables:
|
||||
Regardless of 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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue