CoreGo Documentation
CoreGo is a backend SDK for Go: authentication with server-side sessions,
a web framework, MongoDB and PostgreSQL access, email and environment
configuration behind one facade, corego.New. New here? Start with
Getting started: a working API in one file, then
short recipes for everything else.
I want to...
| Task | Where |
|---|---|
| Build my first CoreGo app | Getting started: hello world |
| Add an endpoint | Getting started: recipe 1, Web framework: adding an endpoint |
| Protect routes and read the signed-in user | Getting started: recipe 2, HTTP API: protecting your own routes |
| Serve guests and signed-in users on one route | HTTP API: optional sign-in |
| Return a 404 or 400 from a handler | Web framework: errors |
| Write middleware | Web framework: writing your own |
| Store my data in PostgreSQL or MongoDB | Getting started: recipe 3, Database |
| Choose where users and sessions are stored | Auth storage |
| Send verification and password reset emails | Getting started: recipe 4, Mail |
| Send my own emails | |
| Connect a browser frontend (CORS, cookies) | Getting started: recipe 5, HTTP API: bearer tokens or cookies, CSRF protection |
| Know every auth route, body and status code | HTTP API |
| Call the auth service from my own code | Authentication |
| Configure through environment variables | Environment |
| Deploy to production | Getting started: deploy checklist |
| Test my application | Testing |
| Upgrade from 0.1 | Migrating from 0.1 |
| Look up an exact signature | API reference |
Pages
| Page | What it covers |
|---|---|
| Getting started | Install, hello world, how the pieces fit, a project layout, and six recipes: endpoints, protected routes, databases, email, browser frontends, deployment. |
| Web framework | The web package: routing, groups, middleware (CORS, rate limiting, logging, recovery), the Context, errors, net/http interop, running and configuring the server. |
| Authentication | The auth service: configuration, sign-up and sign-in, sessions, reading the user in handlers, email verification, password reset, email and password changes, admin operations, concurrent updates, background email delivery, mailers, errors, security notes. |
| HTTP API | The auth/authhttp routes: route table, curl examples, bearer tokens and cookies, CSRF protection, the email link flows, rate limits, error messages, RequireAuth, OptionalAuth, plain net/http. |
| Auth storage | Choosing an auth store (including a custom prefix or your own store through the facade), the memory store, the MongoDB and PostgreSQL stores (setup, prefixes, indexes, migrations, data model) and writing your own store. |
| Database | The database package: connecting, MongoDB CRUD, PostgreSQL queries, typed scanning, transactions, "not found" handling, raw drivers. |
The mail package: senders (SMTP, log, capture), messages, TLS modes, auth emails, troubleshooting. | |
| Environment | Every environment variable CoreGo reads, precedence rules, the env package and the .env format. |
| Testing | Testing an application built on CoreGo, and running CoreGo's own test suite and integration tests. |
| Migrating from 0.1 | Before and after code for every API that changed in 0.2.0. |
| API reference | Every exported identifier of every package, with its signature. |
Outside this directory
- README: overview and the hello world.
- Quickstart example: a runnable app with a recorded curl session.
- Changelog: what changed in each release.
- Roadmap: what is next and what is explicitly not planned.
Keeping the docs honest
The documentation is written against the code and checked against it: code samples compile against the current release, and every route, status code, default and environment variable is taken from the source. If you change a public API, update the affected page and the API reference in the same change.