Skip to main content

​
Quick Start

This guide will help you create and run your first Kratos service in just a few minutes.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Go 1.22 or higher - Download Go
  • Protocol Buffers compiler - Required for code generation
  • Git - For cloning templates
If you haven’t installed the Kratos CLI yet, see the Installation Guide.

​
Create Your First Service

1

Create a new project

Use the kratos new command to create a new service from the official template:
kratos new helloworld
This command clones the kratos-layout template and sets up a complete project structure.
The CLI will prompt you to select a template. Choose “Service” for a standard microservice template, or “Admin” for an admin backend template.
2

Navigate to your project

cd helloworld
Your project structure will look like this:
helloworld/
├── api/                 # Protobuf definitions
│   └── helloworld/
│       └── v1/
│           ├── greeter.proto
│           └── error_reason.proto
├── cmd/                 # Application entrypoint
│   └── helloworld/
│       ├── main.go
│       └── wire.go      # Dependency injection
├── internal/            # Private application code
│   ├── biz/            # Business logic
│   ├── conf/           # Configuration structs
│   ├── data/           # Data access layer
│   ├── server/         # HTTP/gRPC server setup
│   └── service/        # Service implementations
└── configs/            # Configuration files
    └── config.yaml
3

Install dependencies

go mod tidy
This downloads all required dependencies including the Kratos framework:
  • github.com/go-kratos/kratos/v2 - Core framework
  • google.golang.org/grpc - gRPC support
  • google.golang.org/protobuf - Protobuf runtime
4

Run your service

Start the service using the Kratos CLI:
kratos run
Or use the standard Go command:
go run ./cmd/helloworld
You should see output similar to:
INFO msg=config loaded: config.yaml
INFO msg=server listening on: [::]:8000
INFO msg=server listening on: [::]:9000
The service now exposes:
  • HTTP server on port 8000
  • gRPC server on port 9000
5

Test your service

Open a new terminal and test the HTTP endpoint:
curl http://localhost:8000/helloworld/kratos
Expected response:
{
  "message": "Hello kratos"
}
The same endpoint is available via gRPC on port 9000. You can use tools like grpcurl to test gRPC endpoints.

​
Understanding the Application Structure

​
Application Bootstrap

The main application is bootstrapped in cmd/helloworld/main.go. Here’s the key initialization code: 
package main

import (
    "github.com/go-kratos/kratos/v2"
    "github.com/go-kratos/kratos/v2/transport/http"
    "github.com/go-kratos/kratos/v2/transport/grpc"
)

func main() {
    // Create HTTP server
    httpSrv := http.NewServer(
        http.Address(":8000"),
    )
    
    // Create gRPC server
    grpcSrv := grpc.NewServer(
        grpc.Address(":9000"),
    )
    
    // Create application
    app := kratos.New(
        kratos.Name("helloworld"),
        kratos.Version("v1.0.0"),
        kratos.Server(httpSrv, grpcSrv),
    )
    
    // Run application
    if err := app.Run(); err != nil {
        panic(err)
    }
}
The kratos.New() function creates an application lifecycle manager that:
  • Manages server startup and graceful shutdown
  • Handles OS signals (SIGTERM, SIGINT, SIGQUIT)
  • Registers services with service registry
  • Coordinates all application components

​
Service Implementation

Services are implemented in internal/service/. The greeter service looks like: 
package service

import (
    "context"
    
    pb "helloworld/api/helloworld/v1"
)

type GreeterService struct {
    pb.UnimplementedGreeterServer
}

func NewGreeterService() *GreeterService {
    return &GreeterService{}
}

func (s *GreeterService) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) {
    return &pb.HelloReply{
        Message: "Hello " + req.Name,
    }, nil
}

​
API Definition

APIs are defined using Protocol Buffers in api/helloworld/v1/greeter.proto: 
syntax = "proto3";

package helloworld.v1;

import "google/api/annotations.proto";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/helloworld/{name}"
    };
  }
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}
The google.api.http annotation maps gRPC methods to HTTP endpoints, enabling dual-protocol support.

​
Next Steps

Add New Endpoints

Learn how to add new API endpoints to your service

Configure Middleware

Add logging, tracing, and metrics to your service

Database Integration

Connect to databases and implement data persistence

Service Discovery

Set up service registration and discovery

​
Common Commands

Here are some useful commands for Kratos development: 
# Generate code from proto files
kratos proto client api/helloworld/v1/greeter.proto

# Generate server implementation stubs
kratos proto server api/helloworld/v1/greeter.proto

# Add a new proto file
kratos proto add api/user/v1/user.proto

# Run the service with auto-reload (requires air)
air

# Build the binary
go build -o bin/helloworld ./cmd/helloworld

​
Troubleshooting

Port already in use: If you see “bind: address already in use”, another process is using ports 8000 or 9000. Either stop that process or change the ports in your configs/config.yaml.
protoc-gen-go not found: If code generation fails, ensure you have installed the protobuf plugins:
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest

​
What You’ve Learned

In this quick start, you:
  • Created a new Kratos service using the CLI
  • Ran HTTP and gRPC servers simultaneously
  • Made HTTP requests to your service
  • Understood the basic project structure
  • Learned about application lifecycle management
Continue to the Core Concepts section to learn more about Kratos architecture and patterns.

Build docs developers (and LLMs) love

Get started for freeTalk to us