Skip to content

DuckyMomo20012/go-todo

Repository files navigation

Go Todo

Simple Todo api using Go

contributors last update forks stars open issues license


πŸ“” Table of Contents

🌟 About the Project

πŸ“· Screenshots

swagger_ui Swagger UI

πŸ‘Ύ Tech Stack

Server
Database
DevOps

🎯 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 - tienvinh.duong4@gmail.com

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.