fnkit Basics

A primer on the fnkit CLI — scaffolding, developing, and deploying functions.

What is fnkit?

fnkit is a CLI tool for building and deploying serverless functions. It handles scaffolding, Docker packaging, networking, caching, and GitOps deployment — so you focus on writing business logic.

Scaffolding Functions

fnkit supports four function types:

# Go HTTP function
fnkit go my-function

# Node.js HTTP function
fnkit node my-function

# Go MQTT function
fnkit go-mqtt my-function

# Node.js MQTT function
fnkit node-mqtt my-function

Each command creates a directory with everything you need:

my-function/
├── function.go (or index.js)   # Your handler code
├── cmd/main.go                 # Entry point (Go only)
├── Dockerfile                  # Container build
├── docker-compose.yml          # Service definition
├── .env.example                # Environment template
├── .gitignore
├── go.mod / package.json       # Dependencies
└── README.md                   # Documentation

HTTP Functions

HTTP functions handle incoming requests and return responses. Triggered by the gateway, a cron job, or direct HTTP calls.

Go HTTP (fnkit go):

func MyFunction(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}

Node.js HTTP (fnkit node):

const handler = (req, res) => {
    res.json({ status: 'ok' });
};
module.exports = handler;

MQTT Functions

MQTT functions subscribe to topics and process messages as they arrive. They run continuously.

Go MQTT (fnkit go-mqtt):

func MyFunction(ctx context.Context, msg mqtt.Message) error {
    topic := msg.Topic()
    payload := msg.Payload()
    // Process message...
    return nil
}

Infrastructure Commands

Command	Description
docker network create fnkit-network	Create shared network for all functions
fnkit cache start	Start the shared Valkey cache
fnkit cache stop	Stop the cache
docker exec -it fnkit-cache valkey-cli	Access the cache CLI

Local Development

cd my-function

# Copy environment template
cp .env.example .env
# Edit .env with your settings

# Build and start
docker compose up -d

# View logs
docker logs -f my-function

# Test
curl http://localhost:8080/my-function

# Stop
docker compose down

Deployment

Remote Deployment (GitOps)

# Set up remote deployment (one-time)
fnkit deploy remote --host root@your-server.com

# Deploy
git add . && git commit -m "update function"
git push deploy main

fnkit sets up a bare git repo on the server with a post-receive hook that checks out the code, builds the Docker image, restarts the container, and connects to fnkit-network.

Gateway

The fnkit gateway provides a single entry point for all HTTP functions:

https://api.fnkit.dev/my-function  →  my-function container:8080
https://api.fnkit.dev/uns-kpi      →  uns-kpi container:8080
https://api.fnkit.dev/uns-cache    →  uns-cache container:8080

Features: Authentication (Bearer token), Routing (URL path → container), Rate limiting (per-client).

Environment Variables

Variable	Description	Example
FUNCTION_TARGET	Function name (config lookup key)	uns-state
CACHE_URL	Valkey connection	redis://fnkit-cache:6379
DATABASE_URL	PostgreSQL connection	postgres://fnkit:fnkit@fnkit-postgres:5432/fnkit
MQTT_BROKER	MQTT broker URL	mqtts://mqtt.example.com:8883

Business configuration (topics, tables, etc.) lives in Valkey, not in environment variables. See Configuration Guide.

Previous Quick Start Next First Deployment