Golang Clean Web API (Dockerized)

A complete sample project demonstrating a clean architecture approach for a car sales web API with Golang, featuring comprehensive logging, monitoring, and containerization.

Table of Contents

• System Architecture
• Technologies Used
• Getting Started
  • Running Locally
  • Running with Docker
• API Examples
• Monitoring and Observability
• Production Deployment
• Project Preview
• Contributing
• Contact Information

System Architecture

Database Design

Technologies Used

This project leverages a modern technology stack to achieve robust functionality:

1. Web Framework: Gin - High-performance HTTP web framework
2. Authentication: JWT - Token-based authentication and authorization
3. Caching: Redis - In-memory data structure store
4. Logging Stack:
   • Elasticsearch - Log storage and indexing
   • Filebeat - Log shipping
   • Kibana - Log visualization
5. Database:
   • PostgreSQL - Main database engine
   • PgAdmin - Database management tool
   • GORM - ORM library
6. Monitoring:
   • Prometheus - Metrics collection
   • Grafana - Metrics visualization
   • Alertmanager - Alert handling
7. Development Tools:
   • Validator - Input validation
   • Viper - Configuration management
   • Zap & Zerolog - Structured logging
   • Swaggo - API documentation
8. Containerization: Docker & Docker Compose - Application packaging and deployment

Getting Started

Running Locally

1. Start Dependencies with Docker

docker compose -f "docker/docker-compose.yml" up -d setup elasticsearch kibana filebeat postgres pgadmin redis prometheus node-exporter alertmanager grafana

2. Install Swagger and Run the Application

cd src
go install github.com/swaggo/swag/cmd/swag@latest
cd cmd
go run main.go

The API will be available at: http://localhost:5005

3. Stop Dependencies

docker compose -f "docker/docker-compose.yml" down

Running with Docker

Deploy the entire application stack with a single command:

docker compose -f "docker/docker-compose.yml" up -d --build

Service Access Information

Service	URL	Credentials
Web API	http://localhost:9001	Username: admin Password: 12345678
Kibana	http://localhost:5601	Username: elastic Password: @aA123456
Prometheus	http://localhost:9090	N/A
Grafana	http://localhost:3000	Username: admin Password: foobar
PgAdmin	http://localhost:8090	Username: [email protected] Password: 123456

Postgres Connection Details:

• Host: postgres_container
• Port: 5432
• Username: postgres
• Password: admin

Stopping Docker Services

docker compose -f 'docker/docker-compose.yml' --project-name 'docker' down

API Examples

Authentication

Login example:

curl -X 'POST' \
  'http://localhost:5005/api/v1/users/login-by-username' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "12345678",
  "username": "admin"
}'

Filtering and Sorting

City Filter with Text Search

{
  "filter": {
    "Name": {
      "filterType": "text",
      "from": "t", 
      "type": "contains"
    } 
  },
  "pageNumber": 1,
  "pageSize": 10,
  "sort": [
    {
      "colId": "name",
      "sort": "desc"
    }
  ]
}

City with Range Filter

{
  "filter": {
    "Id": {
      "filterType": "number",
      "from": "1", 
      "to": "7", 
      "type": "inRange"
    } 
  },
  "pageNumber": 1,
  "pageSize": 10,
  "sort": [
    {
      "colId": "name",
      "sort": "desc"
    }
  ]
}

Production Deployment

Linux Deployment with Systemd

1. Build the Project

cd src
go build -o ../prod/server ./cmd/main.go
mkdir -p ../prod/config/ && cp config/config-production.yml ../prod/config/config-production.yml

2. Create a Systemd Service Unit

sudo vi /lib/systemd/system/go-api.service

3. Configure the Service

[Unit]
Description=go-api

[Service]
Type=simple
Restart=always
RestartSec=20s
ExecStart=/development/Project/go/clean-web-api/prod/server
Environment="APP_ENV=production"
WorkingDirectory=/development/Project/go/clean-web-api/prod

[Install]
WantedBy=multi-user.target

4. Start the Service

sudo systemctl start go-api

5. Stop the Service

sudo systemctl stop go-api

6. View Service Logs

sudo journalctl -u go-api -e

Project Preview

Swagger

Grafana

Kibana

Contributing

Contributions are welcome! Please feel free to submit issues, fork the repository, and create pull requests.

Contact Information

If you have any questions, suggestions, or feedback regarding this project, please feel free to reach out:

• Email: [email protected]
• GitHub Issues: Please use the issue tracker
• LinkedIn: Omid Haqi
• Telegram: Umut