{"id":17355173,"url":"https://github.com/zephinzer/goboil","last_synced_at":"2026-01-06T21:50:39.197Z","repository":{"id":79926642,"uuid":"156056048","full_name":"zephinzer/goboil","owner":"zephinzer","description":"Opinionated build tooling boilerplate for developing Golang applications with","archived":false,"fork":false,"pushed_at":"2018-11-08T01:45:24.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T18:27:11.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Makefile","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/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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-04T06:35:21.000Z","updated_at":"2018-11-08T01:42:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"9f21e0a4-c73b-4f42-898f-9d3cc8d07ff4","html_url":"https://github.com/zephinzer/goboil","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgoboil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgoboil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgoboil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgoboil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zephinzer","download_url":"https://codeload.github.com/zephinzer/goboil/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245858880,"owners_count":20684062,"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.616Z","updated_at":"2026-01-06T21:50:39.172Z","avatar_url":"https://github.com/zephinzer.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Golang Build Tooling Boilerplate\nOpinionated build tooling boilerplate for developing Golang applications with.\n\n[![Build Status](https://travis-ci.org/zephinzer/goboil.svg?branch=master)](https://travis-ci.org/zephinzer/goboil)\n\n# Scope\n## Non-Technical (Value Propositions)\n- Uses Docker images to eliminate development machine differences\n- Work on Golang applications outside of the `GOPATH`\n- Enables fast feedback cycle through live-reloading of app and tests\n- Sticks to the native Go build tooling for compilation\n- Integrates with common CI providers such as Travis and GitLab\n- Integrates with common CI tools such as CodeClimate and SonarQube\n\n## Technical\n- [x] Start application\n- [x] Start application with live-reloading\n- [x] Dependency management\n- [x] Environment configuration\n- [x] Test application with coverage\n- [x] Test application with live-reloading\n- [x] Compile binary\n- [x] Versioning capabilities\n- [x] Create production Docker image bundle\n- [x] Travis integration\n- [ ] GitLab integration\n- [ ] CodeClimate integration\n- [ ] SonarQube integration\n\n# Tooling Included\n- [Make for running common operations](https://www.gnu.org/software/make/)\n- [Realize for application live-reloading](https://github.com/oxequa/realize)\n- [Dep for dependency management](https://github.com/golang/dep)\n- [Auto-run.py from GoConvey for test live-reloading](https://github.com/smartystreets/goconvey/wiki/Auto-test)\n\n# Software Development Lifecycle\n\n## Dependency Management\n\nFor all `.local` postfixed commands, a best-attempt will be tried by symlinking the currect directory into your host machine's `${GOPATH}/src` and using that symlinked directory to run `dep`.\n\n### Initialisation\nRun `make dep ARGS=init` to initialize the dependencies *(you likely will not need this if you are seeding a project by cloning this repository)*.\n\n\u003e To run `dep` on your hostmachine, use `make dep.local ARGS=init`. You will need Dep installed and your directory needs to be within a valid `${GOPATH}/src` to do this.\n\n### Adding a Dependency\nRun `make dep ARGS=\"ensure -add ${DEPENDENCIES}\"` to add dependencies where `${DEPENDENCIES}` is a space-separated list of dependencies you wish to add.\n\n\u003e To run `dep` on your hostmachine, use `make dep.local ARGS=\"...\"`. You will need Dep installed and your directory needs to be within a valid `${GOPATH}/src` to do this.\n\n\n## Development\n\n### Getting Started in Development\n\nCopy `./sample.properties` into `./Makefile.properties` and set your required values there. These configurations are mostly for production image releasing so you may not need to change anything.\n\nRun `make start` to start the application in development with live-reload.\n\n\u003e To run the application on your host machine, use `make start.local`. You will need Go installed and a valid `GOPATH` set to do this.\n\nTo debug the application with a shell, run `make shell` to create a shell logged in as `root` into the running development container.\n\n### Configuring the Environment\n\nModify the `./.env` file to change the environment variables. A `.env` file looks like:\n\n```\nENV_VAR_1=\"value 1\"\nENV_VAR_2=value2\n# ....\n```\n\nThe above will add the environment variables `ENV_VAR_1` and `ENV_VAR_2` to your Docker image.\n\n## Testing\n\nAppend a `.local` to run the below on your host machine (`test.local`, `testc.local`, `testw.local`). Note that this may or may not work depending on what you have available on your host machine.\n\n### Standalone Tests\n\nRun `make test` to run the tests once.\n\n### Standalone Tests with Live-Reload\n\nRun `make testw` to run the tests in automated live-reload mode.\n\n\u003e Requires `python` to be installed on your machine. The script is at `./.scripts/auto-run.py` courtesy of GoConvey.\n\n### Standalone Tests with Coverage\n\nRun `make testc` to run the tests once and output the coverage.\n\n## Building\n\nRun `make build` to create the binary.\n\nTo use your host machine's Go installation, run `make build.local`\n\n## Releasing\n\nTo get the latest version of the application, use `make version.get`.\n\nTo bump the **patch** version, use `make version.bump`\n\nTo bump the **minor** version, use `make version.bump BUMP=minor`\n\nTo bump the **major** version, use `make version.bump BUMP=major`\n\n## Continuous Integration\n\nThe following environment variables should be set in your continuous integration environment for this to work:\n\n| Variable Name | Value Description |\n| --- | --- |\n| DOCKER_IMAGE | the name of the docker image  - namespace/THIS:tag - this defaults to `goboil` (this package) |\n| DOCKER_NAMESPACE | the namespace of the docker image - THIS/image_name:tag - this defaults to `zephinezr` (mine) |\n| DOCKER_REGISTRY | the registry of the docker image - THIS/namespace/image_name:tag - set to `docker.io` for Docker Hub |\n| DOCKER_REGISTRY_PASSWORD | password for your docker registry |\n| DOCKER_REGISTRY_USERNAME | username for your docker registry |\n| REPO_HTTPS_URL | your source control repository url in HTTPS format - this will be rebuit into `https://${USERNAME}:${TOKEN}@rest.of/your/repo.git` |\n| REPO_PERSONAL_ACCESS_TOKEN | your personal access token to your repository for pushing tags |\n| REPO_USERNAME | your username to your repository for pushing tags |\n\n### Travis\n\nThe provided `./.travis.yml` file provides a simple build \u003e test \u003e release \u003e publish cycle. To start using this, follow the steps below:\n\n1. [Create a personal access token](https://github.com/settings/tokens) with `repo` access on GitHub\n1. Go to Travis and [enable your repository](https://travis-ci.org/account/repositories)\n1. Go to your repository's page on Travis and click on **More options** \u003e **Settings** and add the environment variables as stated above\n\n\n## Containerisation\n\n\u003e Note: to ensure you publish to the correct repository, confirm that your settings in `./Makefile.properties` is correct.\n\n### Creating the Image\n\nTo create a production image, use `make dkbuild`. An image should be created named with your directory name and tagged with `:latest`.\n\nTo create a development image, use `make dkbuild.dev`. An image should be created named with your directory name and tagged with `:dev-latest`.\n\n### Publishing the Image\n\nTo publish the production image, use `make dkpublish`.\n\nTo publish the development image, use `make dkpublish.dev`.\n\n# Methodology\n\n## Live Reloading\n\nLive-reloading of a server allows for a quick feedback cycle which allows developers to experience changes they made in terms of application behaviour. The Realize CLI tool is used to do this for the application code.\n\nFor tests, a Python script originally from GoConvey is being used. See the [./.scripts/auto-run.py](./.scripts/auto-run.py) for more information on this.\n\n## Configuration\n\nA `.env` file was chosen to decide the environment which the Docker containers will load upon instantiation. This is the easiest way I know of to inject environment variables into a system, but it has the down-side of having to re-run the `make start` command if an environment variable changes.\n\nA viable alternative is to use a `.yaml` file in development but draw from the environment in production based on the mode set. However, I felt this changes the behaviour of the application based on environment and isn't a clean solution too.\n\n## Quality Assurance\n\nTest coverage is a useful quick-win (but non-essential) metric we can use to estimate technical debt. The default coverage tool is used when `make testc` (run test with coverage) is run.\n\nThe standard `go test` is handy enough without any frameworks, so to create a more lightweight setup, no frameworks were added.\n\n## Containerisation\n\nCloud-native is all the buzz. This boilerplate includes convenience recipes to create an image with your Golang binary to avoid \"it works on my machine\" issues.\n\n### Dockerfile\n\nThe Dockerfile is split into three build stages:\n\n1. **development**: in this stage, development dependencies and convenience tools are available. When built, this image contains the source code only without binaries. This image works for files being mounted onto the directory at `/go/src/${PROJECT_NAME}` where `${PROJECT_NAME}` will default to the name of your host directory. This eliminates the need for a valid `GOPATH` on the host machine.\n1. **compile**: this stage includes everything from **development** and includes the binary. Useful for debugging the production environment.\n1. **production**: this stage contains only production level stuff like your binary. No development convenience tools or dependencies are here and permissions are restricted.\n\n# License\nThis project is licensed under the permissive MIT license. See [LICENSE](./LICENSE) for the full text.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fgoboil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzephinzer%2Fgoboil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fgoboil/lists"}