The Iris book, fifth edition
Documentation
The documentation for Iris is a book. 24 chapters and 437 pages covering version 14.0.0on Go 1.27, from a first route to a tested application in production. Free to read here, free to download, and every example verified against the framework source.
How the book is organised
The chapters build on one another and are best read in order the first time. Afterwards each one stands alone.
- 01
Foundation
Installation, the framework’s core concepts, and the builder that assembles a production application.
Chapters 1 to 3
- 02
The Request Path
Routing and controllers, reading requests, writing responses, and the middleware pipeline.
Chapters 4 to 7
- 03
Application Structure
Dependency injection, error handling, authentication and authorization, and configuration.
Chapters 8 to 11
- 04
Middleware and Data
The built-in middleware, database integration, caching and internationalization.
Chapters 12 to 15
- 05
Running in Production
Testing, observability, security, deployment and performance.
Chapters 16 to 20
- 06
Going Further
AI backends, complete applications, the upgrade path to v14, and the framework’s extension points.
Chapters 21 to 24
Every chapter
Foundation
- 01Getting StartedInstall Iris v14, write a first route, read a typed path parameter and run the server. Ends with a first taste of the production stack and a project layout.
- 02Core ConceptsThe Application, the Router, the pooled Context and handlers chained into a middleware pipeline. How a single request travels through all four and back.
- 03Building Applications with iris.NewBuilderThe compile-enforced builder chain. Each step returns an interface exposing only the moves still legal, so a step called out of turn will not compile.
The Request Path
- 04Routing & ControllersRoute registration, typed path parameters such as {id:uuid}, custom macros, route groups, subdomains, and controllers resolved by the container.
- 05Reading Requestsctx.BindJSON with automatic Validate, the ctx.Read family, query and path accessors, forms, file uploads, cookies, body limits and the validator hook.
- 06Response HandlingThe rest helpers that take a value and an error, the Context writers underneath them, status codes, redirects, streaming and content negotiation.
- 07MiddlewareOne handler type. Middleware is a handler that decides whether the rest of the chain runs. Registration order, guards, and what the builder installs.
Application Structure
- 08Dependency InjectionRegister constructors at startup and the container resolves them into handlers and controllers. Interface binding, request scope and shutdown closers.
- 09Error HandlingThe rest/errors package: canonical codes, one wire format, and a single central map from Go error to HTTP response. Internals never leak to clients.
- 10Authentication & AuthorizationBasic Auth in one line, the generic JWT SDK, role and permission guards, session-based login, and the built-in identity server and OAuth2 provider.
- 11Configuration Managementiris.Options as one struct, built in code, loaded from YAML or read from SERVER_CONFIG. Merge semantics, defaults and multi-environment setups.
Middleware and Data
- 12Built-in MiddlewareThe 31 middleware packages that ship in-tree: CORS, rate limiting, recovery, compression, access logging, sessions, API keys, JWT, request IDs and more.
- 13Database IntegrationIris ships no ORM and no drivers. The repository seam, injected connections, kataras/pg, transactions, and mapping driver errors to status codes.
- 14Caching StrategiesThree layers: client caching with headers and 304s, server-side response caching, and in-application caching. Where each one stops a request.
- 15Internationalization (i18n)The i18n middleware. INI, JSON, TOML and YAML catalogs matched with BCP 47 tags, pluralization, template integration, and path or subdomain rewriting.
Running in Production
- 16TestingIn-process HTTP tests against the real router, the real middleware chain and the real error map. No ports, no network and no sleeps, from unit to suite.
- 17Monitoring & ObservabilityStructured access logs, request ID correlation, the process dashboard, pprof, per-request cost measurement, Server-Timing and health checks.
- 18Security Best PracticesWhat v14 secures by default, then transport security, request bounds, input validation, CORS, CSRF, security headers, secrets and a production checklist.
- 19Deployment & DevOpsOne static binary. Graceful shutdown, Docker, running behind a reverse proxy, Kubernetes health checks, systemd units and continuous integration.
- 20Performance OptimizationMeasure before changing anything. Response size, request bounds, caching, database access patterns, concurrency in handlers and runtime tuning.
Going Further
- 21AI BackendsStream a model over Server-Sent Events, serve the streaming and non-streaming shape from one handler, relay an upstream provider and classify what it returns.
- 22Real-World ExamplesTwo complete applications, file by file: Shortl built on iris.New and Stockroom built on iris.NewBuilder, and when to reach for each of the two shapes.
- 23Upgrading to v14The import path change, renamed Context methods, moved packages, and everything the Go compiler catches for you on the way from v12 up to version 14.
- 24Advanced TopicsGeneric MVC controllers, custom typed contexts, global patches, custom path macros, wrapping the router, multi-app composition and net/http interop.
Alongside the book
The tutorial
One complete, tested service built end to end in a single document. Shorter than chapter 22 and just as finished.
The migration guide
The canonical reference for moving a v12 application to v14. Chapter 23 is the tour; this is the substitution list.
Machine-readable
Every chapter is also served as plain markdown at its own path plus
.md. There is an llms.txt too.