Skip to main content

Quick Start

This guide will help you create a Gonyx project from scratch and run it successfully.

Prerequisites​

Before you begin, make sure you have the following installed:

  • Go version 1.23 or higher
  • Git for version control

Creating a New Gonyx Project​

Creating a new Gonyx project is simple with the gonix command-line tool. The basic syntax is:

gonix init [application-name]

This will create a new application folder in your current directory. The application folder will be named according to what you specify as [application-name].

If you want to create the application in a specific parent directory, you can use the --path flag (or -p for short):

gonix init my-gonyx-app --path /path/to/parent/folder

Project Structure​

After running the gonix init command, your project structure will look like this:

my-gonyx-app/               # Root of your project
├── .git/                   # Git repository
├── .gitignore              # Git ignore file
├── app/                    # Application core
│   ├── app.go              # Main application logic
│   ├── controller.go       # Controller definitions
│   ├── model.go            # Data models
│   └── proto/              # Protobuf definitions (if applicable)
├── commands/               # CLI commands
│   └── root.go             # Root command definition
├── configs/                # Configuration files
│   ├── base_sample.json    # Base configuration template
│   ├── http_sample.json    # HTTP server configuration template
│   ├── logger_sample.json  # Logger configuration template
│   ├── protobuf_sample.json # Protobuf configuration template
│   └── dev/                # Development environment configs
├── go.mod                  # Go module definition
├── go.sum                  # Go module checksums
└── main.go                 # Application entry point

The gonix init command automatically sets up this structure for you, saving you the effort of creating these directories and files manually.

Understanding Your New Project​

After creating your project with gonix init, you'll have a complete, ready-to-use application structure. Here's what you need to know to get started:

Controllers​

The app/controller.go file contains the definitions for your API endpoints. Controllers in Gonyx handle HTTP requests and produce responses. Here's an example of a controller from the generated code:

// SampleController - a sample controller to show the functionality
type SampleController struct{}

// GetName - return the name of the controller to be used as part of the route
func (ctrl *SampleController) GetName() string { return "Sample" }

// Routes - returning controller specific routes to be registered
func (ctrl *SampleController) Routes() []http.HttpRoute {
	return []http.HttpRoute{
		http.HttpRoute{
			Method:    http.MethodGet,
			Path:      "/hello",
			RouteName: "hello",
			F:         ctrl.GetHello,
		},
	}
}

// GetHello - just return the 'Hello World' string to user
func (ctrl *SampleController) GetHello(c *gin.Context) {
	c.String(200, "Hello World")
}

Controllers typically:

  • Define route handlers for different HTTP methods (GET, POST, PUT, DELETE)
  • Process incoming requests and validate data
  • Interact with models or services for business logic
  • Return appropriate responses to clients

In this example, the controller:

  1. Defines a structure called SampleController
  2. Implements the GetName() method to define the controller's name
  3. Implements the Routes() method to register a GET route at "/hello"
  4. Implements the handler function GetHello() that returns a simple "Hello World" response

Running Your Application​

To run your application, use the gonix runserver command:

cd my-gonyx-app      # Navigate to your project directory
go run ./main.go runserver      # Run both HTTP and gRPC servers

This command starts two servers:

  1. An HTTP RESTful API server (default port: 3000)
  2. A gRPC server (default port: 7777)

The servers use the configuration files in the configs/dev directory by default. You can create different configuration environments by adding new folders (e.g., configs/prod for production) and specifying the environment when running the server.

To access your API:

Configuration Modes​

Gonyx supports different configuration modes for various environments:

  • dev: Development mode (default)
  • prod: Production mode (create this folder and configuration files as needed)
  • Custom modes: You can create any named folder under configs/ for custom environments

The configuration files define settings like port numbers, database connections, logging options, and more.

Next Steps​

Congratulations! You've created your first Gonyx application. Here are some suggestions for next steps:

  • Explore more advanced Gonyx features like middleware, validation, and database integration
  • Implement structured routing with controllers
  • Add authentication to your API
  • Create a more complex data model
  • Connect to a database

For more detailed tutorials and examples, check out the other sections of this documentation.