Skip to content
Public template

About

Opinionated Go service template with Fiber API, OpenAPI docs, Telegram bot wiring, health endpoints, and Fx-based modular DI.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Contributors Forks Stargazers Issues Apache License Go


Logo

go-project-template

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

About The Project

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 (/start command 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.

(back to top)

Built With

  • Go
  • Fiber
  • Fx
  • CLI
  • Swagger
  • Telegram

(back to top)

Getting Started

Follow these steps to run the service locally.

Prerequisites

  • Go 1.26.7+
    go version
  • golangci-lint v2.14.0 or later (optional but recommended)
    golangci-lint version
  • swag CLI for docs generation
    go install github.com/swaggo/swag/cmd/swag@latest

Installation

  1. Clone the repo.
    git clone https://github.com/capcom6/go-project-template.git
    cd go-project-template
  2. Download dependencies.
    make deps
  3. (Optional) Generate OpenAPI docs.
    make gen
  4. Build the binary.
    make build

(back to top)

Usage

Run the server (default command):

go run .

Or with live reload:

make air

CLI commands:

go run . --help                     # list commands
go run . serve                      # explicit serve
go run . example                    # one-shot demo
go run . --version                  # print version

Default 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.token is required to use bot handlers, telegram.proxy_url (SOCKS5) routes API traffic, telegram.timeout bounds each request, and telegram.mode selects 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 own telegram.proxy_url/telegram.timeout always 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/webhook is 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:
    curl -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"]}'
    Call the Bot API deleteWebhook before switching back to polling.

Webhook security. The webhook route performs no request authentication: the X-Telegram-Bot-Api-Secret-Token check 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

(back to top)

Roadmap

  • 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).

(back to top)

Contributing

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!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

Contact

Maintainer: @capcom6

Project Link: https://github.com/capcom6/go-project-template

(back to top)

Acknowledgments

(back to top)

About

Opinionated Go service template with Fiber API, OpenAPI docs, Telegram bot wiring, health endpoints, and Fx-based modular DI.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages