{"id":36463723,"url":"https://github.com/dimiro1/lunar","last_synced_at":"2026-04-18T22:07:25.509Z","repository":{"id":324414739,"uuid":"1097030977","full_name":"dimiro1/lunar","owner":"dimiro1","description":"A lightweight, self-hosted Function-as-a-Service platform written in Go with Lua scripting.","archived":false,"fork":false,"pushed_at":"2026-04-18T14:42:09.000Z","size":9628,"stargazers_count":76,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-18T15:35:20.756Z","etag":null,"topics":["faas","faas-platform","go","golang","mithriljs","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimiro1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T12:08:27.000Z","updated_at":"2026-04-18T14:41:18.000Z","dependencies_parsed_at":"2026-01-12T00:00:10.885Z","dependency_job_id":null,"html_url":"https://github.com/dimiro1/lunar","commit_stats":null,"previous_names":["dimiro1/faas-go"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/dimiro1/lunar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimiro1%2Flunar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimiro1%2Flunar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimiro1%2Flunar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimiro1%2Flunar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimiro1","download_url":"https://codeload.github.com/dimiro1/lunar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimiro1%2Flunar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31986367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"ssl_error","status_checked_at":"2026-04-18T20:23:29.375Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["faas","faas-platform","go","golang","mithriljs","self-hosted"],"created_at":"2026-01-11T23:59:53.355Z","updated_at":"2026-04-18T22:07:25.498Z","avatar_url":"https://github.com/dimiro1.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo/logo-dark.png\" alt=\"Lunar Logo\" width=\"300\"\u003e\n\u003c/p\u003e\n\n# Lunar (formerly Faas-Go)\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/dimiro1/lunar.svg)](https://pkg.go.dev/github.com/dimiro1/lunar)\n[![Go Report Card](https://goreportcard.com/badge/github.com/dimiro1/lunar)](https://goreportcard.com/report/github.com/dimiro1/lunar)\n\nA lightweight, self-hosted Function-as-a-Service platform written in Go with Lua scripting.\n\n\u003e **Beta Phase Notice**: This project is currently in beta. New features and changes are actively being developed, but I promise to maintain backward compatibility for all Lua APIs. \n\n## Features\n\n* **Simple Lua Functions** - Write serverless functions in Lua\n* **Code Editor** - Monaco Editor with autocomplete and inline documentation\n* **HTTP Triggers** - Execute functions via HTTP requests\n* **Built-in APIs** - HTTP client, KV store, environment variables, logging, and more\n* **AI Integration** - Chat completions with OpenAI and Anthropic, with request/response logging\n* **Email Integration** - Send emails via Resend with scheduling support\n* **Version Control** - Track and manage function versions\n* **Execution History** - Monitor function executions and logs\n* **Beautiful Error Messages** - Human-friendly error messages with code context, line numbers, and actionable suggestions\n* **Web Dashboard** - Manage functions through a clean web interface\n* **API Documentation** - Swagger UI available at `/docs`\n* **Lightweight** - Single binary, no external dependencies\n\n## Screenshots\n\n### Dashboard\n![Dashboard](shots/dashboard.png)\n\n### Function Editor\n![Edit Function](shots/edit.png)\n\n### Environment Variables\n![Environment Variables](shots/env.png)\n\n### Testing Functions\n![Test Function](shots/test.png)\n\n### Execution History\n![Executions](shots/executions.png)\n\n### Version Management\n![Versions](shots/versions.png)\n\n### Version Comparison\n![Version Comparison](shots/comparison.png)\n\n### Command Palette\n![Command Palette](shots/command.png)\n\n### Error Messages\n![Error Messages](shots/error-messages.png)\n\n### AI Request Logs\n![AI Request Logs](shots/ai-logs.png)\n\n### Email Request Logs\n![Email Request Logs](shots/email-logs.png)\n\n## Quick Start\n\n### Prerequisites\n\n- Go 1.26 or newer\n- `make`\n- Chrome or Chromium if you plan to run the E2E test suite\n\nFor CLI internals and code generation details, see [cli/README.md](cli/README.md).\n\n### Building from Source\n\n```bash\ngit clone https://github.com/dimiro1/lunar.git\ncd lunar\nmake build\n```\n\n### Running\n\n```bash\n./build/lunar\n```\n\nFor local development, you can also install the optional contributor tools:\n\n```bash\nmake install-tools\n```\n\nThis installs `air` for live reload and `goreleaser` for release packaging.\n\nThen start the development server with:\n\n```bash\nmake dev\n```\n\nThe application will be available at `http://localhost:3000`.\n\n### First-Time Setup\n\nOn first run, Lunar will automatically generate an API key and save it to `data/api_key.txt`. The key will be printed in the server logs:\n\n```\nINFO Generated new API key key=cf31cb0cdc7811ca9cec6a3c77579b3ea28c1e4e10d6fc1061ae71788834c21b file=data/api_key.txt\n```\n\nWhen you access the dashboard, you'll be prompted to enter this API key to login. The key is also available in the `data/api_key.txt` file.\n\n### Your First Function\n\n1. Open `http://localhost:3000` and log in with the API key from `data/api_key.txt`.\n2. Create a new function named `hello-world`.\n3. Paste the sample handler below and save it.\n4. Copy the function ID and invoke it:\n\n```bash\ncurl http://localhost:3000/fn/\u003cfunction-id\u003e\n```\n\nYou should get back a JSON response. After that, open the function's execution history in the dashboard to inspect logs and request details.\n\n## Writing Functions\n\nFunctions are written in Lua and must export a `handler` function:\n\n```lua\nfunction handler(ctx, event)\n  -- ctx contains execution context (executionId, functionId, etc.)\n  -- event contains HTTP request data (method, path, query, body, headers)\n  \n  log.info(\"Function started\")\n  \n  return {\n    statusCode = 200,\n    headers = { [\"Content-Type\"] = \"application/json\" },\n    body = json.encode({ message = \"Hello, World!\" })\n  }\nend\n```\n\n### Available APIs\n\n* **log** - Logging utilities (info, debug, warn, error)\n* **kv** - Key-value storage (get, set, delete)\n* **env** - Environment variables (get)\n* **http** - HTTP client (get, post, put, delete)\n* **json** - JSON encoding/decoding\n* **crypto** - Cryptographic functions (md5, sha256, hmac, uuid)\n* **time** - Time utilities (now, format, sleep)\n* **url** - URL utilities (parse, encode, decode)\n* **strings** - String manipulation\n* **random** - Random generators\n* **base64** - Base64 encoding/decoding\n* **ai** - AI chat completions (OpenAI, Anthropic)\n* **email** - Send emails via Resend\n\n### LLM-Assisted Development\n\nLunar provides an [`llms.txt`](https://llmstxt.org/) file at `/llms.txt` with the complete Lua API reference, including function signatures, parameters, and code examples. You can use this with any LLM-powered coding assistant to get accurate help when writing Lunar functions.\n\n### Example: Counter Function\n\n```lua\nfunction handler(ctx, event)\n  -- Get current count from KV store\n  local count = kv.get(\"counter\") or \"0\"\n  local newCount = tonumber(count) + 1\n  \n  -- Save updated count\n  kv.set(\"counter\", tostring(newCount))\n  \n  log.info(\"Counter incremented to: \" .. newCount)\n  \n  return {\n    statusCode = 200,\n    headers = { [\"Content-Type\"] = \"application/json\" },\n    body = json.encode({ count = newCount })\n  }\nend\n```\n\n### Example: Send Email\n\n```lua\n-- Requires RESEND_API_KEY environment variable\nfunction handler(ctx, event)\n  local data = json.decode(event.body)\n\n  local result, err = email.send({\n    from = \"noreply@yourdomain.com\",\n    to = data.email,\n    subject = \"Welcome!\",\n    html = \"\u003ch1\u003eHello, \" .. data.name .. \"!\u003c/h1\u003e\",\n    scheduled_at = time.now() + 3600  -- Optional: send in 1 hour\n  })\n\n  if err then\n    return {\n      statusCode = 500,\n      body = json.encode({ error = err })\n    }\n  end\n\n  return {\n    statusCode = 200,\n    headers = { [\"Content-Type\"] = \"application/json\" },\n    body = json.encode({ email_id = result.id })\n  }\nend\n```\n\n### Calling Functions\n\n```bash\ncurl -X GET http://localhost:3000/fn/{function-id}\ncurl -X POST http://localhost:3000/fn/{function-id} -d '{\"key\":\"value\"}'\ncurl -X GET http://localhost:3000/fn/{function-id}?name=John\n```\n\n## Deployment\n\n### Docker\n\n```bash\n# Run the latest release from Docker Hub\ndocker run -p 3000:3000 -v $(pwd)/data:/data dimiro1/lunar:latest\n\n# Build and run with Docker\ndocker build -t lunar .\ndocker run -p 3000:3000 -v lunar-data:/app/data lunar\n\n# Or use Docker Compose\ndocker compose up -d\n```\n\n### Railway\n\nLunar is ready to deploy on [Railway](https://railway.app):\n\n1. **Connect Repository** - Link your GitHub repository to Railway\n2. **Add Volume** - Create a volume and mount it to `/data`\n3. **Set Environment Variables**:\n   - `BASE_URL` - Your Railway public URL (e.g., `https://yourapp.up.railway.app`)\n   - `API_KEY` - (Optional) Set a custom API key, or let it auto-generate\n4. **Deploy** - Railway will automatically detect the Dockerfile and deploy\n\nThe Dockerfile is Railway-compatible and will:\n- Use Railway's automatic `PORT` environment variable\n- Bind to `0.0.0.0:$PORT` for public networking\n- Persist data to the mounted volume at `/data`\n\n## Configuration\n\nLunar can be configured via environment variables:\n\n```bash\nPORT=3000                 # HTTP server port (default: 3000)\nDATA_DIR=./data           # Data directory for SQLite database (default: ./data)\nEXECUTION_TIMEOUT=300     # Function execution timeout in seconds (default: 300)\nAPI_KEY=your-key-here     # API key for authentication (auto-generated if not set)\nBASE_URL=http://localhost:3000  # Base URL for the deployment (auto-detected if not set)\n```\n\n### Authentication\n\nThe dashboard requires authentication via API key. You can:\n\n1. **Auto-generate** (recommended) - Let Lunar generate a secure key on first run\n2. **Set manually** - Provide your own key via the `API_KEY` environment variable\n\nAPI calls can authenticate using either:\n- **Cookie** - Automatically handled by the dashboard after login\n- **Bearer token** - Include `Authorization: Bearer YOUR_API_KEY` header\n\nExample API call with Bearer token:\n```bash\ncurl -H \"Authorization: Bearer YOUR_API_KEY\" http://localhost:3000/api/functions\n```\n\nNote: Function execution endpoints (`/fn/{id}`) do not require authentication.\n\n## CLI\n\nLunar ships a command-line client (`lunar-cli`) that is auto-generated from the OpenAPI spec, so it always stays in sync with the API.\n\n### Installation\n\n```bash\ngo install github.com/dimiro1/lunar/lunar-cli@latest\n```\n\nOr download a pre-built binary from the [Releases](https://github.com/dimiro1/lunar/releases) page (`lunar-cli_*` archives).\n\n### AI Agent Skills\n\nAI agent skills require the CLI to be installed first.\n\nLunar ships built-in skill definitions that teach your AI coding agent how to use the CLI and write Lua functions.\n\n```bash\nlunar-cli skills list             # show available skills\nlunar-cli skills show lunar-cli   # CLI command reference\nlunar-cli skills show lunar-lua   # Lua function authoring guide\n```\n\nTo install them, ask your agent:\n\n\u003e \"Install the Lunar skills from the `lunar-cli skills` command.\"\n\n### Authentication\n\n```bash\n# Start the device authorization flow (opens a browser tab for approval)\nlunar-cli --server http://your-lunar-server login\n\n# If the browser does not open automatically, use the printed approval URL and code.\n\n# The token is saved to ~/.config/lunar/config.yaml automatically\n# To log out and clear the stored token:\nlunar-cli logout\n```\n\nYou can also skip the login flow and pass a token directly:\n\n```bash\nlunar-cli --token YOUR_API_KEY functions list\n\n# Or via environment variable:\nexport LUNAR_SERVER=http://your-lunar-server\nexport LUNAR_TOKEN=YOUR_API_KEY\nlunar-cli functions list\n```\n\n### Configuration\n\nThe CLI stores its configuration in `~/.config/lunar/config.yaml`:\n\n```yaml\nserver: http://localhost:3000\ntoken: \u003cyour-api-token\u003e\n```\n\nFlags and environment variables always take precedence over the config file:\n\n| Priority | Source |\n|----------|--------|\n| 1 (highest) | `--server` / `--token` flags |\n| 2 | `LUNAR_SERVER` / `LUNAR_TOKEN` env vars |\n| 3 | `~/.config/lunar/config.yaml` |\n\n### Commands\n\n#### Functions\n\n```bash\nlunar-cli functions list [--limit 20] [--offset 0]\nlunar-cli functions create --name hello-world --code handler.lua\nlunar-cli functions create --name hello-world --code -  # read code from stdin\nlunar-cli functions get \u003cid\u003e\nlunar-cli functions update \u003cid\u003e --name new-name\nlunar-cli functions update \u003cid\u003e --cron-schedule \"*/5 * * * *\" --cron-status active\nlunar-cli functions update \u003cid\u003e --disabled\nlunar-cli functions delete \u003cid\u003e\nlunar-cli functions env \u003cid\u003e --env API_KEY=secret --env DEBUG=true\nlunar-cli functions kv \u003cid\u003e --kv counter=0 --kv state=idle\nlunar-cli functions kv \u003cid\u003e --kv shared=value --global   # write to global KV\nlunar-cli functions next-run \u003cid\u003e\n```\n\n#### Versions\n\n```bash\nlunar-cli versions list \u003cfunction-id\u003e\nlunar-cli versions get \u003cfunction-id\u003e \u003cversion-number\u003e\nlunar-cli versions activate \u003cfunction-id\u003e \u003cversion-id\u003e\nlunar-cli versions delete \u003cfunction-id\u003e \u003cversion-id\u003e\nlunar-cli versions diff \u003cfunction-id\u003e \u003cv1\u003e \u003cv2\u003e\n```\n\n#### Executions\n\n```bash\nlunar-cli executions list \u003cfunction-id\u003e\nlunar-cli executions get \u003cexecution-id\u003e\nlunar-cli executions logs \u003cexecution-id\u003e\nlunar-cli executions ai-requests \u003cexecution-id\u003e\nlunar-cli executions email-requests \u003cexecution-id\u003e\n```\n\n#### API Tokens\n\n```bash\nlunar-cli tokens list\nlunar-cli tokens revoke \u003ctoken-id\u003e\n```\n\n#### LLM Reference\n\n```bash\nlunar-cli llms\n```\n\n#### Invoke\n\nExecute a function directly without authentication (functions are public by default):\n\n```bash\nlunar-cli invoke \u003cfunction-id\u003e\nlunar-cli invoke \u003cfunction-id\u003e --method POST --body '{\"key\":\"value\"}'\nlunar-cli invoke \u003cfunction-id\u003e --method POST --body -   # read body from stdin\n```\n\n### Keeping the CLI in Sync with the API\n\nThe CLI commands are auto-generated from `internal/api/docs/openapi.yaml`. When the API changes, regenerate with:\n\n```bash\ncd cli\ngo generate ./...\ngo build ./...\n```\n\n## Testing\n\n### Go Tests\n\nRun the Go unit tests:\n\n```bash\nmake test\n```\n\n### Frontend Tests (Jasmine)\n\nThe frontend uses [Jasmine](https://jasmine.github.io/) for unit testing, running directly in the browser without Node.js dependencies.\n\n```bash\nmake test-frontend\n```\n\nThis starts a local Go server and opens the test runner at `http://localhost:8888/test/SpecRunner.html`. Tests cover:\n\n- Route URL generators\n- UI components (Button, Badge, Table, Pagination, ...)\n\n### E2E Tests (chromedp)\n\nEnd-to-end tests use [chromedp](https://github.com/chromedp/chromedp) to run a headless Chrome browser:\n\nMake sure Chrome or Chromium is installed before running them.\n\n```bash\nmake test-e2e\n```\n\nE2E tests cover:\n\n- Login flow\n- Page navigation\n- Functions list rendering\n\n### Run All Tests\n\n```bash\nmake test-all\n```\n\nThis runs Go unit tests and E2E tests. Run `make test-frontend` separately to open the browser-based Jasmine tests.\n\n## Architecture\n\n* **Backend** - Go with standard library HTTP server, SQLite database\n* **Frontend** - Mithril.js SPA with Monaco Editor\n* **Runtime** - GopherLua for Lua script execution\n* **Storage** - SQLite for functions, versions, executions, KV store, and environment variables\n\n### Frontend Dependencies\n\nJavaScript dependencies are vendored in `frontend/vendor/` (no npm required). Versions are managed in the Makefile:\n\n| Library | Purpose |\n|---------|---------|\n| Mithril.js | SPA framework |\n| Monaco Editor | Code editor |\n| Highlight.js | Syntax highlighting |\n| Jasmine | Frontend testing |\n\nTo update dependencies, edit the version variables in the Makefile and run:\n\n```bash\nmake vendor-js\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n\n## Author\n\nClaudemiro Alves Feitosa Neto\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimiro1%2Flunar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimiro1%2Flunar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimiro1%2Flunar/lists"}