{"id":16188988,"url":"https://github.com/fogfish/blueprint-serverless-golang","last_synced_at":"2025-03-19T03:30:45.852Z","repository":{"id":39675035,"uuid":"320933138","full_name":"fogfish/blueprint-serverless-golang","owner":"fogfish","description":"AWS CDK template for serverless Golang ","archived":false,"fork":false,"pushed_at":"2024-08-22T17:02:30.000Z","size":534,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-18T16:25:03.719Z","etag":null,"topics":["aws-api-gateway","aws-cdk","aws-cdk-construct","aws-cdk-go","aws-lambda","golang","serverless-golang"],"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/fogfish.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}},"created_at":"2020-12-12T22:03:30.000Z","updated_at":"2024-09-14T14:46:25.000Z","dependencies_parsed_at":"2024-10-30T09:31:00.133Z","dependency_job_id":"8f9ce175-e5b3-44f3-9ccb-9e811ec24500","html_url":"https://github.com/fogfish/blueprint-serverless-golang","commit_stats":{"total_commits":107,"total_committers":1,"mean_commits":107.0,"dds":0.0,"last_synced_commit":"e8be2bb26218ba3201e3307bc3088bd9f8b0970e"},"previous_names":[],"tags_count":1,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fblueprint-serverless-golang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fblueprint-serverless-golang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fblueprint-serverless-golang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fogfish%2Fblueprint-serverless-golang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fogfish","download_url":"https://codeload.github.com/fogfish/blueprint-serverless-golang/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243965774,"owners_count":20375917,"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":["aws-api-gateway","aws-cdk","aws-cdk-construct","aws-cdk-go","aws-lambda","golang","serverless-golang"],"created_at":"2024-10-10T07:33:13.039Z","updated_at":"2025-03-19T03:30:45.295Z","avatar_url":"https://github.com/fogfish.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./doc/logo.gif\" width=\"50%\"  /\u003e\n  \u003ch3 align=\"center\"\u003eBlueprint: Serverless Golang\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\u003cstrong\u003eSkeleton of Golang serverless application built with AWS CDK\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003c!-- Documentation --\u003e\n    \u003ca href=\"https://pkg.go.dev/github.com/fogfish/blueprint-serverless-golang\"\u003e\n      \u003cimg src=\"https://pkg.go.dev/badge/github.com/fogfish/blueprint-serverless-golang\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Build Status  --\u003e\n    \u003ca href=\"https://github.com/fogfish/blueprint-serverless-golang/actions/\"\u003e\n      \u003cimg src=\"https://github.com/fogfish/blueprint-serverless-golang/workflows/build/badge.svg\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- GitHub --\u003e\n    \u003ca href=\"http://github.com/fogfish/blueprint-serverless-golang\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/last-commit/fogfish/blueprint-serverless-golang.svg\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Coverage --\u003e\n    \u003ca href=\"https://coveralls.io/github/fogfish/blueprint-serverless-golang?branch=main\"\u003e\n      \u003cimg src=\"https://coveralls.io/repos/github/fogfish/blueprint-serverless-golang/badge.svg?branch=main\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Go Card --\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/fogfish/blueprint-serverless-golang\"\u003e\n      \u003cimg src=\"https://goreportcard.com/badge/github.com/fogfish/blueprint-serverless-golang\" /\u003e\n    \u003c/a\u003e\n    \u003c!-- Maintainability --\u003e\n    \u003ca href=\"https://codeclimate.com/github/fogfish/blueprint-serverless-golang/maintainability\"\u003e\n      \u003cimg src=\"https://api.codeclimate.com/v1/badges/1b00f59c9634d9d479cf/maintainability\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n--- \n\nThis project crafts a fully functional blueprint of Golang serverless RESTful application for Amazon Web Services. The blueprint is a hybrid solution, composed of pure \"application logic\" and Infrastructure as a Code implemented on top of AWS CDK, both developed with Golang. \n\n\n## Inspiration\n\n[AWS CDK](https://aws.amazon.com/cdk) is amazing technology to automate the development and operation of application into one process and one codebase.\n\nHowever, seeding of new repository for development of Golang serverless application requires a boilerplate code. This blueprint helps you to focus on the application development than waste a time with establish **project layout**, **configure AWS CDK**, **setting up CI/CD** and figuring out how to **testing the application**. All these issues are resolved within this blueprint.\n\n\n## Installation\n\nThe blueprint is fully functional application (Pet Store) that delivers a skeleton for Golang serverless development with AWS CDK. Clone the repository and follow [Getting started](#getting-started) instructions to evaluate its applicability for your purposes. It should take less than 5 minutes to build and deploy this blueprint to AWS.\n\n```\ngo get github.com/fogfish/blueprint-serverless-golang\n```\n\nSee [Getting Started](#getting-started) and [Customize Blueprint](#customize-blueprint) chapters for details.\n\n\n### Install from GitHub\n\n[**Use this template**](https://github.com/fogfish/blueprint-serverless-golang/generate)\n\nCreate a new GitHub repository from this blueprint.\n\n\n### Upgrade the template\n\nUse `git` features to update the blueprint from upstream\n\n```bash\ngit remote add blueprint https://github.com/fogfish/blueprint-serverless-golang\ngit fetch blueprint\ngit merge blueprint/main --allow-unrelated-histories --squash\n```\n\n## Requirements\n\nBefore Getting started, you have to ensure\n\n* [Golang](https://golang.org/dl/) development environment v1.16 or later\n* [assay-it](https://assay.it) utility for testing cloud apps in production \n* [AWS CDK](https://docs.aws.amazon.com/cdk/latest/guide/work-with.html#work-with-prerequisites) for deployment of serverless application using infrastructure as a code\n* [GitHub](https://github.com) account for managing source code and running CI/CD pipelines as [GitHub Actions](https://docs.github.com/en/actions)  \n* Account on [Amazon Web Services](https://aws.amazon.com) for running the application in production \n\n\n## Getting started\n\n**Let's have a look on the repository structure**\n\nThe structure resembles the mixture of [Standard package layout](https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1) and [Hexagonal architecture](https://medium.com/@matiasvarela/hexagonal-architecture-in-go-cfd4e436faa3). The proposed structure is better version of Hexagonal architecture that follows Golang best practices:\n\n1. the root is aws cdk application\n    \n2. Sub-packages to isolate dependencies to external technologies so that they act as bridge between your domain and technology adaptation. `internal` holds sub-packages internal to applications. `pkg` are sharable clients\n\n4. `cmd` contains main packages that build lambda functions and ties everything together.\n\n```\ngithub.com/.../the-beautiful-app\n├─ petshop.go                  // aws cdk main application  \n|\n├─ internal/awspetshop         // IaC, aws cdk application\n|\n├─ internal/core               // the root defines domain types, unit test \n|  |                           // \"algebra\" of your application. contains core\n|  |                           // types to describe domain of your application.\n|  |                           // It contains simple types that has no dependency\n|  |                           // to technology but their implements core logic\n|  |                           // and use-cases.\n|  |\n|  └─ storage.go               // defines capability requires to store core\n|                              // objects at the external storage, hex-arch\n|                              // use \"port\" concept to depict it          \n|\n├─ internal/storage            // sub-package for dependency/technology ...\n|                              // it follows the standard package layout to \n|                              // adapt domain/implementation/dependency.\n|                              // in this example storage implements in-memory\n|                              // database for all domain objects.  \n|\n├─ internal/services           // entry point to the core, implement app logic\n|  └─ pets                     // entire logic about pets domain\n|     ├─ fetcher.go            // fetch and enrich pets objects \n|     └─ creator.go            // create pets objects\n|\n├─ internal/mock               // shared mock\n|\n├─ internal/http               // public REST API exposed by application.\n|  ├─ petshop.go               // collection of petshop endpoints impl. by app\n|  |                           // endpoints consumer services using ports    \n|  | \n|  └─ suites                   // testing suites for api endpoint(s)\n|\n├─ cmd                         // executables of the project\n|  ├─ lambda                   // aws lambda's are main packages\n|  |  ├─ petshop               // each lambda stays at own executable\n|  |  |  └─ main.go            // single lambda pattern is not recommended\n|  | ...\n|  └─ server                   // run application as standalone server \n|     └─ main.go\n|\n├─ pkg/api                     // public domain objects used by application\n|                              // client library\n|\n└─ .github                     // CI/CD with GitHub Actions\n    └─ ...                   \n```\n\n### Development workflows\n\n**unit testing**\n\nTest the Golang application and its cloud infrastructure\n\n```bash\ngo test ./...\n```\n\n**local testing**\n\nRun application locally\n\n```bash\ngo run cmd/server/main.go\nassay-it test --target http://127.1:8080\n```\n\n**build**\n\nBuild entire application (both Golang and its AWS infrastructure). It should compile Golang code, assemble binaries for AWS Lambda and produce AWS CloudFormation template\n\n```bash\ncdk synth\n```\n\n**deploy**\n\nDeploy an application to AWS account, it requires a valid AWS credentials either access keys or assumed roles.\n\n```bash\ncdk deploy\n```\n\nIn few seconds, the application becomes available at\n\n```bash\ncurl https://xxxxxxxxxx.execute-api.eu-west-1.amazonaws.com/api\n```\n\nThe write path of api is protected by AWS IAM, request has to be signed.\nEither use example client `cmd/petshop-cli` or curl directly\n\n```bash\ncurl $BLUEPRINT/petshop/pets \\\n  -XGET \\\n  -H \"Accept: application/json\" \\\n  --aws-sigv4 \"aws:amz:eu-west-1:execute-api\" \\\n  --user \"$AWS_ACCESS_KEY_ID\":\"$AWS_SECRET_ACCESS_KEY\"\n```\n\nSee [all available endpoints](./http/petshop.go). \n\n\n**test in production**\n\n```bash\nassay-it test --target https://xxxxxxxxxx.execute-api.eu-west-1.amazonaws.com/api\n```\n\n\n**destroy**\n\nDestroy the application and remove all its resource from AWS account\n\n```bash\ncdk destroy\n```\n\n\n## Continuos Delivery \n\nContinuos Integration and Delivery is implemented using GitHub Actions. It consists of multiple [.github/workflows](.github/workflows).\n\n`AWS_ACCESS_KEY` and `AWS_SECRET_ACCESS_KEY` are required to enable deployment by GitHub Actions. Store these credentials to secret key vault at your fork settings (Your Fork \u003e Settings \u003e Secrets).\n\n### Check quality of Pull Request\n\nThe quality checks are executed every time a new change is proposed via Pull Request:\n* **checks** (`check-code.yml`) evaluates a quality of source code and reviews proposed changes (pull requests) using static code analysis.\n* **tests** (`check-test.yml`) the quality of software assets with scope on unit tests only and measures the test coverage.\n* **spawns** (`check-spawn.yml`) a sandbox(ed) deployment of the application to target AWS account for continuous integrations (optionally executed if pull request is marked with `[@] deploy` label);\n* **cleans** (`check-clean.yml`) sandbox environment after Pull Request is either merged or closed.\n\n### Check quality of `main` branch\n\nThe quality checks are executed every time a pull request is merged into pipeline:\n* **tests** (`check-test.yml`) the quality of software assets with scope on unit tests only and measures the test coverage.\n* **builds** (`build.yml`) validates quality of `main` branch once Pull Request is merge by deploying changes to the development environment at target AWS account;\n\n### Release of `main` branch\n\nThe quality checks are executed every time a new release is created:\n* **carries** (`carry.yml`) \"immutable\" application snapshot to production environment when GitHub release is published;\n\n\n## Customize Blueprint\n\n- [ ] rebuild go.mod and go.sum for your application\n- [ ] add RESTful api endpoints to [http](http) package\n- [ ] add Lambda functions to [aws/lambda](aws/lambda) package\n- [ ] set the name of your stack at [cloud/blueprint.go](cloud/src/blueprint.go) and enhance the infrastructure\n```go\nstackID := fmt.Sprintf(\"blueprint-golang-%s\", vsn(app))\nstack := awscdk.NewStack(app, jsii.String(stackID), config)\n```\n- [ ] update the target stack name at CI/CD workflows [check-spawn.yml](.github/workflows/check-spawn.yml), [build.yml](.github/workflows/build.yml), [carry.yml](.github/workflows/carry.yml) and [check-clean.yml](.github/workflows/check-clean.yml)\n```yaml\nstrategy:\n      matrix:\n        stack: [blueprint-golang]\n```\n- [ ] setup access to AWS account for CI/CD\n- [ ] integrate api testing \n- [ ] tune CI/CD pipeline according to purpose of your application either removing or commenting out blocks\n\n\n## How To Contribute\n\nThe blueprint is [MIT](LICENSE) licensed and accepts contributions via GitHub pull requests:\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Added some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n\n### commit message\n\nThe commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.\n\n### bugs\n\nIf you experience any issues with the library, please let us know via [GitHub issues](https://github.com/fogfish/blueprint-serverless-golang/issue). We appreciate detailed and accurate reports that help us to identity and replicate the issue. \n\n## License\n\n[![See LICENSE](https://img.shields.io/github/license/fogfish/blueprint-serverless-golang.svg?style=for-the-badge)](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fblueprint-serverless-golang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffogfish%2Fblueprint-serverless-golang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffogfish%2Fblueprint-serverless-golang/lists"}