Skip to content

Latest commit

 

History

History
109 lines (83 loc) · 4.61 KB

README.adoc

File metadata and controls

109 lines (83 loc) · 4.61 KB

Go contact form

About

Provides a simple, tiny webservice that serves a contact form and sends responses via e-mail.

Example contact formExample email message

Usage

The simplest way to use this is via docker. See the examples directory for some example docker-compose files. The latest stable version of this project is published at ghcr.io/csmith/contact-form:latest.

You should place this service behind an TLS-terminating proxy such as Caddy or Traefik, and ensure it is requested over a secure connection.

Parameters

The application can be configured either using command line arguments or environmental variables (shown in square brackets, below). from, to, smtp-host, smtp-user, and smtp-pass are required; other options have vaguely sensible fallbacks.

  -crsf-key string
    	CRSF key to use [CONTACT_CRSF_KEY]
  -enable-captcha
    	Whether to require captchas to be completed [CONTACT_ENABLE_CAPTCHA]
  -enable-health-check
    	Whether to expose health checks at /_health [CONTACT_ENABLE_HEALTH_CHECK]
  -from string
    	address to send e-mail from [CONTACT_FROM]
  -port int
    	port to listen on for connections [CONTACT_PORT] (default 8080)
  -session-path string
        Path to persist session information [CONTACT_SESSION_PATH] (default "./sessions.db")
  -smtp-host string
    	SMTP server to connect to [CONTACT_SMTP_HOST]
  -smtp-pass string
    	password to supply to the SMTP server [CONTACT_SMTP_PASS]
  -smtp-port int
    	port to use when connecting to the SMTP server [CONTACT_SMTP_PORT] (default 25)
  -smtp-user string
    	username to supply to the SMTP server [CONTACT_SMTP_USER]
  -subject string
    	e-mail subject [CONTACT_SUBJECT] (default "Contact form submission")
  -to string
    	address to send e-mail to [CONTACT_TO]

You can use any SMTP server; however I recommend using a dedicated service such as mailgun or AWS SES, both of which you can access over SMTP.

Templates

All templates are loaded from the templates directory, which is expected to be in the current working directory. The form itself is loaded from form.html; success and failure pages from success.html and failure.html respectively. If captcha support is enabled, the captcha page is loaded from captcha.html. Each page is loaded as a go html.template and can use the templating syntax described there. Forms must contain the {{ .csrfField }} template field, which will automatically insert the CSRF token for the request.

Any query parameters passed to the form will be accessible through the {{ .params }} template field. The default template will include all parameters as hidden fields in the form.

If the form contains a field named from, it will be used in the Reply-To header. Otherwise, no special processing is applied to any field; they are all simply written out to the message body. No server-side validation is performed.

When running from the docker image, templates are stored in /templates; you can replace this with a volume to supply custom templates.

Static files

Any files in the static directory will be served under the path /static/. By default that is just a single stylesheet (style.css) that is used by the default templates.

When running from the docker image, static files are stored in /static; you can replace this with a volume to supply custom files.

Health checks

If the -enable-health-check flag is present, a healthcheck endpoint will be exposed at /_health. This implements the draft-inadarei-api-health-check-04 specification. Any application error that occurs when sending a mail or generating a captcha will result in a failing health check until the same operation succeeds again.

Note that the health check exposes error messages, which could potentially contain information about the configuration of the service or parts of messages being sent. If this is a concern you may wish to restrict access to the URL.

Credits

Developed by Chris Smith; CSS heavily based on the login form in ig by Greg Holmes.

Captchas are implemented using the dchest/captcha library, CSRF protection uses the Gorilla web toolkit. Health checks are implemented using nelkinda/health-go.

Licence

This software is licensed under the MIT licence. See the LICENCE.adoc file for the full text.