Docs Minimal Server

Minimal Server

This guide walks through the smallest possible Plumego server.

The goal is not to build a production-ready service,
but to establish a clear mental model of how Plumego fits around Go’s standard library.

If you can understand this example, everything else in Plumego builds naturally on top of it.

Prerequisites

Before continuing, you should be comfortable with:

  • Basic Go syntax
  • go mod and module-based projects
  • Running a Go program

No prior knowledge of Plumego is required.

Step 1: Create a New Go Module

Create an empty directory and initialize a module:

mkdir plumego-demo
cd plumego-demo
go mod init example.com/plumego-demo

Step 2: Install Plumego

Add Plumego as a dependency:

go get github.com/spcent/plumego

This will pull in Plumego and its minimal dependency set
(which is intentionally small and standard-library-focused).

Step 3: Write the Minimal Server

Create a file named main.go:

package main

import (
	"net/http"

	"github.com/spcent/plumego"
)

func main() {
	// Create a new Plumego application
	app := plumego.New()

	// Register a minimal route
	app.GET("/", func(ctx *plumego.Context) {
		ctx.String(http.StatusOK, "Hello, Plumego")
	})

	// Start the HTTP server
	if err := app.Run(":8080"); err != nil {
		panic(err)
	}
}

This is a complete Plumego application.

There are no hidden files, generators, or configuration layers.

Step 4: Run the Server

Start the server:

go run main.go

You should see no output by default.

Plumego does not log startup messages unless explicitly configured.

Step 5: Send a Request

In another terminal:

curl http://localhost:8080/

Expected response:

Hello, Plumego

At this point, you have a working Plumego server.

What Just Happened

Although the example is small, several important things occurred.

1. You Created an Explicit Application

app := plumego.New()

Plumego does not rely on global state.

The application instance owns:

  • Routing
  • Middleware
  • Lifecycle management

This makes behavior explicit and testable.

2. You Registered a Route Explicitly

app.GET("/", handler)

Routes are registered directly on the application.

There is no implicit scanning, reflection, or annotation-based routing.

What you register is exactly what the server exposes.

3. You Handled a Request via Context

func(ctx *plumego.Context) { ... }

Plumego provides a thin Context wrapper around the standard library.

It exists to:

  • Encapsulate request and response handling
  • Provide common helpers
  • Avoid leaking framework logic into business code

The context is request-scoped and explicit.

4. You Started a Standard HTTP Server

app.Run(":8080")

Internally, Plumego starts a standard http.Server.

There is no custom runtime, no event loop, and no proprietary transport.

If you understand net/http, you already understand Plumego’s execution model.

What This Example Does Not Include

This minimal server intentionally avoids:

  • Middleware
  • Logging
  • Configuration
  • Graceful shutdown
  • Error handling strategy
  • Project structure

All of those topics are covered later.

Adding them now would obscure the core idea.

Common Questions at This Stage

Why is there no automatic JSON response?

Because Plumego does not assume response formats.

You decide:

  • When to return JSON
  • How to structure responses
  • How errors are represented

Plumego avoids default conventions that are difficult to change later.

Why is there no startup log?

Because Plumego does not log by default.

Logging is considered a cross-cutting concern
and must be explicitly configured.

This avoids accidental logging behavior in production systems.

Why does the handler look “manual”?

Because it is.

Plumego favors explicit request handling over automated binding.

This improves debuggability and long-term clarity.

Minimal Does Not Mean Primitive

Although this example is small, it already establishes:

  • A clear request entry point
  • An explicit lifecycle
  • A predictable execution model

Everything else in Plumego builds on this foundation.

Next

Now that you have a running server, the next step is to understand how Plumego thinks.

Continue with:

→ Concepts / Request Lifecycle

Or, if you prefer to expand gradually:

→ Getting Started / Project Layout