# How bootstrap.StartUp() Initializes the Gorig Application: A Complete Code Walkthrough

> Discover how bootstrap StartUp() initializes the Gorig application by registering services, dumping router info, launching the server, and managing shutdown. Get a complete code walkthrough.

- Repository: [Jom/gorig](https://github.com/jom-io/gorig)
- Tags: internals
- Published: 2026-03-05

---

**The `bootstrap.StartUp()` function orchestrates the entire Gorig application initialization by registering the HTTP service, dumping router information, launching the server in a background goroutine, and managing graceful shutdown.**

The `jom-io/gorig` repository provides a modular Go framework for building HTTP services with Gin. At the heart of every Gorig application lies the `bootstrap.StartUp()` function, which serves as the unified entry point that wires together configuration, service lifecycle management, and the web server. Understanding this initialization flow is essential for developers extending or debugging Gorig-based services.

## Entry Point: Calling bootstrap.StartUp()

The simplest Gorig application requires only a single function call. The example binary at [`simple/main.go`](https://github.com/jom-io/gorig/blob/main/simple/main.go) demonstrates the minimal setup:

```go
package main

import "github.com/jom-io/gorig/bootstrap"

func main() {
    // Boots the full application (service registration, HTTP server, graceful shutdown)
    bootstrap.StartUp()
}

```

This entry point delegates all initialization complexity to the bootstrap package, allowing developers to focus on business logic rather than boilerplate server setup.

## Service Registration Flow

Inside [`bootstrap/startup.go`](https://github.com/jom-io/gorig/blob/main/bootstrap/startup.go), the `StartUp()` function begins by invoking `regWebService()` to register the HTTP service with the global service registry. This function constructs a `serv.Service` struct that defines the lifecycle callbacks and configuration for the web server.

The registration process stores the service in a global map `gServices` defined in [`serv/serv.go`](https://github.com/jom-io/gorig/blob/main/serv/serv.go). The registry rejects duplicate service codes, ensuring only a single HTTP instance can exist per application.

## HTTP Service Configuration

The `regWebService()` function configures the HTTP service with specific parameters extracted from the application configuration:

| Field | Implementation Detail |
|-------|----------------------|
| **Code** | `"HTTP"` (unique service identifier) |
| **PORT** | `configure.GetString("api.rest.addr", ":9617")` (configurable, defaults to port 9617) |
| **Startup** | `httpx.Startup` (creates the `http.Server` and Gin engine) |
| **Shutdown** | `httpx.Shutdown` (gracefully stops the server with timeout) |

This configuration separates concerns between the bootstrap orchestrator and the HTTP implementation details.

## Router Inspection and Logging

After service registration, `bootstrap.StartUp()` calls `httpx.DumpRouters()` to enumerate all registered Gin routes. This includes the default `GET /ping` endpoint added during `httpx` package initialization, providing visibility into the available API surface before the server accepts traffic.

## Starting the Server

The final initialization step invokes `serv.Running()`, which iterates over the `gServices` map and executes each service's `Startup` function. For the HTTP service, this triggers `httpx.Startup` in [`httpx/serv.go`](https://github.com/jom-io/gorig/blob/main/httpx/serv.go).

The `httpx.Startup` function performs the following:

1. **Singleton Guard**: Returns early if `gHttpServer` already exists to prevent duplicate server instances.
2. **Server Configuration**: Creates an `http.Server` wrapping the global Gin engine (`gEngine`) with configurable timeouts.
3. **Background Execution**: Launches `ListenAndServe` in a separate goroutine, allowing `serv.Running()` to continue monitoring for shutdown signals.
4. **Error Handling**: Fatal exit if the server fails to start (port conflicts, permission issues).

The Gin engine itself is prepared in `httpx.init()`, which attaches recovery middleware, logging, CORS, gzip compression, and the default health check endpoint.

## Graceful Shutdown Mechanism

`serv.Running()` blocks on an OS interrupt signal (`SIGINT`, `SIGTERM`). Upon receiving the signal, it:

1. Logs a shutdown banner.
2. Creates a 5-second context deadline.
3. Invokes each service's `Shutdown` function sequentially.

For the HTTP service, `httpx.Shutdown` calls `http.Server.Shutdown()` with the timeout context, allowing active connections to complete while rejecting new requests. This prevents abrupt connection drops and ensures data integrity during deployment or scaling events.

## Summary

- **`bootstrap.StartUp()`** serves as the unified entry point that orchestrates the entire Gorig application lifecycle.
- The function registers the HTTP service via `regWebService()`, which configures the server port, startup, and shutdown callbacks in [`serv/serv.go`](https://github.com/jom-io/gorig/blob/main/serv/serv.go).
- Router information is dumped via `httpx.DumpRouters()` to provide visibility into available endpoints.
- `serv.Running()` launches the HTTP server in a background goroutine through `httpx.Startup`, which wraps the Gin engine in a standard `http.Server`.
- The application blocks until an OS signal triggers graceful shutdown via `httpx.Shutdown`, ensuring clean connection termination with a 5-second timeout.

## Frequently Asked Questions

### How do I customize the HTTP port in a Gorig application?

The port is configured via the `api.rest.addr` configuration key, which defaults to `:9617` if not specified. You can set this in your configuration file or environment variables, and `regWebService()` will automatically pick it up when constructing the service struct in [`bootstrap/startup.go`](https://github.com/jom-io/gorig/blob/main/bootstrap/startup.go).

### Can I register additional services alongside the HTTP service?

Yes. While `bootstrap.StartUp()` currently focuses on HTTP, the `serv` package in [`serv/serv.go`](https://github.com/jom-io/gorig/blob/main/serv/serv.go) supports multiple service registrations through `serv.RegisterService()`. You can extend the bootstrap flow to register custom services (databases, message queues, etc.) before calling `serv.Running()`, and the graceful shutdown mechanism will handle each service's `Shutdown` callback sequentially.

### What happens if the HTTP server fails to start?

If `httpx.Startup` encounters an error (such as a port conflict or permission denied), it logs the error and triggers an immediate fatal exit. This prevents the application from running in a partially initialized state. The error originates from the standard library's `http.Server.ListenAndServe()` call within the goroutine spawned by `httpx.Startup` in [`httpx/serv.go`](https://github.com/jom-io/gorig/blob/main/httpx/serv.go).

### How does Gorig handle concurrent requests during shutdown?

When an OS interrupt signal is received, `serv.Running()` creates a 5-second context deadline and passes it to `httpx.Shutdown`. This calls `http.Server.Shutdown(ctx)`, which gracefully closes the listener and waits for existing connections to complete while rejecting new ones. If connections exceed the 5-second timeout, they are forcibly closed to ensure the process exits.