JSON2FILE-GO(8)

💖 JSON2FILE-GO 💖

okay so bestie, welcome to the manual page for json2file-go, section 8 of the manual. it's a lil web server that catches JSON files for u and it's genuinely iconic. let's get into it 🫶

---

✨ NAME ✨

json2file-go — a simple web server that provides entry points to store JSON files 🎀

---

✨ SYNOPSIS ✨

json2file-go

that's it. no flags. no args. she just runs. main character energy fr fr 👑

---

✨ DESCRIPTION ✨

so json2file-go(1) is a mini-application that runs as a Web server, and its whole job is storing the information that remote WebHooks send over in JSON format using the HTTP POST method. 💅

originally she was built to process GitLab and Gitea WebHooks, but ngl she can be used with other systems too.

now here's the vibe check on how auth works: to verify that a caller actually has permission to store a file, the program compares a JSON field or an HTTP HEADER against the secret it has configured for the given PATH. if the secret matches, the program then verifies that the data received is a valid JSON file — and only stores it if it is. no valid JSON, no file. periodt. ✨

the application is configured using environment variables, and she's designed to run inside a docker container or supervised with systemd if we're on a regular Linux server. 🌸

the application reads two mandatory environment variables:

• J2F_BASEDIR — the working directory of the application. it must exist before launching her, no cap.
  • the default value for this variable when using the systemd helper (see later, bestie) is /var/spool/json2file-go.
  • if we use the application inside a container, the idea is to set the value to /data (which is a volume in the Dockerfile) and use a volume or mount a HOST directory there. 🦋
• J2F_DIRLIST — the list of directories in which we allow one to save files, plus an optional token that must be passed in a header or within the JSON to authorize the save operation for the file.
  • the variable is a string of the form: DIR1:TOKEN1;...;DIR#:TOKEN#
  • there is no default for this variable — it must be set. 😭

other optional variables include:

• J2F_SIGNATURE_HEADERS — comma-separated list of names for the HTTP header containing the signature hash (by default the list contains the name X-Hub-Signature)
• J2F_TOKEN_HEADERS — comma-separated list of names for the HTTP header containing the token (by default the list contains the names X-Auth-Token and X-Gitlab-Token)
• J2F_TOKEN_FIELDS — comma-separated list of names for the received JSON field that contains the token (by default we use secret)
• J2F_URL_PREFIX — service base path on URLs, the directory names are computed removing this prefix
• J2F_HOST — IP address to bind to (default 0.0.0.0)
• J2F_PORT — TCP Port (80 if there are no certificates, 443 if there are any)
• J2F_BIND — Listen Address and Port (default $J2F_HOST:$J2F_PORT, if used it replaces the other two variables)
• J2F_CERTFILE and J2F_KEYFILE — public certificate and key file for TLS (if both are set it is assumed that we are using TLS and the server uses that certificate and private key)
• J2F_SOCKET — UNIX Socket to listen on (has no default value; if passed, the server listens for HTTP requests on a UNIX socket, ignoring the address, port and TLS settings). this is the preferred mode when the service is accessed using NGINX as a reverse proxy. 💜

by default the system saves the JSON data received in the sub folder of J2F_BASEDIR that matches the requested directory name, using files with names of the form TIMESTAMP.json, where the format of TIMESTAMP is YYYYmmdd-HHMMSS.MS.json. 🎀

while this program does nothing else, the files are usually processed by scripts launched by cron(8) or incrond(8).

to be able to work with systemd.socket(5), when the application launches it checks if the variable LISTEN_PID is set — and in that case the J2F_HOST, J2F_PORT, J2F_BIND and J2F_SOCKET are ignored, and the program listens on the first file descriptor available after stdout (the one with value 3), ignoring other descriptors if any (the daemon only listens on a file descriptor). note that in this case the J2F_CERTFILE and J2F_KEYFILE are NOT ignored (systemd can pass us a file descriptor where we should use HTTPS). 🧚

heads up bestie: if the program is launched without systemd and the variables J2F_HOST, J2F_PORT, J2F_BIND or J2F_SOCKET have no value, the program tries to listen on 0.0.0.0:80 (or 0.0.0.0:443 if we provide a certificate and a key file).

---

✨ CONFIGURATION ✨

the binary does not read any configuration files by itself, but the packaged version includes a helper script (/usr/lib/json2file-go/json2file-go) to adjust environment variables when launching the program with systemd or other init systems (see the /usr/share/doc/json2file-go/examples directory for samples). 🍓

the launcher script reads files from the directory /etc/json2file-go and adjusts the variables as follows:

• dirlist — file with lines of the form dir:token that are passed on the variable J2F_DIRLIST separated by ;. this file is required when using systemd. 💀
• basedir — value of the J2F_BASEDIR variable, has a default value when using systemd
• debug — value of the J2F_DEBUG variable
• signature_headers — lines with of HTTP header names that can contain signature hashes, the values are stored separated by commas on the environment variable J2F_SIGNATURE_HEADERS
• token_headers — lines with of HTTP header names that can contain authorization tokens, the values are stored separated by commas on the environment variable J2F_TOKEN_HEADERS
• token_fields — lines with names of JSON fields that can contain authorization tokens, the values are stored separated by commas on the environment variable J2F_TOKEN_FIELDS
• url_prefix — value of the J2F_URL_PREFIX
• bind — value of the J2F_BIND variable
• host — value of the J2F_HOST variable
• port — value of the J2F_PORT variable
• certfile — value of the J2F_CERFILE variable
• keyfile — value of the J2F_KEYFILE variable
• socket — value of the J2F_SOCKET variable

---

✨ BUGS ✨

none so far... ;) 😌💅

(not me being obsessed with that confidence level. we love a bug-free queen.)

---

✨ AUTHOR ✨

json2file was originally written by Sergio Talens-Oliag in Python using the Flask micro framework, later it was rewritten using FastAPI (another Python framework), and to make it lighter for container usage this third version in Go was born. 🌈

---

✨ SEE ALSO ✨

docker(1), systemd(1), incrond(8)

---

✨ COPYING ✨

Copyright (c) 2019-2020 Sergio Talens-Oliag. Free use of this software is granted under the terms of the Apache License Version 2.0.

---

and that's the whole page bestie!! 🌟 this version is from 2025-06-25, and yes it's still JSON2FILE-GO(8) — the one and only. mwah, go store some JSON 💖✨🎀