{"id":21540366,"url":"https://github.com/circa10a/go-rest-template","last_synced_at":"2026-02-10T01:15:51.279Z","repository":{"id":262353506,"uuid":"886945456","full_name":"circa10a/go-rest-template","owner":"circa10a","description":"A project template for my personal projects","archived":false,"fork":false,"pushed_at":"2026-01-26T00:25:15.000Z","size":184,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-26T13:26:19.068Z","etag":null,"topics":["golang","project-template","rest-api","restful-api","template","template-project"],"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/circa10a.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-11T22:29:35.000Z","updated_at":"2026-01-26T00:25:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"bc945514-1daa-4cba-b4ca-923b29612c4f","html_url":"https://github.com/circa10a/go-rest-template","commit_stats":null,"previous_names":["circa10a/go-rest-template"],"tags_count":13,"template":true,"template_full_name":null,"purl":"pkg:github/circa10a/go-rest-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fgo-rest-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fgo-rest-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fgo-rest-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fgo-rest-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circa10a","download_url":"https://codeload.github.com/circa10a/go-rest-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fgo-rest-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29288047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T21:57:15.303Z","status":"ssl_error","status_checked_at":"2026-02-09T21:57:11.537Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["golang","project-template","rest-api","restful-api","template","template-project"],"created_at":"2024-11-24T04:18:14.821Z","updated_at":"2026-02-10T01:15:51.251Z","avatar_url":"https://github.com/circa10a.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💤 go-rest-template\n\nA project template for Go REST API's.\n\n![Build Status](https://github.com/circa10a/go-rest-template/workflows/deploy/badge.svg)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/circa10a/go-rest-template)\n\n\u003cimg width=\"40%\" src=\"https://raw.githubusercontent.com/ashleymcnamara/gophers/refs/heads/master/CouchPotatoGopher.png\" align=\"right\"/\u003e\n\n- [go-rest-template](#go-rest-template)\n  - [Features](#features)\n  - [Usage](#usage)\n    - [Repository setup](#repository-setup)\n    - [Initialize a new project](#initialize-a-new-project)\n    - [Server](#server)\n  - [Development](#development)\n    - [Start the server](#start-the-server)\n    - [Default Routes](#default-routes)\n    - [Adding routes](#adding-routes)\n    - [Generate OpenAPI docs](#generate-openapi-documentation)\n    - [Generate Client SDK](#generate-client-sdk)\n- [Docker compose](#docker-compose)\n- [Kubernetes](#kubernetes)\n\n## Features\n\n- :lock: Secure by default with automatic TLS powered by [CertMagic](https://github.com/caddyserver/certmagic)\n- :chart_with_upwards_trend: Prometheus metrics\n- :scroll: Beautiful logging via [charmbracelet](https://github.com/charmbracelet/log)\n- :book: OpenAPI documentation built in with SDK generation\n- Easy kubernetes development via [Tilt](https://github.com/tilt-dev/tilt)\n- A full local monitoring stack using [Grafana](https://grafana.com/), [Prometheus](https://prometheus.io/), and [Loki](https://grafana.com/oss/loki/) via Docker compose.\n- :construction_worker: CI pipelines via GitHub actions\n  - Tests\n  - Linting via [golangci-lint](https://github.com/golangci/golangci-lint)\n  - Security scanning via [gosec](https://github.com/securego/gosec)\n  - Secret scanning via [gitleaks](https://github.com/gitleaks/gitleaks)\n  - Automatic semantic version tagging\n  - [GoReleaser](https://github.com/goreleaser/goreleaser)\n  - Docker build and pushes for latest and tagged versions\n\n## Usage\n\n### Repository setup\n\nThe default GitHub actions that come with this project has 1 setup requirement.\n\n1. `DOCKERHUB_TOKEN` - Login to [Docker Hub](https://hub.docker.com/) and [create a personal access token](https://docs.docker.com/security/for-developers/access-tokens/) with `Read, Write` scope to push docker images under your account.\n\n\u003e [!WARNING]\n\u003e This assumes your Docker Hub namespace matches your git repository namespace.\n\u003e Example: github.com/mynamespace/myrepo will push to mynamespace/myrepo on Docker Hub\n\n1. Enable dependabot updates - Navigate to repository \u003e Security \u003e Code security \u003e Grouped security updates \u003e Enabled\n\n### Initialize a new project\n\nUse [gonew](https://pkg.go.dev/golang.org/x/tools/cmd/gonew) to initialize a new project from this template:\n\n```console\n# Install gonew (if needed)\n$ go install golang.org/x/tools/cmd/gonew@latest\n\n# Init project\n$ gonew github.com/circa10a/go-rest-template github.com/namespace/project\n```\n\nFinally, replace all of the existing references of the template repository with your newly created one by running:\n\n```console\n$ make template\n```\n\n### Overview\n\n```console\n$ go run .\nA template project for Go REST API's\n\nUsage:\n  go-rest-template [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  server      Start the go-rest-template server\n\nFlags:\n  -h, --help   help for go-rest-template\n\nUse \"go-rest-template [command] --help\" for more information about a command.\n```\n\n## Server\n\n```console\n$ go run . server --help\n\nStart the go-rest-template server\n\nUsage:\n  go-rest-template server [flags]\n\nFlags:\n  -a, --auto-tls                 Enable automatic TLS via Let's Encrypt. Requires port 80/443 open to the internet for domain validation. (env: APP_AUTO_TLS)\n  -d, --domains stringArray      Domains to issue certificate for. Must be used with --auto-tls. (env: APP_DOMAINS)\n  -h, --help                     help for server\n  -f, --log-format string        Server logging format. Supported values are 'text' and 'json'. (env: APP_LOG_FORMAT) (default \"text\")\n  -l, --log-level string         Server logging level. (env: APP_LOG_LEVEL) (default \"info\")\n  -m, --metrics                  Enable Prometheus metrics intrumentation. (env: APP_METRICS)\n  -p, --port int                 Port to listen on. Cannot be used in conjunction with --auto-tls since that will require listening on 80 and 443. (env: APP_PORT) (default 8080)\n      --tls-certificate string   Path to custom TLS certificate. Cannot be used with --auto-tls. (env: APP_TLS_CERTIFICATE)\n      --tls-key string           Path to custom TLS key. Cannot be used with --auto-tls. (env: APP_TLS_KEY)\n```\n\n## Development\n\n\u003e [!IMPORTANT]\n\u003e Most `make` targets expect [Docker](https://docs.docker.com/engine/install/) to be installed.\n\n### Start the server\n\n```console\n$ make run\n2024-10-26T19:09:03-07:00 INFO \u003cserver/server.go:118\u003e Starting server on :8080 component=server\n```\n\n### Default routes\n\n|                            |                                                     |\n|----------------------------|-----------------------------------------------------|\n| Endpoint                   | Descripton                                          |\n| `localhost:8080/v1/docs`   | OpenAPI documentation                               |\n| `localhost:8080/v1/health` | Health status                                       |\n| `localhost:8080/metrics`   | Prometheus metrics (if server is started with `-m`) |\n\n### Adding routes\n\nRoutes are created in `internal/server/server.go` with API handlers in `internal/server/handlers/handlers.go`.\n\n### Generate OpenAPI documentation\n\nSimply add your API spec to `api/openapi.yaml` then run `make docs`. The OpenAPI documentation will then be embed in the application and will be accessible at the `http://localhost:8080/docs` endpoint.\n\n### Generate Client SDK\n\nOnce your API documention is added to `api/openapi.yaml`, just run `make sdk` and a generated client sdk will be output to the `api` package.\n\n## Docker compose\n\nThe local docker compose stack sets up a full observability stack for testing. Run the following the start the stack:\n\n```console\n$ make docker-compose\n```\n\nThe following services will then be accessible with a pre-configured dashboard:\n\n- Go server: http://localhost:8080\n- [Grafana](https://grafana.com/): http://localhost:3000\n- [Prometheus](https://prometheus.io/): http://localhost:9090\n- [Loki](https://grafana.com/oss/loki/)\n- [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/)\n\n## Kubernetes\n\n\u003e [!NOTE]\n\u003e Requires [Tilt](https://tilt.dev/) to be installed and local kubernetes context to be configured.\n\u003e\n\u003e This has only been tested on MacOS using Docker for Mac's Kubernetes integration.\n\n```console\n$ make k8s\n```\n\nThis will deploy the service to kubernetes and make it available at http://localhost:8080\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fgo-rest-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirca10a%2Fgo-rest-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fgo-rest-template/lists"}