Formrecevr (pronunced "Form receiver") is a simple and lightweight from receiver backend primarily designed for (but not limited to) static websites. It is inspired by formspree.io but it is simpler, self-hosted and doesn't have a frontend.
- Easy setup: Just create your docker-compose.yml and you're good to go!
- Powerful templating: Use Go templating (just like in Hugo) to compose customized content
- Shoutrrr integration: You can use a wide variety of services to reveive your form submissions
- Flexible delivery: Thanks to the use of shoutrrr and templating, you can use data from the form as a receiver
- Cloudflare Turnstile: Couldflare Turnstile is a modern and privacy preserving CAPTCHA.
The official installation method is using Docker:
- Create a folder for installation:
mkdir /opt/formrecevr && cd /opt/formrecevr
- Create the file docker-compose.yml with this content:
version: "3.7" services: formrecevr: image: dorianim/formrecevr restart: always ports: - 5081:8088 volumes: - ./config:/config
- Adjust the port (default
5081
) to your needs - Start the formrecevr:
docker-compose up -d
- Done! You can reach your formrecevr on
localhost:80
- Adjust your
config.yml
in/opt/formrecevr/config/config.yml
- [OPTIONAL] Adjust your templates in
/opt/formrecevr/config/templates
- [OPTIONAL] To setup ssl/https, please use a reverse proxy like nginx
The configuration is stored in /config/config.yml
in the container by default. It is reloaded live, so changes do not require a container restart to become effective.
A fully populated config could look like this:
forms:
- id: "Example"
enabled: true
targets:
- enabled: true
template: default.html
shoutrrrurl: "telegram:https://someToken@telegram/?channels={{ .params.someChannel }}"
params:
someKey: someChannel
- enabled: false
template: email.html
shoutrrrurl: "smtp:https://username:password@host:port/?from=fromAddress&to=recipient1&to={{ .mailFromFrom }}"
- id: "Example2"
enabled: true
turnstile:
enabled: true
secretkey: "1x0000000000000000000000000000000AA"
targets:
- enabled: true
template: default.html
shoutrrrurl: "slack:https://token:token@channel/"
listen:
host: 0.0.0.0
port: 8088
listen
contains settings for the webserverforms
contains a list of form blocks
id
: The ID of the form. I suggest using something likeuuidgen
to create a random IDenabled
: If the form is enabled. It will not work when this is set to falsetargets
: Contains a list of target blocksturnstile
: Contains the turnsilte-config
enabled
: If the target is enabled. It will be skipped when set to falsetemplate
: The name of the template which is used for the body. See templatesshoutrrrurl
: The shoutrrr URL to use for form submissions. Additional information on how to get the URLs can be found hereparams
: Additional parameters which are also passed to the templating engine as.params.<key>
. This can be useful when using the same template for multiple targets.
enabled
: If Turnstile is enabled. Defaults toflase
secretkey
: The Turnsitle sectre key.
Templates have to be stored in /config/templates
by default.
The templates are processed by the go templating engine and have access to all of its functionality, like range loops and if conditions.
Templates can use all submited form fields in the root context. In addition to that, they have access to the params defined for their target inside the .params
key.
For testing, you can use {{ . }}
to see all avaiable data.
There are two additional functions wich can be used:
join
: Joins a list of strings with a delimiter, eg.{{ join .someListParameter "," }}
print
: Prints one or more strings or string lists without any delimiter, eg.{{ print .someString .someStringList }}
There are currently two routes available
/api/v1/healthcheck
(GET): Should return 200 if everything is OK/f/:formID
(POST): Accepts form data for configured formIDs. It currently supportsapplication/x-www-form-urlencoded
andmultipart/form-data
I recommend to use the javascript fetch()
API to submit your form. An example of this can be found in examples/form-xhr-fetch.html