KNEL-TSYSDevStack-SupportStack-Cloudron/Package-Workspace/DevOps-Tools/fx/README.md

FX — Cloudron Package

fx is "poor man's function as a service": a CLI that turns a stateless function file (JavaScript, Python, Go, Ruby, Java, PHP, Perl, Crystal, Rust, Julia, D) into a running HTTP service on your own Docker host or Kubernetes cluster, in seconds. fx packages the function, ships it to the target over SSH (key-based) or the K8s API, and the target runs the container.

This package is an fx workstation: the pinned fx binary plus a persistent workspace, driven from the Cloudron web terminal. Cloudron app containers have no Docker daemon (and no access to the host's), so deploys always target a remote Docker host or a Kubernetes cluster — never the app container itself.

Packaging overview

Aspect	Choice
Pattern	Pre-compiled binaries (JOURNAL pattern #5)
Base image	cloudron/base:4.0.0 (Ubuntu 22.04; the goreleaser binary is glibc-built)
Upstream binary	fx_0.9.48-alpha.d91a7a0_Tux_64-bit.tar.gz (linux/amd64), sha256-pinned in the Dockerfile (checksum from upstream checksums.txt)
Addons	localstorage only (workspace persistence; no database)
Auth	No user concept → httpAuth.type = proxy (see below)
Runtime	start.sh seeds the workspace and serves the landing page; fx runs on demand from the terminal

Why pre-compiled: the last published release is 0.9.48-alpha.d91a7a0 (2021-06-10) — the same artifact the official scripts/install.sh installs, and the binary reports version 0.9.48. Repo master (2023) has no newer release; building the go 1.12-era, packr-using codebase from source would buy nothing over the official binary.

Authentication (auth gate verdict: proxy)

• fx has no user concept: no web UI, no accounts, no SSO hooks — it is a terminal tool.
• The manifest declares httpAuth: {"type": "proxy"}: Cloudron's auth proxy gates the landing page, which is the only HTTP surface this app has. Access to the terminal (and therefore the workspace and SSH keys) is Cloudron's app access list — restrict the app to the admins who should wield it.
• The SSH keys stored in /app/data/ssh/ are the credentials for the deploy targets; guard them with the app's access list and file permissions.

Usage

1. Open the app's web terminal (or cloudron exec).
2. Drop an SSH private key into /app/data/ssh/ (e.g. via the file manager) for your Docker target, or a kubeconfig into /app/data/kube/ for a Kubernetes target.
3. Deploy:

fx up --host deploy@example.com --ssh_key /app/data/ssh/id_rsa \
       --name hello /app/data/functions/hello.js

fx list --host deploy@example.com     # deployed services
fx down --host deploy@example.com hello

Kubernetes:

export FX_KUBECONF=/app/data/kube/config
fx up --name hello /app/data/functions/hello.py

The two seeded starters (hello.js, hello.py) use the exact upstream example shapes: a Koa-style ctx handler for JS, a plain fx(request) callable for Python.

Knobs: FX_HOST (default deploy target, <user>@<host>) and FX_KUBECONF (path to kubeconfig) can be set once via Cloudron's environment settings instead of per-command flags — see .env.example.

Ports

Port	Type	Purpose
8000	httpPort	Landing/usage page + platform health check (behind Cloudron auth proxy)

fx itself listens on nothing; deployed functions listen on their target host, outside this app.

Build & test

docker build --cgroup-parent ukrrs-batch.slice -t fx-cloudron:test Package-Workspace/DevOps-Tools/fx/
docker run --rm --entrypoint /usr/local/bin/fx fx-cloudron:test -v   # -> 0.9.48

Files

• Dockerfile — pinned release download + sha256 gate on cloudron/base:4.0.0
• CloudronManifest.json — manifestVersion 2, httpAuth proxy, localstorage only
• start.sh — workspace seeding + landing-page server (committed executable)
• status.html — auth-proxied landing/usage page
• .env.example — FX_HOST / FX_KUBECONF knobs
• .dockerignore — excludes the cloned repo/ from the build context
• logo.png — 256x256 monogram (fx ships no logo asset)