Documentation
Home GitHub

Getting Started

Install, configure, and run go-faas on a host with Redis and the language runtimes you plan to execute.

Prerequisites

macOS can run the server for development via sandbox-exec; Linux is the production sandbox target.

Installation

From Source

git clone https://github.com/pardnchiu/go-faas.git
cd go-faas
go build -o go-faas cmd/api/main.go

Using go install

go install github.com/pardnchiu/go-faas/cmd/api@latest

Install TypeScript Dependencies

npm install

On first launch, the program checks for bwrap, node, and python3. If any are missing, it attempts to install them via the system package manager (Linux only).

Configuration

Copy .env.example and fill in values (or export the same variables in the shell):

cp .env.example .env
Variable Required Default Description
HTTP_PORT No 8080 HTTP server port
MAX_CPUS No 1 Sandbox CPU quota (cores)
MAX_MEMORY No 128M Sandbox memory ceiling
CODE_MAX_SIZE No 262144 (256KB) Maximum allowed code size in bytes
TIMEOUT_SCRIPT No 30 Script execution timeout in seconds
REDIS_HOST No localhost Redis host address
REDIS_PORT No 6379 Redis port
REDIS_PASSWORD No empty Redis password
REDIS_DB No 0 Redis database number
REDIS_TIMEOUT_SECONDS No 5 Redis connection timeout in seconds

See Configuration for details.

Start the Server

./go-faas

Startup order in cmd/api/main.go:

  1. Load .env via godotenv (falls back to system env)
  2. checker.CheckPackage() for runtimes
  3. database.Init() (Redis ping)
  4. sandbox.NewSlice() (Linux systemd user slice)
  5. Listen on HTTP_PORT

Basic: Upload a Script

curl -X POST http://localhost:8080/upload \
  -H "Content-Type: application/json" \
  -d '{
    "path": "math/add",
    "language": "python",
    "code": "return event.get(\"a\", 0) + event.get(\"b\", 0)"
  }'

Response:

{
  "path": "math/add",
  "language": "python",
  "version": 1739000000
}

Basic: Execute a Stored Script

Latest version:

curl -X POST http://localhost:8080/run/math/add \
  -H "Content-Type: application/json" \
  -d '{
    "input": "{\"a\": 3, \"b\": 5}"
  }'

Specific version:

curl -X POST "http://localhost:8080/run/math/add?version=1739000000" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "{\"a\": 3, \"b\": 5}"
  }'

Response:

{
  "data": 8,
  "type": "number"
}

Advanced: Run-Now

curl -X POST http://localhost:8080/run-now \
  -H "Content-Type: application/json" \
  -d '{
    "language": "javascript",
    "code": "return { sum: event.a + event.b }",
    "input": "{\"a\": 10, \"b\": 20}"
  }'

Advanced: SSE Streaming

curl -X POST http://localhost:8080/run-now \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "import time\nfor i in range(5):\n    print(i)\n    time.sleep(0.5)\nreturn \"done\"",
    "input": "{}",
    "stream": true
  }'

Streaming format:

data: {"event":"log","data":"0","type":"text"}

data: {"event":"log","data":"1","type":"text"}

data: {"event":"result","data":"done","type":"string"}

Next Steps

中文