Your First Service (Go Microservice)

Overview

This tutorial walks you through adding a new Go microservice to the GitiNext stack: from scaffold to registration in the Gateway and deployment.

Prerequisites

Go 1.22+
Access to the monorepo (gitinext-golang)
Docker (for local run)
Understanding of Microservices Architecture

Steps

1. Create the service directory

Under services/, create a new service (e.g. myservice):

services/myservice/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   └── myservice/
│       └── handler.go
├── go.mod
└── Dockerfile

2. Implement the server

cmd/server/main.go — minimal HTTP server with health and graceful shutdown:

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
    mux.HandleFunc("/api/v1/hello", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte(`{"message":"hello"}`))
    })

    srv := &http.Server{Addr: ":7080", Handler: mux}
    go func() { _ = srv.ListenAndServe() }()

    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGTERM, syscall.SIGINT)
    <-quit
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    _ = srv.Shutdown(ctx)
    log.Println("shutdown complete")
}

3. Add to workspace and build

Add services/myservice to the root go.work (if using workspaces).
From repo root: go build ./services/myservice/cmd/server

4. Gateway integration

In the Gateway, add an HTTP client or gRPC client pointing to myservice:7080.
Expose one or more routes (e.g. /api/v1/myservice/hello) that proxy to this service.
Document the new endpoint in Gateway REST and Swagger.

5. Docker and deploy

Dockerfile: Multi-stage build; copy binary; run as non-root; expose 7080.
Docker Compose / Swarm: Add myservice service and wire network so Gateway can reach it.
Use same patterns as existing services (config via env, health checks).

Flow

flowchart LR
  A[Gateway] -->|HTTP/gRPC| B[MyService]
  B --> C[/healthz]
  B --> D[/api/v1/hello]