= Application to store JSON data sent by Web Hooks into files

This mini-application is used to store the information sent in JSON format by
remote Web Hooks into local files to be processed by external tools; so far it
has been used to process *GitLab* and *Gitea* Web Hooks using shell and python
scripts invoked by `incron`.

The program uses environment variables to adjust parameters, see
json2file-go(1) for a list of them and a description of what they are used for.

The idea behind this application is to be as simple as possible, the only thing
it does with the JSON data is to check that the format is valid, the rest of
the processing has to be done from external scripts or programs (i.e. using
`jq` from shell scripts or parsing the file using libraries in `python`, `ruby`
or any other programming language).

For a system with more functionalities included you can use something like
`webhook`.

== Executing under `systemd` supervision

As the initial idea for the application was to run it always inside a container
the program is not prepared to _damonize_ itself nor to drop privileges or read
configuration files (the configuration options are passed using environment
variables).

To launch the program under `systemd` we have prepared a shell script that
reads configuration values from files, exports their values and _execs_ the
program (the _daemonizing_ part is done by `systemd`); instead of the
_launcher_ script we could have used the `EnvironmentFile` option, but we opted
for the script because it is also useful with other init systems.

The program can listen on a TCP or UNIX socket opened by itself directly or use
a systemd.socket(5); in any case the program is prepared to process plain HTTP
requests or HTTPS requests (the program handles the TLS protocol if a
certificate and a key are provided).

By default the Debian package launches the program only if the admin has
created a `/etc/json2file-go/dirlist` file (it is needed to know the service
path and secret, the simplest one can contain a line with a colon which makes
the service available on the `base_url` path without using secrets).

If the file exists and nothing else is changed `systemd` launches the program
listening on a UNIX socket (the idea is that usually the machine will probably
have another web server already installed and this service can be published
using a reverse proxy in `nginx` or `apache`), if you prefer to listen on a TCP
port you just need to override the `json2file-go.socket` definition provided by
the package.

On the `examples` directory (`/usr/share/doc/json2file-go/examples` on the
packaged version) there are some configuration examples to:

- use `nginx` as a reverse proxy to publish the service,
- configure `systemd` to use a TCP port instead of a UNIX socket,
- configurations for alternative init daemons o supervision services to launch
  the program

== Execution as a container using the `docker-json2file-go` script

If a user wants to run the application inside a container it can be done using
the script `bin/docker-json2file-go` on a checkout of the repository and
exporting variables (the script uses the `J2F_*` variables and if they are not
available it also accepts the variables `IP`, `DIRLIST`,`PORT` y `SOCKET`).

Files are stored on the checkout directory under `data` and if we plan to use
TLS the `cert.pem` and `key.pem` files have to be stored under the `secrets`
directory.

Currently the container uses the `host` network, if we have other HTTP(S)
servers on the machine we can use a different TCP port or a UNIX socket in
a folder shared with the host or other containers and configure a web server
like `nginx` as a reverse proxy to publish the service.
