Opinionated Go service template with Fiber API, OpenAPI docs, Telegram bot wiring, health endpoints, and Fx-based modular DI.
Explore the docs »
Report Bug
·
Request Feature
This repository is a production-oriented starter for backend services in Go. It ships with:
- HTTP server bootstrapped with Fiber and dependency injection via Uber Fx.
- Version + health endpoints using
healthfx. - Swagger/OpenAPI docs endpoint under
/api/v1/docs. - Telegram bot integration (
/startcommand handler included). - Modular business domain example with CLI commands (serve, one-shot tasks).
Use this template when you want a fast path to shipping APIs and bot workflows with a clean module layout.
Follow these steps to run the service locally.
- Go 1.26.7+
go version
golangci-lintv2.14.0 or later (optional but recommended)golangci-lint version
swagCLI for docs generationgo install github.com/swaggo/swag/cmd/swag@latest
- Clone the repo.
git clone https://github.com/capcom6/go-project-template.git cd go-project-template - Download dependencies.
make deps
- (Optional) Generate OpenAPI docs.
make gen
- Build the binary.
make build
Run the server (default command):
go run .Or with live reload:
make airCLI commands:
go run . --help # list commands
go run . serve # explicit serve
go run . example # one-shot demo
go run . --version # print versionDefault server address is 127.0.0.1:3000.
Helpful endpoints:
- Health endpoints (via
healthfx), typically under/health. - OpenAPI docs:
http://127.0.0.1:3000/api/v1/docs.
Configuration:
- Environment variables are loaded via
go-core-fx/config. - You can point to a YAML file using:
export CONFIG_PATH=./config.local.yaml - Telegram is configured via the app config:
telegram.tokenis required to use bot handlers,telegram.proxy_url(SOCKS5) routes API traffic,telegram.timeoutbounds each request, andtelegram.modeselects polling (default) or webhook. - The app-wide default HTTP client is configured via
http_client(proxy_url,bypass,timeout,max_idle_conns,max_idle_conns_per_host,idle_conn_timeout,tls.*); unset/zero values inherit the standard library defaults. The bot's owntelegram.proxy_url/telegram.timeoutalways override it for bot API traffic, so only the idle-pool and TLS settings are shared with the bot client. - Webhook mode:
POST /api/v1/webhookis mounted in every mode and answers 500 while no webhook handler is ready (polling). Register the endpoint with the Bot API once — this template ships no CLI helper for it:Call the Bot APIcurl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" -H 'Content-Type: application/json' -d '{"url":"https://<public-host>/api/v1/webhook","allowed_updates":["message"]}'
deleteWebhookbefore switching back to polling.
Webhook security. The webhook route performs no request authentication: the
X-Telegram-Bot-Api-Secret-Tokencheck is not implemented. A caller that reaches the route can submit forged updates. Keep the HTTP server behind a reverse proxy that only forwards Telegram traffic, and prefer the default polling mode.
Quality checks:
make fmt
make lint
make test
make coverage- Fiber API scaffold
- OpenAPI + Swagger integration
- Telegram bot wiring
- Telegram webhook secret token validation
- Database module integration
- Auth middleware and RBAC
- CI release pipeline hardening
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the Apache 2.0 License. See LICENSE for more information.
Maintainer: @capcom6
Project Link: https://github.com/capcom6/go-project-template