The boilerplate consists of:
- Go code with chi http router, zerolog logging, knadh/koanf config library and testify. Basic code infra with http setup and request and response logger (configurable), logging setup, config setup and graceful shutdown.
- Makefile targets for local installation of external tools (
staticcheck,golangci-lint,goimports,gofumpt,gojq,air). - Makefile targets for linting (installing all necessary tools locally), building, testing, and local run (docker compose or native).
- GitHub Actions for linter checks and tests on each pr.
- Dependabot setup for updating dependencies.
- Visual Studio Code settings, tasks and launch configuration for building, debugging and testing the code.
- Docker compose and development Dockerfile with hot-rebuild (using air) and dlv debug server.
- Production Dockerfile
- Click
Use this templatefrom this repo github page, and choose your destination repo/name (e.g.github.com/glendale/service) - Clone your repo locally and run
./scripts/renamegiving your new package name and main cmd name. E.g../scripts/rename github.com/glendale/service service. - Commit the renaming and you are ready to start.
Every local package that collides with a golang std package is named with
xpostfix. For example.../internal/httpxor.../internal/logx. By doing this cheat you can avoid putting aliases when you need both of those and you can take advantage of package autocomplete/autoimport features more easily than having colliding names.
| Package | Description |
|---|---|
cmd/*/main.go |
main function that is intended to glue together the most core level components like: configuration, http server and router, logs initialization, db connections (if any), the App and finally the Main struct (/internal/exec.go) that handles the long running / signal handling / graceful shutdown of the service. |
internal/exec.go |
the Main struct that wraps the long running / signal handling / graceful shutdown of the service |
internal/config |
this package contain the initialization of koanf config. |
internal/httpx |
this package contains: the setup of the chi router, some helpers functions for parsing/writing http request and http response and some middlewares like for logging each request/response. |
internal/logx |
this package contains the setup/init function for zerolog logger. |
| Folder/File | Description |
|---|---|
deployments |
this folder is intended to hold everything regarding deployment (e.g. helm/kubernetes etc). Inside compose directory a docker-compose.yml file is included that is intended for local development. |
build/docker |
this folder contains production-like docker file as well as a local development one. |
Builds all binaries under ./cmd (one for each directory) and outputs the binaries into ./output folder using this patter ./cmd/<directory name> -> ./output/<directory name>.
Builds a specific cmd directory <directory name> and outputs the binary into ./output folder using this pattern ./cmd/<directory name> -> ./output/<directory name>.
Deletes ./output folder.
Deploys (rebuilds and recreates) the docker compose file deployments/compose/docker-compose.yml in attached mode. This docker compose file is intended for local development.
It uses the docker file build/docker/debug.Dockerfile and runs air target (see below), including hot-reload (rebuild on changes) and debug server.
Stops (if started) the containers specified by the docker compose file deployments/compose/docker-compose.yml removes containers, cleans up the volumes and delete local docker images.
Installs (if needed) air under TOOLS_BIN folder (default is ./.tools/bin) and runs air -c .air.toml.
Air watches for code file changes and rebuilds the binary according to the configuration .air.toml.
Current air configuration executes cmd.goboilerplate target (on each file change) and then runs the ./build/dlv that starts the debug server (dlv exec) with the produced binary.
Builds the docker image using the docker file ./build/docker/Dockerfile.
This docker file is intended to be used as a production image.
Image name and tag are specified by IMAGE_NAME and IMAGE_TAG. Default values can be overwritten during execution (eg make IMAGE_NAME=myimage IMAGE_TAG=1.0.0 image).
Runs go mod vendor that downloads all dependencies into ./vendor folder.
Prints information regarding the local environment. More specifically: go env, all go packages and folders, and the specified tools bin directory.
Full hard reset to HEAD. Cleans up all untracked files and restore all staged and un-staged changes.
Runs go test with race conditions and prints cover report.
Installs (if needed) all tools (goimports, staticcheck, gofumpt, etc) under TOOLS_BIN folder (default is ./.tools/bin).
Runs all default checks (vet, staticcheck, gofumpt, goimports, golangci-lint).
Runs go vet.
Installs (if needed) gofumpt under TOOLS_BIN folder (default is ./.tools/bin) and runs gofumpt for each folder.
If gofumpt finds files that need fix/format it displays those files as list and the target fails (exit 1).
In case of gofumpt fails this target can be used to display the necessary changes. It runs gofumpt -d to display the needed changes that can be applied with make gofumpt.fix.
Runs gofumpt -w to fix/format files (that need fix).
Installs (if needed) goimports under TOOLS_BIN folder (default is ./.tools/bin) and runs goimports for each folder.
If goimports finds files that need fix/format it displays those files as list and the target fails (exit 1).
In case of goimports fails this target can be used to display the necessary changes. It runs goimports -d to display the needed changes that can be applied with make goimports.fix.
Runs goimports -w to fix files (that need fix).
Installs (if needed) staticcheck under TOOLS_BIN folder (default is ./.tools/bin) and runs staticcheck using all checks excluding ST1000.
If issues are found the target fails (due to staticcheck exit status).
Installs (if needed) golangci-lint under TOOLS_BIN folder (default is ./.tools/bin) and runs golangci-lint.
If issues are found the target fails (due to golangci-lint exit status).