{"id":50138861,"url":"https://github.com/slice-soft/ss-keel-examples","last_synced_at":"2026-05-24T00:03:32.753Z","repository":{"id":345854963,"uuid":"1175213517","full_name":"slice-soft/ss-keel-examples","owner":"slice-soft","description":"Self-contained example projects demonstrating Keel framework patterns","archived":false,"fork":false,"pushed_at":"2026-04-22T15:42:53.000Z","size":48877,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T17:36:24.526Z","etag":null,"topics":["examples","go","keel","slicesoft"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/slice-soft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2026-03-07T11:50:23.000Z","updated_at":"2026-04-22T15:42:56.000Z","dependencies_parsed_at":"2026-03-21T17:03:14.643Z","dependency_job_id":null,"html_url":"https://github.com/slice-soft/ss-keel-examples","commit_stats":null,"previous_names":["slice-soft/ss-keel-examples"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/slice-soft/ss-keel-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slice-soft%2Fss-keel-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slice-soft%2Fss-keel-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slice-soft%2Fss-keel-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slice-soft%2Fss-keel-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slice-soft","download_url":"https://codeload.github.com/slice-soft/ss-keel-examples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slice-soft%2Fss-keel-examples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33416316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"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":["examples","go","keel","slicesoft"],"created_at":"2026-05-24T00:03:24.137Z","updated_at":"2026-05-24T00:03:32.740Z","avatar_url":"https://github.com/slice-soft.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keel Examples\n\nA curated collection of example projects demonstrating how to build production-style services with the [Keel](https://keel-go.dev) framework and the [Keel CLI](https://github.com/slice-soft/ss-keel-cli).\n\nEach example is small, focused, and self-contained — you can run any of them independently in under a minute.\n\n---\n\n## What is Keel?\n\n[Keel](https://keel-go.dev) is a modular Go framework for building web services. It provides:\n\n- Structured modules, controllers, and services\n- Built-in health checks, request logging, and OpenAPI docs\n- Composable middleware and guards\n- Scheduler, event bus, and tracing hooks\n- First-class validation via struct tags\n\n---\n\n## Learning Path\n\nIf you are new to Keel, work through the examples in order:\n\n| Step | Example | Concept |\n|------|---------|---------|\n| 1 | [01-hello-world](./examples/01-hello-world) | Bootstrap a Keel app and define a route |\n| 2 | [02-config-env](./examples/02-config-env) | Load configuration from environment variables |\n| 3 | [03-health-check](./examples/03-health-check) | Add custom health checkers |\n| 4 | [04-rest-crud](./examples/04-rest-crud) | Build a complete CRUD REST service |\n| 5 | [05-validation](./examples/05-validation) | Validate request bodies with struct tags |\n| 6 | [06-middleware](./examples/06-middleware) | Write and apply custom middleware |\n| 7 | [07-jwt-auth](./examples/07-jwt-auth) | Protect routes with the ss-keel-jwt addon |\n| 8 | [08-gorm-postgres](./examples/08-gorm-postgres) | Persist data with GORM and PostgreSQL |\n| 9 | [09-scheduler-cron](./examples/09-scheduler-cron) | Schedule background jobs with cron |\n| 10 | [10-addon-example](./examples/10-addon-example) | Integrate a Keel addon |\n| 11 | [11-jwt-addon](./examples/11-jwt-addon) | JWT addon flow with refresh and RBAC |\n| 12 | [12-oauth](./examples/12-oauth) | OAuth2 login with GitHub and Google |\n| 13 | [13-mongo](./examples/13-mongo) | Document CRUD with MongoDB |\n| 14 | [14-redis-cache](./examples/14-redis-cache) | Cache-aside reads with Redis |\n| 15 | [15-devpanel](./examples/15-devpanel) | Real-time observability UI with the DevPanel addon |\n| 16 | [16-otel](./examples/16-otel) | Distributed tracing with the OpenTelemetry addon |\n\n---\n\n## Project structure note\n\nExamples 01–10 use the module pattern from `ss-keel-core` directly with a flat `main.go` at the repo root. Examples 11–16 (addon-based) follow the same flat layout intentionally, so each example stays self-contained and runnable without the Keel CLI scaffold.\n\nProjects created with `keel new` use a `cmd/main.go` layout with `application.properties` and `.env`/`.env.example`. When comparing example code against a generated project, translate root-level `main.go` to `cmd/main.go`.\n\n---\n\n## Examples\n\n### 01 — Hello World\nMinimal Keel app with a single `GET /hello` route. The starting point for every Keel service.\n\n### 02 — Config \u0026 Env\nStructured configuration loader using environment variables with typed defaults.\n\n### 03 — Health Check\nBuilt-in `/health` endpoint plus a custom `HealthChecker` that inspects an in-memory dependency.\n\n### 04 — REST CRUD\nFull CRUD for a `Task` resource: list, get, create, update, and delete — all in-memory, no database required.\n\n### 05 — Validation\nShows how Keel uses `validate` struct tags together with `ctx.ParseBody()` to return structured 422 errors automatically.\n\n### 06 — Middleware\nCustom request middleware: correlation ID injection, response timing header, and a simple IP blocklist.\n\n### 07 — JWT Auth\nJWT authentication using the [ss-keel-jwt](https://github.com/slice-soft/ss-keel-jwt) addon in a minimal login flow. Issues tokens on `POST /auth/login` and protects routes with the addon's reusable middleware.\n\n### 08 — GORM + PostgreSQL\nDatabase-backed CRUD using [ss-keel-gorm](https://github.com/slice-soft/ss-keel-gorm) with migrations, a repository pattern, and connection health checks.\n\n### 09 — Scheduler / Cron\nRegister recurring background jobs with the Keel scheduler. Includes a simple in-memory job that runs on a configurable cron expression.\n\n### 10 — Addon Example\nDemonstrates how to consume a Keel addon installed via the Keel CLI (`keel add`).\n\n### 11 — JWT Addon\nA deeper [ss-keel-jwt](https://github.com/slice-soft/ss-keel-jwt) addon example focused on token refresh, claims inspection, and role-based access control on top of `jwtProvider.Middleware()`.\n\n### 12 — OAuth2\nSocial login with GitHub and Google via the [ss-keel-oauth](https://github.com/slice-soft/ss-keel-oauth) addon. After the OAuth flow the addon issues a signed JWT so protected routes work identically to the JWT addon example.\n\n### 13 — MongoDB\nDocument CRUD using the [ss-keel-mongo](https://github.com/slice-soft/ss-keel-mongo) addon: `EntityBase`, a generic typed repository, pagination, partial updates, and a built-in MongoDB health checker.\n\n### 14 — Redis Cache\nCache-aside reads and invalidation using the [ss-keel-redis](https://github.com/slice-soft/ss-keel-redis) addon. The module receives `*ssredis.Client`, while the service depends on the generic `contracts.Cache` interface.\n\n### 15 — DevPanel\nReal-time observability UI powered by the [ss-keel-devpanel](https://github.com/slice-soft/ss-keel-devpanel) addon. Captures every HTTP request in a ring buffer, streams structured logs from `panel.Logger()`, and exposes config and route inspection — all in a browser UI at `/keel/panel`.\n\n### 16 — OpenTelemetry\nDistributed tracing and metrics via the [ss-keel-otel](https://github.com/slice-soft/ss-keel-otel) addon. Shows automatic HTTP spans from the OTel middleware, manual child spans with `app.Tracer().Start()`, span attributes, and error recording — with OTLP export to Jaeger.\n\n---\n\n## How to Run an Example\n\nEach example is an independent Go module. To run any example:\n\n```bash\n# 1. Enter the example directory\ncd examples/01-hello-world\n\n# 2. Copy the environment file\ncp .env.example .env\n\n# 3. Download dependencies\ngo mod download\n\n# 4. Run the service\ngo run main.go\n```\n\nThe server starts on port **7331** by default.\n\nOpen the interactive API docs at [http://localhost:7331/docs](http://localhost:7331/docs).\n\n\u003e **Note:** Some examples (08-gorm-postgres, 12-oauth, 13-mongo, 14-redis-cache, 16-otel) require Docker or external services. See each example's README for details.\n\u003e\n\u003e **Config:** Every example uses `application.properties` + `config.MustLoadConfig` for typed configuration — no manual `os.Getenv` calls needed.\n\n---\n\n## Repository Structure\n\n```\nss-keel-examples/\n├── examples/          # One subdirectory per example\n│   ├── 01-hello-world/\n│   ├── 02-config-env/\n│   └── ...\n├── shared/\n│   ├── docker/        # Shared Docker Compose files for dependencies\n│   └── scripts/       # Helper shell scripts\n└── docs/\n    ├── learning-path.md\n    └── example-matrix.md\n```\n\n---\n\n## Related Projects\n\n| Project | Description |\n|---------|-------------|\n| [ss-keel-core](https://github.com/slice-soft/ss-keel-core) | The Keel framework |\n| [ss-keel-cli](https://github.com/slice-soft/ss-keel-cli) | CLI for scaffolding Keel projects |\n| [ss-keel-docs](https://github.com/slice-soft/ss-keel-docs) | Official documentation |\n| [ss-keel-addon-template](https://github.com/slice-soft/ss-keel-addon-template) | Template for creating Keel addons |\n\n---\n\n## Contributing\n\nExamples that fix bugs, improve clarity, or add new concepts are welcome. Please open an issue first to discuss the change.\n\n## License\n\n[MIT](./LICENSE) — SliceSoft\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslice-soft%2Fss-keel-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslice-soft%2Fss-keel-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslice-soft%2Fss-keel-examples/lists"}