{"id":15034572,"url":"https://github.com/begmaroman/go-micro-boilerplate","last_synced_at":"2025-05-16T15:03:57.273Z","repository":{"id":38600805,"uuid":"255649615","full_name":"begmaroman/go-micro-boilerplate","owner":"begmaroman","description":"The boilerplate of the GoLang application with a clear microservices architecture.","archived":false,"fork":false,"pushed_at":"2024-12-24T12:46:52.000Z","size":378,"stargazers_count":271,"open_issues_count":3,"forks_count":75,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-12T12:55:05.740Z","etag":null,"topics":["boilerplate","docker","docker-compose","example","go","go-micro","golang","golang-examples","golang-server","grpc","microservice","microservice-example","microservices","microservices-architecture","nats","protobuf","protocol-buffers","rpc","swagger"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/begmaroman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-04-14T15:35:28.000Z","updated_at":"2025-04-09T09:49:21.000Z","dependencies_parsed_at":"2024-12-03T22:24:01.680Z","dependency_job_id":"994319c0-2ac2-4e43-ba6d-ac4a413450cb","html_url":"https://github.com/begmaroman/go-micro-boilerplate","commit_stats":{"total_commits":54,"total_committers":2,"mean_commits":27.0,"dds":0.2407407407407407,"last_synced_commit":"56f561c7bf5b08fed143ee0d5020b2bab1c22429"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begmaroman%2Fgo-micro-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begmaroman%2Fgo-micro-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begmaroman%2Fgo-micro-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/begmaroman%2Fgo-micro-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/begmaroman","download_url":"https://codeload.github.com/begmaroman/go-micro-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553937,"owners_count":22090416,"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","docker","docker-compose","example","go","go-micro","golang","golang-examples","golang-server","grpc","microservice","microservice-example","microservices","microservices-architecture","nats","protobuf","protocol-buffers","rpc","swagger"],"created_at":"2024-09-24T20:25:32.939Z","updated_at":"2025-05-16T15:03:57.223Z","avatar_url":"https://github.com/begmaroman.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[go]: https://golang.org/doc/install\n[gomicro]: https://github.com/micro/go-micro\n[nats]: https://nats.io/\n[docker]: https://www.docker.com/\n[dockercompose]: https://docs.docker.com/compose/\n[gomodules]: https://blog.golang.org/using-go-modules\n[protoc]: https://github.com/google/protobuf/releases\n[swagger]: https://swagger.io/\n\n*NOTE 1: If something is not fully clear, feel free to create an issue. \nLet's create an excellent boilerplate together!*\n\n*NOTE 2: There are no tests in the project, this is a different story :)*\n\n# Go Micro Boilerplate\n\nGo Micro Boilerplate is the example of the [GoLang][go] project based on the microservices architecture.\n\nThis project provides simple functionality to perform CRUD operations related to the user entity.\n\nThere are two microservices, one web service that exposes REST API, \nand the second one is the RPC microservice that implements functionality to work with users, \nbasically this service is responsible for the business logic. \n\nOnce a user sends an HTTP request to the web service, it handles the incoming request, prepares data\nand calls the RPC service through RPC request using protobuf models.\nThe RPC service handles this request, applies some business logic, and updates/reads the data store.\n\n### Technologies\n\n[Go Micro][gomicro] framework provides the core requirements for distributed systems development \nincluding RPC and Event driven communication.\nRead more about this framework on their official [GitHub page][gomicro].\n\n![go micro](./docs/gomicro.svg)\n\nWe use [NATS][nats] as a discovery service, message broker service, and transport channel.\n\nAll services are [dockerized][docker] and can be adjusted by [docker-compose][dockercompose] configuration.\nCheck Dockerfiles and docker-compose.yaml file in the root of the project.\n\nUse [Go modules][gomodules] to manage dependencies of the project. \n\n[Swagger][swagger] is used to define the REST API of the platform. \nIt's really easy to maintain your REST API logic using this tool. \nReview it in `rest-api-svc` service.\n\n### Install [protoc][protoc]\n\nUse Protobufs as part of our toolchain so you need to [grab a release][protoc] \nfrom upstream before you can create a project. \nOn macOS you can do this with just `brew install protobuf`, if you'd like.\nOn Linux try to do the following:\n```bash\n$ cd ./~\n$ export PROTOBUF_VERSION=3.11.4\n$ curl -sOL \"https://github.com/google/protobuf/releases/download/v${PROTOBUF_VERSION}/protoc-${PROTOBUF_VERSION}-linux-x86_64.zip\" \u0026\u0026 \\\n$ unzip protoc-*.zip              \u0026\u0026 \\\n$ mv bin/protoc /usr/local/bin    \u0026\u0026 \\\n$ mv include/* /usr/local/include \u0026\u0026 \\\n$ rm -f protoc-*.zip\n```\n\n### Install other go tools\n\nThere are a few other go tools that are needed to develop and build the project.\nOpen your terminal and execute the following command:\n```bash\n$ go install \\\n    github.com/go-openapi/runtime \\\n    github.com/tylerb/graceful \\\n    github.com/jessevdk/go-flags \\\n    github.com/micro/protoc-gen-micro \\\n    github.com/golang/protobuf/protoc-gen-go \\\n    github.com/go-swagger/go-swagger/cmd/swagger\n```\n\n\n### Run locally\n\nTo run services locally you have to install [docker][docker] and [docker-compose][dockercompose]. \n\nOnce it's done, you have to build the base image:\n```bash\n$ make build-base-image\n```\nThis is needed to prepare common things for all services to avoid doing the same work multiple times.\n\nNow you have to use the following command to build and start all services:\n```bash\n$ docker-compose up -d --build\n```\n\nTo stop services use:\n```bash\n$ docker-compose stop\n```\n\n### Structure of the project:\n\nThis section describes and explains the files and directories structure of the project. \n\n#### `./proto` directory\n\nContains protocol buffers models of each service where it exists.\nYour services use protocol buffer messages as the main communication objects.\n\n#### `./services` directory\n \nContains all services of the project.\n\nOnce you want to create a new service, you may create a new directory with `\u003cservice-name\u003e-svc` format.\nInside of the created directory you can put the logic of your service like it's done with `account-svc`.\n \n#### `./pkg` directory\n \nContains common packages used across the services.\n\n#### `./vendor` directory (git ignored)\n\nContains dependencies. Execute the following from the root of the project to setup `vendor`:\n```bash\n$ export GO111MODULE=on\n$ go mod download\n$ go mod vendor\n```\n\n#### `./docker-compose.yaml` directory\n \nContains configuration of services to run inside docker containers.\nIf you want to add a new service there, you can use the way how it's done with `account-svc`.\nUseful commands:\n- `docker-compose up -d --build` - restart all services.\n- `docker-compose up -d --build \u003cservice-name\u003e` - restart a certain service.\n- `docker-compose down` - destroy all services. All data will be removed.\n- `docker-compose stop` - stop all services.\n    \n#### `./go.mod` and `./go.sum` files\n \nThese files are needed to manage dependencies using [go modules][gomodules].\nWhen you add/remove dependency from the project, these files gonna be modified.\n\n#### `./.env` file\n \nThis contains environment variables that pass to services \nwhen we run them using docker-compose (see `docker-compose.yaml`).\n\n\n#### `./README.md` file\n \nThis is recommended to describe your project.\n\n## Structure of services\n\n![go micro](./docs/infra.png)\n\nThis section describes and explains architecture of microservices both web and RPC.\nAll services should be in `./services` directory. Use `\u003cservicename\u003e-svc` format to name services.\n\nThere are two microservices in this project:\n\n- `rest-api-svc` is the web service that exposes REST endpoints. \n    It allows users to perform operations in other services.\n    You can serve Swagger UI by doing the following:\n    ```bash\n    $ docker-compose up -d api-spec  \n    ```\n    And open `localhost:4005` after that command. \n\n- `account-svc` is the RPC microservice that provides some business logic related to users.\n\n\n### Structure of an RPC service:\n\nAs an example, `account-svc` is described below.\n\n![go micro](./docs/layers.png)\n\nThere are 3 layers:\n\n- **Transport layer** represents the API of the service. \n    It can be implemented using HTTP, RPC, WS, etc. \n    This layer prepares and passes data to pass to the service layer.\n    No business logic inside of this layer.\n\n- **Domain/business layer** represents the business/domain logic of the service. \n    This layer doesn't care about transport and must not depend on it.\n    All business logic must be implemented in this layer.\n\n- **Store layer** represents the behavior of the data store. \n    It can be implemented using PostgreSQL, MongoDB, etc. databases, this is the internal implementation.\n    Only store layer knows about the kind of database inside.\n    A data just come from the outside of this layer. No business logic inside of this layer.\n\nThe most important thing about clean architecture is to make interfaces through each layer.\nDon't build dependencies on implementations, use interfaces instead.\nEach of these layers has its own interface that describes the behavior of it.\n\n- `Dockerfile` is the dockerfile of the service.\n- `entrypoint.sh` is the entrypoint script of the service. \n    This script can load some external data like secrets, passwords, etc.\n- `handler.go` implements proto service interface defined in the proto model of a service.\n    This is the transport layer of the service.\n- `domain` contains the business logic.\n- `store` is the store layer.\n- `microservice` implements functionality to setup and configure your microservice. \n    No business logic inside.\n- `cmd` contains the main package.\n\n### Structure of web service:\n\nAs an example, `rest-api-svc` is described below.\n\nThis service provides REST API to users. Requests from users are handled by `rest-api-svc`\nand redirected to other RPC services.\n\nWe use [Swagger][swagger] to describe REST API of the project.\n\n- `Dockerfile` is the dockerfile of the service.\n- `entrypoint.sh` is the entrypoint script of the service. \n    This script can load some external data like secrets, passwords, etc.\n- `handler.go` sets up the swagger API of the service.\n- `swaggergen` contains generated Swagger models.\n- `specs` contains Swagger file that describes REST API of the project.\n- `microservice` implements functionality to setup and configure your microservice. \n    No business logic inside.\n- `cmd` contains the main package.\n- `account` contains handlers of endpoints that are related to the account logic.\n\n## Inspired by\n\n- [GoLang][go]\n- [Go Micro][gomicro]\n- [NATS][nats]\n- [Docker][docker]\n- [docker-compose][dockercompose]\n- [Swagger][swagger]\n\n## TODO\n\n- Add a cli tool to generate a simple microservice. It will be in a new repo.\n- Add protected endpoints. \n- Add example of usage of postgres, and redis.\n\n\nDonate ETH: 0xc81A7a2b1bbC8D0CD09bf7eBdB8ac5A635711B5f\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbegmaroman%2Fgo-micro-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbegmaroman%2Fgo-micro-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbegmaroman%2Fgo-micro-boilerplate/lists"}