{"id":13753422,"url":"https://github.com/takama/caldera","last_synced_at":"2025-07-05T08:05:55.654Z","repository":{"id":52591339,"uuid":"148619414","full_name":"takama/caldera","owner":"takama","description":"Caldera allows you to create a boilerplate service that ready to run inside the container (Go language)","archived":false,"fork":false,"pushed_at":"2023-02-25T09:42:03.000Z","size":3431,"stargazers_count":119,"open_issues_count":7,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T06:35:41.199Z","etag":null,"topics":["boilerplate","container","docker","go","golang","kubernetes","microservice","template"],"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/takama.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-09-13T10:04:39.000Z","updated_at":"2024-03-06T19:53:32.000Z","dependencies_parsed_at":"2024-01-17T15:02:53.264Z","dependency_job_id":"68259030-2e03-4b46-8992-25f04743be3d","html_url":"https://github.com/takama/caldera","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/takama/caldera","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takama%2Fcaldera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takama%2Fcaldera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takama%2Fcaldera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takama%2Fcaldera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/takama","download_url":"https://codeload.github.com/takama/caldera/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/takama%2Fcaldera/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263707028,"owners_count":23499076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["boilerplate","container","docker","go","golang","kubernetes","microservice","template"],"created_at":"2024-08-03T09:01:21.913Z","updated_at":"2025-07-05T08:05:55.610Z","avatar_url":"https://github.com/takama.png","language":"Go","funding_links":[],"categories":["template"],"sub_categories":[],"readme":"# Caldera\n\nA command line utility Caldera allows you to create a boilerplate service that ready to run inside the container. This will save two or more days of developers working, who decided to create their first (micro) service.\n\n## Version  v0.2.5\n\nAll changes in the project described in [changelog](docs/CHANGELOG.md)\n\n## Features of the boilerplate service\n\n- gRPC/REST API example using protobuf\n- Implementation of the health checks\n- Configuring the service using config file, environment variables or flags\n- Processing of graceful shutdown for every registered component\n- Database interfaces with migration features\n- CI/CD pipelines integrated into Makefile\n- Helm charts for deploying the service in Kubernetes environment\n- Container SSL certificates integration for using a secure client\n- Integration of the package manager\n- Versioning automation\n\n### Features of the command line utility Caldera\n\n- Using of configuration file that contains your saved preferences for a new boilerplate service\n- Interactive mode to select preferred features for a new service\n- Using of CLI flags to create new service quickly\n\n## Requirements\n\n- [Go compiler](https://golang.org/dl/) v1.9 or newer\n- [GNU make utility](https://en.wikipedia.org/wiki/Make_(software)) that probably already installed on your system\n\n### Requirements for boilerplate service\n\n- Docker service, version 18.03 or newer\n\n## Setup\n\n```sh\ngo get -u github.com/takama/caldera\ncd $GOPATH/src/github.com/takama/caldera\nmake\n```\n\n## Usage of Caldera\n\n### Interactive mode\n\nIn this mode, you'll be asked about the general properties associated with the new service. The configuration file will be used for all other data, such as the host, port, etc., if you have saved it before. Otherwise, the default settings will be used.\n\n```txt\n./caldera\nCaldera boilerplate version: v0.2.0 build date: 2021-04-17T23:37:17+07\n\nProvide name for your Github account (my-account):\nProvide a name for your module or namespace (default):\nProvide name for your service (my-service): new-service\nProvide description for your service (New service): Very new service\nDo you need API for the service? (y/n): y\nDo you want gRPC (1) or gRPC+REST (2)?: 2\nDo you need CORS? (y/n): y\nDefault API version (v1):\nDo you need storage driver? (y/n): y\nDo you want postgres (1), mysql (2) or postgres+mysql (3)?: 1\nDo you need Contract API example for the service? (y/n): y\nDo you need to expose metrics for Prometheus? (y/n): y\nDo you want to deploy your service to the Google Kubernetes Engine? (y/n): y\nProvide ID of your project on the GCP (my-project-id):\nProvide compute region of your project on the GCP (europe-west4):\nProvide cluster name in the GKE (my-cluster-name):\nDefault Golang CI Linter version (1.32.2):\nTemplates directory (~/go/src/github.com/takama/caldera/.templates):\nNew service directory (~/go/src/github.com/my-account/my-service):\nDo you want initialize service repository with git (y/n): y\n```\n\n### CLI mode\n\nIn this mode, you'll be not asked about everything. The configuration file will be used for all other data, such as the host, port, etc., if you have saved it before. Otherwise, the default settings will be used.\n\n```sh\n./caldera new [ --service \u003cname\u003e --description \u003cdescription\u003e --github \u003caccount\u003e --grpc-client ]\n```\n\n### Save configuration for future use\n\nFor example of save a `storage` parameters in Caldera configuration file:\n\n```sh\n./caldera storage [flags]\n\nFlags:\n  -h, --help       help for storage\n      --enabled    A Storage modules using\n      --postgres   A postgres module using\n      --mysql      A mysql module using\n```\n\nSave a `storage` parameters for database driver in Caldera configuration file:\n\n```sh\n./caldera storage driver [flags]\n\nFlags:\n  -h, --help              help for driver\n      --host string       A host name (default \"postgres\")\n      --port int          A port number (default 5432)\n      --name string       A database name (default \"postgres\")\n  -u, --username string   A name of database user (default \"postgres\")\n  -p, --password string   An user password (default \"postgres\")\n      --max-conn int      Maximum available connections (default 10)\n      --idle-count int    Count of idle connections (default 1)\n      --idle-time int     Maximum amount of time in seconds a connection may be idle (default 60)\n```\n\nSave an `API` parameters for `REST/gRPC` (REST always used gRCP gateway):\n\n```sh\n./caldera api [flags]\n\nFlags:\n  -h, --help           help for api\n      --enabled        An API modules using\n      --grpc           A gRPC module using\n      --rest-gateway   A REST gateway module using\n```\n\nSave a common `API` parameters:\n\n```sh\n./caldera api config [flags]\n\nFlags:\n  -h, --help               help for config\n      --port int           A service port number (default 8000)\n      --gateway-port int   A service rest gateway port number (default 8001)\n```\n\n## gRPC/REST API example\n\nThis example contains a good approach to using the API with the code-generated Client/Server from the interfaces in the `.proto` definitions using the Go language. In addition, it contains a gRPC gateway that can be used to access the API via REST.\n\n```proto\n// Interface exported by the server\nservice Events {\n  // Get the Event object by ID\n  rpc GetEvent (request.ByID) returns (Event) {\n    option (google.api.http).get = \"/v1/events/id/{id}\";\n  }\n\n  // Find the Event objects by name\n  rpc FindEventsByName (request.ByName) returns (stream Event) {\n    option (google.api.http).get = \"/v1/events/name/{name}\";\n  }\n\n  // List all Events\n  rpc ListEvents (google.protobuf.Empty) returns (stream Event) {\n    option (google.api.http).get = \"/v1/events\";\n  }\n\n  // Create a new Event object\n  rpc CreateEvent (Event) returns (Event) {\n    option (google.api.http) = {\n      post: \"/v1/events\",\n      body: \"*\"\n    };\n  }\n\n  // Update the Event object\n  rpc UpdateEvent (Event) returns (Event) {\n    option (google.api.http) = {\n      put: \"/v1/events/id/{id}\",\n      body: \"*\"\n    };\n  }\n\n  // Delete the Event object by ID\n  rpc DeleteEvent (request.ByID) returns (google.protobuf.Empty) {\n    option (google.api.http).delete = \"/v1/events/id/{id}\";\n  }\n\n  // Delete The Event objects by Event name\n  rpc DeleteEventsByName (request.ByName) returns (google.protobuf.Empty) {\n    option (google.api.http).delete = \"/v1/events/name/{name}\";\n  }\n}\n```\n\n## Health checks\n\nService should have [health checks](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/) for successful execution in containers environment. It should helps with correct orchestration of the service.\n\n## Configuring\n\nThe [twelve factors](https://12factor.net/config) service must be configured using environment variables. The service has a built-in library for automatically recognizing and allocating environment variables that are stored inside `struct` of different types. As additional methods, a configuration file and flags are used. All these methods of setting are directly linked to each other in using of configuration variables.\n\n## System signals\n\nThe service has an ability to intercept system signals and transfer actions to special methods for graceful shutdown, maintenance mode, reload of configuration, etc.\n\n```go\ntype Signals struct {\n    shutdown    []os.Signal\n    reload      []os.Signal\n    maintenance []os.Signal\n}\n```\n\n## Database integration\n\nBoilerplate service is provided database drivers and optional `stub` driver for testing purposes.\nThe database drivers are using in local container environment as well. Corresponded `make` commands `db, migrate-up, migrate-down` allow to run database engine and migrate data into database.\nSupported the following database drivers:\n\n- Postgres\n- MySQL\n\n## Build automation\n\nIn the CI/CD pipeline, there is a series of commands for the static cross-compilation of the service for the specified OS. Build a docker image and push it into the container registry. Optimal and compact `docker` image `FROM SCRATCH`.\n\n```Dockerfile\nFROM scratch\n\nENV MY_SERVICE_SERVER_PORT 8000\nENV MY_SERVICE_INFO_PORT 8080\nENV MY_SERVICE_LOGGER_LEVEL 0\n\nEXPOSE $MY_SERVICE_SERVER_PORT\nEXPOSE $MY_SERVICE_INFO_PORT\n\nCOPY certs /etc/ssl/certs/\nCOPY migrations /migrations/\nCOPY bin/linux-amd64/service /\n\nCMD [\"/service\", \"serve\"]\n```\n\n## SSL support\n\nCertificates support for creating a secure SSL connection in the `Go` client. Attaching the certificate to the docker image.\n\n## Testing\n\nThe command `make test` is running set of checks and tests:\n\n- tool `go fmt` used on package sources\n- set of linters used on package sources (20+ types of linters)\n- tests used on package sources excluding vendor\n- a testing coverage of new boilerplate service\n- compile and check of Helm charts\n\n## Helm charts and Continuous Delivery\n\nA set of basic templates for the deployment of the service in Kubernetes has been prepared. Only one `make deploy` command loads the service into Kubernetes. Wait for the successful result, and the service will be ready to go.\n\n## Package manager\n\nTo properly work with dependencies, we need to select a package manager. `go mod` is dependency management tools for Go.\n\n## Versioning automation\n\nUsing a special script to increment the release version\n\n```sh\nmake version\nCurrent version v0.1.10.\nPlease enter new version [v0.2.0]:\n```\n\n## Contributing to the project\n\nSee the [contribution guidelines](docs/CONTRIBUTING.md) for information on how to participate in the Caldera project to submitting a pull request or creating a new issue.\n\n## License\n\n[MIT Public License](https://github.com/takama/caldera/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakama%2Fcaldera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftakama%2Fcaldera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftakama%2Fcaldera/lists"}