Skip to main content
This guide walks you through creating a new microservice using the Kratos framework.

​
Prerequisites

Before you begin, ensure you have:
  • Go 1.19 or later installed
  • Protocol Buffers compiler (protoc) installed
  • Kratos CLI tool installed

​
Installation

1
Install Kratos CLI
2
First, install the Kratos command-line tool:
3
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest
4
Verify the installation:
5
kratos -v
6
Create a New Service
7
Use the kratos new command to create your service:
8
kratos new helloworld
9
This creates a new project with the following structure:
10
helloworld/
├── api/                  # API definitions (protobuf)
│   └── helloworld/
│       └── v1/
├── cmd/                  # Application entrypoint
│   └── helloworld/
│       ├── main.go
│       └── wire.go
├── configs/              # Configuration files
│   └── config.yaml
├── internal/             # Private application code
│   ├── biz/             # Business logic
│   ├── conf/            # Configuration structures
│   ├── data/            # Data access layer
│   ├── server/          # Server initialization
│   └── service/         # Service implementation
└── go.mod
11
Choose a Template
12
When you run kratos new, you can select from different templates:
13
  • Service: Standard microservice template with gRPC and HTTP support
  • Admin: Admin backend service template
  • Custom: Use a custom repository URL
    • 14
    # Use a specific template
kratos new myservice --repo https://github.com/go-kratos/kratos-layout.git

# Specify a branch
kratos new myservice --branch main
    16
    Change into your new project directory:
    17
    cd helloworld
    18
    Generate Code
    19
    Generate the wire dependency injection code and protobuf files:
    20
    go generate ./...
    21
    This command:
    22
  • Generates Go code from protobuf definitions
  • Creates HTTP and gRPC bindings
  • Generates wire dependency injection code
    • 23
    Install Dependencies
    24
    Download and install project dependencies:
    25
    go mod download
    26
    Build the Service
    27
    Build your service binary:
    28
    go build -o ./bin/ ./...
    29
    The compiled binary will be placed in the ./bin/ directory.
    30
    Run the Service
    31
    Start your service with the configuration file:
    32
    ./bin/helloworld -conf ./configs
    33
    Your service is now running! By default:
    34
  • HTTP server runs on port 8000
  • gRPC server runs on port 9000
    • 35
    Test the Service
    36
    Test your service endpoints:
    37
    # Test HTTP endpoint
curl http://localhost:8000/helloworld/world

# Test with grpcurl
grpcurl -plaintext -d '{"name":"world"}' localhost:9000 helloworld.v1.Greeter/SayHello

    ​
    Project Structure Explained

    ​
    API Layer (api/)

    Contains protobuf definitions for your services: 
    syntax = "proto3";

package helloworld.v1;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

    ​
    Business Logic Layer (internal/biz/)

    Contains business logic and use cases, independent of data sources.

    ​
    Data Layer (internal/data/)

    Handles data access, database connections, and external service integrations.

    ​
    Service Layer (internal/service/)

    Implements the API contract defined in protobuf files.

    ​
    Server Layer (internal/server/)

    Configures and initializes HTTP and gRPC servers.

    ​
    Next Steps

    Define APIs

    Learn how to define APIs using Protocol Buffers

    Code Generation

    Generate HTTP and gRPC bindings from protobuf

    Configuration

    Configure your service with multiple sources

    Testing

    Learn testing strategies for Kratos services

    ​
    Common Issues

    Ensure $GOPATH/bin is in your PATH:
    export PATH=$PATH:$(go env GOPATH)/bin
    Make sure wire is installed:
    go install github.com/google/wire/cmd/wire@latest
    Change the port in configs/config.yaml or stop the process using the port.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us