{"id":17355171,"url":"https://github.com/zephinzer/template-go-service","last_synced_at":"2025-03-27T15:22:04.993Z","repository":{"id":187027501,"uuid":"676190420","full_name":"zephinzer/template-go-service","owner":"zephinzer","description":"Template for a Go service that has HTTP server, worker, and job components. Includes local setups for multiple databases via Docker Compose and deployment manifests for Kubernetes via Helm","archived":false,"fork":false,"pushed_at":"2023-12-23T18:23:28.000Z","size":181,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-01T19:14:08.649Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zephinzer.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}},"created_at":"2023-08-08T16:22:31.000Z","updated_at":"2023-12-23T18:23:47.000Z","dependencies_parsed_at":"2023-12-23T20:27:58.717Z","dependency_job_id":null,"html_url":"https://github.com/zephinzer/template-go-service","commit_stats":null,"previous_names":["zephinzer/template-go-service"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Ftemplate-go-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Ftemplate-go-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Ftemplate-go-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Ftemplate-go-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zephinzer","download_url":"https://codeload.github.com/zephinzer/template-go-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245868335,"owners_count":20685609,"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":[],"created_at":"2024-10-15T17:42:32.450Z","updated_at":"2025-03-27T15:22:04.946Z","avatar_url":"https://github.com/zephinzer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Template Go Service\n\nThis is a template repository that provides boilerplate code for a service written in Go.\n\n**Supported data stores**\n- Kafka\n- MongoDB\n- MySQL\n- NATS\n- PostgreSQL\n- Redis\n\n**Supported deployment methods**\n- Kubenretes via Helm\n\n# Boilerplate information\n\n## Directory structure\n\n| Directory path | Description |\n| --- | --- |\n| `/.data` | Persistent data storage |\n| `/bin` | Contains built binaries |\n| `/cmd` | Contains command entrypoints |\n| `/deploy` | Contains deployment manifests |\n| `/internal` | Contains app-related packages |\n| `-\u003e ./api` | Contains HTTP-related packages and defines mainly routing |\n| `-\u003e ./constants` | Contains build configurations and app-wide constants |\n| `-\u003e ./database` | Contains database connection management code |\n| `-\u003e ./docs` | Contains Swagger documentation |\n| `-\u003e ./example` | Contains an example endpoint that connects to the HTTP API |\n| `-\u003e ./server` | Contains the server instance code |\n| `/tests` | Contains test artifacts |\n| `/vendor` | Contains dependenices |\n\n## CLI information\n\nTo test the CLI you can run `go run ./cmd/app`, help information should be available.\n\nThe following commands are included in the boilerplate which you can remove if not applicable to your project:\n\n- `app debug kafka` - tests the connection to Kafka (run `make kafka-jks` and `make start-kafka` before this)\n- `app debug mongo` - tests the connection to MongoDB (run `make start-mongo` before this)\n- `app debug mysql` - tests the connection to MySQL (run `make start-mysql` before this)\n- `app debug nats` - tests the connection to NATS (run `make start-nats` before this)\n- `app debug postgres` - tests the connection to PostgreSQL (run `make start-postgres` before this)\n- `app debug redis` - tests the connection to Redis (run `make start-redis` before this)\n- `app start job` - sample command to start a one-time job\n- `app start server` - sample command to start the server\n- `app start worker` - sample command to start a worker service\n\n\n## Notable packages and software used\n\n### Go\n\n1. [`cobra`](https://github.com/spf13/cobra) for structuring the app's CLI invocations and flags configuration\n1. [`viper`](https://github.com/spf13/viper) for managing configuration on a service level\n1. [`gofiber`](https://github.com/gofiber/fiber) for the HTTP server and HTTP API scaffolding\n2. [`swaggo`](https://github.com/swaggo/swag) to generate Swagger documentation\n\n### Tooling\n\n1. [Docker](https://www.docker.com/) for build/release packaging\n2. [Docker Compose](https://docs.docker.com/compose/) for bringing up development services\n3. [KinD](https://github.com/kubernetes-sigs/kind/) for bringing up a local Kubernetes cluster\n4. [`nk`](https://github.com/nats-io/nkeys) for generating NATS nkeys\n5. [Make](https://www.gnu.org/software/make/) for development operations recipes\n\n### Supported data stores\n\n#### Queues/Message brokers\n\n1. Kafka\n5. NATS for queueing/message brokering\n\n#### Relational databases\n7. MySQL for RDBMS usage\n8. PostgreSQL for RDBMS usage\n\n#### NoSQL/document databases/Key stores\n9.  MongoDB for NoSQL usage\n10. Redis for caching\n\n## SDLC Usage\n\n### Development operations\n\nThis repository uses Makefile for storing development operations. Included operations are:\n\n- `make binary` builds the binary and stores it in `./bin/`\n- `make deploy-kind` deploys the application onto a local Kubernetes cluster\n- `make deploy-k8s` deploys the application onto the currently selected Kubernetes cluster\n- `make deps` pulls in the dependencies into `./vendor/`\n- `make docs` generates all documentation\n- `make docs-swaggo` generates just the Swagger documentation using `swaggo`\n- `make image` builds the Docker image\n- `make install-swaggo` installs `swaggo` at the latest version\n- `make kafka-jks` generates the keys and certificates required for Kafka security\n- `make kind-load` loads the image into the local Kubernetes cluster\n- `make nats-nkey` creates a new nkey for use with NATS\n- `make publish-image` publishes the image in it's current form using a concatenation of `${GIT_BRANCH}` and `${GIT_COMMIT_SHA}` separated by a `-` as the image tag\n- `make start` starts the HTTP server using defaults\n- `make start-kafka` starts a local Kafka instance via Docker Compose\n- `make start-kind` starts a local Kubernetes cluster with KinD\n- `make start-mongo` starts a local MongoDB instance\n- `make start-mysql` starts a local MySQL instance\n- `make start-nats` starts a local NATS instance\n- `make start-postgres` starts a local PostgreSQL instance\n- `make start-redis` starts a local Redis instance\n- `make test` runs tests on the application and produces coverage artifacts at `./tests/`\n\nTo configure the Makefile recipes, create a new `Makefile.properties` in the root of this repository. Configurable values can be found in the `Makefile` above the line `-include Makefile.properties`.\n\nSome common configurations are documented below. Insert the code snippets into `Makefile.properties`.\n\nSee the [`./Makefile`](Makefile) for full details\n\n### Database connections\n\nSample connection code with test pings can be found in [`./cmd/app/commands/debug`](./cmd/app/commands/debug).\n\nAll database packages at [`./internal/database`](./internal/database) expose the global interface:\n\n- `Db(name ...string)`: Use this to retrieve a database connection. If `name` is specified, the named connection will be returned.\n- `Init(opts database.ConnectionOpts, name ...string)`: Use this to initialise a database connection. If `name` is specified, a named connection will be created and added to a map of connections which you can retrieve using `Db(connectionName)`.\n- `Close(name ...string)`: Use this to close connections you no longer need. If `name` is specified, a named connection will be closed and removed from the connection map. You need to call this before you `Init()` another connection with the same name.\n\nNamed connections can be used to implement logical tenant separations at the connection level. For example for B2B businesses where each tenant has a separate database instance, a new connection for `tenantA` can be initialised using `Init(opts, \"tenantA\")` and retrieved using `Db(\"tenantA\")`.\n\n### Building on top of the boilerplate\n\n#### Changing the application name\n\nInsert the following into `Makefile.properties`:\n\n```Makefile\nAPP_NAME := \"app2\"\n```\n\nYou will also need to:\n1. Rename the module in `go.mod` to `app2` and run `go mod vendor`\n2. Rename the chart in `./deploy/charts/app/Chart.yaml` to `app2`\n3. Rename the directory `./deploy/charts/app` to `./deploy/charts/app2`\n4. Rename the directory in `./cmd/app` to `./cmd/app2`\n\n#### Changing the Docker image URL\n\nInsert the following into `Makefile.properties`:\n\n```Makefile\nIMAGE_REGISTRY := \"docker.registry.domain.com\"\nIMAGE_PATH := \"your-org/your-app\"\nIMAGE_TAG := \"main-123456\"\n```\n\nThis example will cause images to be tagged and pushed to `docker.registry.domain.com/your-org/your-app:main-123456`\n\n#### Adding a new functional domain\n\nDomains should be in their own internal package in `./internal/`. A package should contain both the controllers and the HTTP interfaces exposed with a reference performed in `./internal/api/`\n\nAn example with both controllers and HTTP interfaces can be found in `./internal/example` for an `example` domain.\n\n### Pre-production checklist\n\nThis repository being a boilerplate contains some redunancies like database code which might not be used depending on your service. Before going to production:\n\n- [ ] Helm chart is name appropriately\n- [ ] Service is named appropriately\n- [ ] Remove the `./cmd/app/commands/debug/*` directories that aren't used. Eg if MongoDB is not used, remove `./cmd/app/commands/debug/mongo` and remove the reference to it in `./cmd/app/commands/debug/debug.go`. This way, code for handling that database type will not be included in your binary.\n- [ ] Disable Swagger in production (unless you want it in production)\n- [ ] Generate fresh keys on a privileged system and delete any keys that come with the boilerplate\n\n# Licensing\n\nSee [`./LICENSE`](./LICENSE). Basically, do whatever you want with this.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Ftemplate-go-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzephinzer%2Ftemplate-go-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Ftemplate-go-service/lists"}