2.5 Configuring and Running JSONAir

How to configure and start the JSONAir server.

JSONAir is configured entirely through environment variables. There are no configuration files to edit. Variables can be provided in two ways:

• A .env file placed in the same directory as the binary

• System environment variables (set via export, a process manager, or a container runtime)

If a .env file is present, it is loaded automatically at startup. System environment variables take precedence if both are set.

---

Environment Variables

Required — Database

Variable	Description	Example
MYSQL_USERNAME	Database username	jsonair
MYSQL_PASSWORD	Database password	s3cr3tpassword
MYSQL_HOST	Database hostname or IP	127.0.0.1
MYSQL_PORT	Database port	3306
MYSQL_DATABASE	Database name	jsonair

Optional — Database TLS

Variable	Description	Default
MYSQL_TLS	Set to true to enable TLS for the database connection	false
MYSQL_TLS_SKIP_VERIFY	Set to true to disable certificate verification. Not recommended for production.	false

Required — HTTP Server

Variable	Description	Example
HTTP_LISTEN	Address and port to listen on	:9191 or 0.0.0.0:9191
HTTP_MODE	Server mode. Must be one of: production, release, debug, test	production

Note: production and release are equivalent — both run the Gin framework in release mode with HTTP access logging suppressed. Use debug during development for verbose request logging.

Optional — HTTPS (TLS)

If HTTP_TLS is not set or is false, the server listens on plain HTTP.

Variable	Description	Example
HTTP_TLS	Set to true to enable HTTPS	true
HTTP_CERT	Path to the TLS certificate file	/etc/letsencrypt/live/example.com/fullchain.pem
HTTP_KEY	Path to the TLS private key file	/etc/letsencrypt/live/example.com/privkey.pem

When HTTP_TLS=true, both HTTP_CERT and HTTP_KEY are required.

Required — Security

Variable	Description	Example
JWT_TOKEN_SECRET	Secret used to sign and verify JWTs. Use a long, random string.	openssl rand -hex 32
JWT_TOKEN_EXPIRE	JWT lifetime in minutes	60
TOKEN_HMAC_SECRET	Secret used to HMAC-SHA256 hash PATs before storing or comparing them. Must match the value used when inserting keys into the database.	openssl rand -hex 32
CONFIG_ENCRYPT_SECRET	Secret used to derive the AES-256-GCM key for decrypting config_data at rest. Must match the secret used when encrypting data with jsonair-encrypt.	openssl rand -hex 32

Required — Process

Variable	Description	Example
RUNAS	Username to drop privileges to after binding to the port	nobody

---

Example .env File

Create a file named .env in the same directory as the jsonair binary. A minimal production setup looks like this:

# Database
MYSQL_USERNAME=jsonair
MYSQL_PASSWORD=your-strong-db-password
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=jsonair
MYSQL_TLS=false

# HTTP
HTTP_LISTEN=:9191
HTTP_MODE=production
HTTP_TLS=false

# Security
JWT_TOKEN_SECRET=replace-with-output-of-openssl-rand-hex-32
JWT_TOKEN_EXPIRE=60
TOKEN_HMAC_SECRET=replace-with-a-different-openssl-rand-hex-32
CONFIG_ENCRYPT_SECRET=replace-with-a-third-openssl-rand-hex-32

# Process
RUNAS=nobody

For HTTPS, add:

HTTP_TLS=true
HTTP_CERT=/etc/letsencrypt/live/example.com/fullchain.pem
HTTP_KEY=/etc/letsencrypt/live/example.com/privkey.pem

Security: Never commit a .env file containing real credentials to source control. Add .env to your .gitignore.

---

Starting the Server

Directly

If using a .env file, simply run the binary from the same directory:

cd /opt/jsonair
./jsonair

Using export.sh

A convenience script is included at cmd/jsonair/scripts/export.sh. Copy and edit it with your values, then run it to set environment variables and start the server in one step:

cp cmd/jsonair/scripts/export.sh /opt/jsonair/start.sh
# Edit start.sh with your values
chmod +x /opt/jsonair/start.sh
./start.sh

As a systemd Service

For production Linux deployments, run JSONAir as a systemd service. Create /etc/systemd/system/jsonair.service:

[Unit]
Description=JSONAir Configuration Server
After=network.target mysql.service
Wants=mysql.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/jsonair
EnvironmentFile=/etc/jsonair/jsonair.env
ExecStart=/opt/jsonair/jsonair
Restart=on-failure
RestartSec=5
KillMode=mixed
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

Place your environment variables in /etc/jsonair/jsonair.env (same format as a .env file), then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable jsonair
sudo systemctl start jsonair
sudo systemctl status jsonair

Note: The service starts as root so it can bind to the configured port, then immediately drops privileges to the user specified in RUNAS. This is the intended behavior.

---

Verifying Startup

On a successful start you should see output similar to:

Banner :jsonair: -*> JSONAir! <*-
Banner :jsonair: Version: 1.0.0
Banner :jsonair: Champ Clark III & The Key9, Inc. Team [https://k9.io]
Banner :jsonair: Copyright (C) 2026 Key9, Inc. et al.
Info   :jsonair: Listening on ':9191' for traffic as UID: 65534.

The UID shown (65534 on most Linux systems is nobody) confirms that privilege drop succeeded.

---

Health Check

JSONAir exposes an unauthenticated health endpoint at /health. It pings the database and returns HTTP 200 when healthy or HTTP 503 when the database is unreachable.

curl http://localhost:9191/health

Healthy response:

{"status": "ok"}

Unhealthy response (HTTP 503):

{"status": "error", "message": "database unreachable"}

This endpoint is intentionally unauthenticated so that load balancers, orchestrators, and container runtimes can poll it without credentials.

Docker HEALTHCHECK

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget -qO- http://localhost:9191/health || exit 1