Go Todo

Simple Todo api using Go

View Demo · Documentation · Report Bug · Request Feature

📔 Table of Contents

• About the Project
  • Screenshots
  • Tech Stack
  • Features
  • Environment Variables
• Getting Started
  • Prerequisites
  • Run with Docker Compose
  • Run Locally
  • Running Tests
• Usage
  • Access Swagger UI
  • Build Docker Image
  • Makefile
• Roadmap
• Contributing
  • Code of Conduct
• FAQ
• License
• Contact
• Acknowledgements

🌟 About the Project

📷 Screenshots

Swagger UI

👾 Tech Stack

Server

• Golang

Database

• PostgreSQL

DevOps

• Docker

🎯 Features

• Basic CRUD operations.
• Swagger UI for API documentation.
• Simple CLI for running the server.
• gRPC Gateway server.

🔑 Environment Variables

Note

All the environment variables file are required to run this project.

To run this project, you will need to add the following environment variables file:

• internal/gateway/configs/.env: Gateway service environment variables.

  • HOST: The host of the server. Default is 0.0.0.0.

  • PORT: The port of the server. Default is 8081.

  • APP_ENV: The environment of the application. Default is development. It can be production or development.

  • LOG_LEVEL: The log level of the application. Default is 0. See available level in zerolog.

  • LOG_SAMPLE_RATE: The sample rate of the log. Default is 5.

  • TASK_SERVER_ADDRESS: The address of the task service. Example: localhost:8080.

  E.g:

  # internal/gateway/configs/.env
  HOST="0.0.0.0"
  PORT=8081
  APP_ENV="development"
  LOG_LEVEL=0
  LOG_SAMPLE_RATE=5
  
  TASK_SERVER_ADDRESS="localhost:9000"
  

  You can also check out the file internal/gateway/configs/.env.example to see all required environment variables.

• internal/task/configs/.env: Task service environment variables.

  • PORT: The port of the server. Default is 8080.

  • APP_ENV: The environment of the application. Default is development. It can be production or development.

  • LOG_LEVEL: The log level of the application. Default is 0. See available level in zerolog.

  • LOG_SAMPLE_RATE: The sample rate of the log. Default is 5.

  • DB_URL: The URL of the database. Example: postgres://postgres:postgres@localhost:5432/task?sslmode=disable.

  E.g:

  # internal/task/configs/.env
  PORT=9000
  APP_ENV="development"
  LOG_LEVEL=0
  LOG_SAMPLE_RATE=5
  
  DB_URL="postgresql://postgres:postgres@localhost:5432/task?sslmode=disable"
  
  

  You can also check out the file internal/task/configs/.env.example to see all required environment variables.

🧰 Getting Started

‼️ Prerequisites

• Go: 1.22.1.

• Docker: 26.1.2.

• Brew tools:

  All required brew tools is placed in internal/tools/Brewfile:

  make download-deps

• Go tools:

  All required Go tools is placed in internal/tools/tools.go:

  make download-deps

Note

These dependencies are not included during build.

🐳 Run with Docker Compose

Update the environment variables files:

Please check the Environment Variables section to see all required environment variables.

Run the server:

docker-compose up -d

Access the Swagger UI at http://localhost/docs.

Access the API at http://localhost/api.

🏃 Run Locally

Clone the project:

git clone https://github.com/DuckyMomo20012/go-todo.git

Go to the project directory:

cd go-todo

Install dependencies:

go mod download

Update the environment variables files:

Please check the Environment Variables section to see all required environment variables.

Start the Postgres database:

docker-compose up -d

Start the server:

go run ./main.go gateway start

go run ./main.go task start

Or with wgo for live reload:

wgo run ./main.go gateway start

wgo run ./main.go task start

Note

The gateway API is mount to localhost:<PORT>/api not localhost:<PORT>.

🧪 Running Tests

Test API with Postman

• REST API:

  You can test the REST API with Postman by importing files from /api/openapi/ to your Postman.

Note

You may have to add the Authorization header to your requests. You can get a token by logging in with the login API.

• gRPC API:

  You can test the gRPC API with Postman by using Postman reflection feature.

👀 Usage

Access Swagger UI

Open your browser and go to http://localhost/docs.

Build Docker Image

Note

Environment variables files are required to build the Docker image. Check the Environment Variables section for more information.

docker build -t go-todo -f ./docker/tasks/Dockerfile .

Or build ghcr image:

make docker-build

Makefile

Makefile provides some useful targets to help you work with this project:

• init: Download tool dependencies and setup GOPRIVATE environment variable.

  make init

Note

Setup GOPRIVATE env for vscode not automatically going to pkg.go.dev for private modules.

• download-deps: Download all tool dependencies.

  make download-deps

• gen-proto: Generate gRPC and gRPC gateway from proto files.

  make gen-proto

• lint: Run lint with golangci-lint.

  make lint

• docker-build: Build Docker image for ghcr.io registry.

  make docker-build

• docker-push: Push Docker image to ghcr.io registry.

  make docker-push

🧭 Roadmap

• gRPC support.
• gRPC Gateway support.
• CLI support.

👋 Contributing

Contributions are always welcome!

📜 Code of Conduct

Please read the Code of Conduct.

❔ FAQ

• I can't query requests using the Swagger UI.

  • Currently with the Buf plugin openapiv2 can only generate the OpenAPI v2 spec. Therefore, I can't set hostname using variable which only available in OpenAPI v3.

  • The swagger service defined in file docker-compose.yaml is running with port 8082 and sending requests using localhost:8082. However, the gRPC gateway service is running with port 8081.

• Why do you migrate to protoc-gen-openapiv2?

  • The original port for REST API is removed in PR#8.

  • Because I decided to switch to grpc-gateway so I can automatically generate REST API from proto files.

  • For the OpenAPI spec, I used to use protoc-gen-openapiv2 (Using buf plugin: openapiv2) to generate the OpenAPI v2 spec. However, it can only generate the OpenAPI v2 so I may have to switch to another plugin that can generate OpenAPI v3 spec later.

• Why do you rename all vars and files from tasks to task?

  • Bad naming convention.

• How can test the gRPC server with Postman?

  • Since the gRPC server enabled reflection service in PR#9, you can use option Using server reflection from tab Service definition in your gRPC requests in Postman.

⚠️ License

Distributed under MIT license. See LICENSE for more information.

🤝 Contact

Duong Vinh - @duckymomo20012 - [email protected]

Project Link: https://github.com/DuckyMomo20012/go-todo.

💎 Acknowledgements

Here are useful resources and libraries that we have used in our projects:

• Clean Architecture: A detailed explanation of Clean Architecture by Three Dots Labs.
• grpc-gateway: gRPC to JSON proxy generator following the gRPC HTTP spec.
• Buf CLI: A new way to work with Protocol Buffers.