# FX — Cloudron Package

[fx](https://github.com/metrue/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:

```bash
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:

```bash
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

```bash
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)