Deploy Ferret as a service

Ferret Worker is an HTTP service that accepts FQL scripts and returns results. This guide walks through deploying Worker with Docker for remote or shared use.

Start Worker with Docker

The simplest deployment uses the Worker Docker image:

$docker run -d -p 8080:8080 montferret/worker

Worker is now listening on port 8080. Test it with a curl request:

$curl -s -X POST http://localhost:8080/api/query \$  -H "Content-Type: application/json" \$  -d '{"query": "RETURN 1 + 1"}'

Add browser support

For scripts that need the cdp driver, run Worker alongside a Chromium container:

# docker-compose.yml
services:
  worker:
    image: montferret/worker
    ports:
      - "8080:8080"
    environment:
      - FERRET_WORKER_CHROME_URL=ws://chromium:9222
    depends_on:
      - chromium

  chromium:
    image: montferret/chromium

$docker compose up -d

Now Worker can execute browser-backed scripts:

$curl -s -X POST http://localhost:8080/api/query \$  -H "Content-Type: application/json" \$  -d '{$    "query": "LET p = WEB::HTML::OPEN(\"https://mockery.ferretlang.org\", { driver: \"cdp\" })\nRETURN p.title"$  }'

Configure Worker

Worker is configured through environment variables or command-line flags. Common settings:

See Worker Configuration for the full list.

Pass parameters

Send parameters alongside the query:

$curl -s -X POST http://localhost:8080/api/query \$  -H "Content-Type: application/json" \$  -d '{$    "query": "LET p = WEB::HTML::OPEN(@url)\nRETURN p.title",$    "params": { "url": "https://mockery.ferretlang.org" }$  }'

Health checks

Worker exposes a health endpoint:

$curl -s http://localhost:8080/api/health

Use this in Docker health checks or load balancer probes:

services:
  worker:
    image: montferret/worker
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3

Run behind a reverse proxy

For production deployments, place Worker behind a reverse proxy (nginx, Caddy, Traefik) to handle TLS, rate limiting, and authentication.

Example nginx configuration:

upstream worker {
    server 127.0.0.1:8080;
}

server {
    listen 443 ssl;
    server_name ferret.example.com;

    location /api/ {
        proxy_pass http://worker;
        proxy_read_timeout 60s;
    }
}

Use Worker as a remote runtime

The Ferret CLI and Lab can execute scripts against a remote Worker instance:

$ferret run --runtime http://localhost:8080 script.fql

Lab supports this with the HTTP runtime:

$lab --dir ./tests --runtime http://localhost:8080

See HTTP Runtime for details.

Next steps