Namma Axum Starter

A beginner-friendly, production-inspired Rust backend starter built with Axum.

Topics

rust axum tokio backend web-server rest-api starter-template open-source beginner-friendly namma-rust

Project Introduction

Namma Axum Starter is a small, readable Rust backend starter project for learning how to build HTTP APIs with Axum. It is designed for people who want to understand real backend structure one step at a time without being dropped into a large production codebase on day one.

The project starts with a working server, basic route modules, environment configuration, tracing logs, CORS middleware, JSON responses, and a simple error pattern. Future phases will introduce testing, validation, authentication, database integration, Docker, CI, and deployment guidance.

This repository is part of the NammaRust open-source learning effort.

Why Namma Axum Starter Exists

Rust backend development can feel hard for beginners. Many examples are either very small single-file demos or large production templates with databases, authentication, queues, deployment tooling, and many abstractions already included.

Namma Axum Starter takes a slower path:

• Start with a small working backend.
• Explain the structure clearly.
• Add features phase by phase.
• Keep the code readable for beginners.
• Give intermediate developers clean modules to improve.
• Help contributors learn by making real open-source contributions.

The goal is not to hide backend complexity. The goal is to introduce it in the right order.

What You Will Learn

By reading and contributing to this project, you can learn:

• How to create an Axum server
• How routing works in Axum
• How to organize routes into modules
• How to manage config using environment variables
• How to use tracing logs
• How to add middleware with tower-http
• How to return JSON responses
• How to structure basic error handling
• How to prepare the project for database and authentication features later
• How to contribute to an open-source Rust project

Current Phase

Current phase: Phase 1 - Starter Foundation

Phase 1 keeps the project intentionally small. It focuses on the base server, route structure, config, logging, middleware, and documentation. Database code, JWT authentication, Docker, and CI are planned for later phases.

Current Features

• Axum HTTP server
• Tokio async runtime
• Health check route
• Demo users route
• Environment configuration
• Tracing logs
• CORS middleware
• Shared response pattern
• Basic error structure
• Clean folder structure
• Beginner-friendly documentation

Planned Features

• Request validation
• Testing
• JWT authentication
• Password hashing
• PostgreSQL with SQLx
• Database migrations
• Docker
• GitHub Actions CI
• API docs
• Deployment guide
• Rate limiting
• Role-based authorization
• Production checklist

See ROADMAP.md for the full roadmap.

Project Philosophy

• Start small.
• Learn by contributing.
• Keep code readable.
• Avoid unnecessary complexity.
• Prefer clear examples over clever abstractions.
• Add production-inspired structure without overwhelming beginners.
• Discuss large changes before implementing them.

Tech Stack

Layer	Tool	Purpose
Language	Rust	Safe and fast systems programming language
Runtime	Tokio	Async runtime for handling concurrent work
Web framework	Axum	HTTP routing and request handling
Middleware	tower-http	CORS and HTTP middleware utilities
Serialization	serde / serde_json	JSON request and response data
Logging	tracing / tracing-subscriber	Structured application logs
Config	dotenvy / env	Environment-based configuration
Errors	thiserror	Clean application error types
Database	SQLx	Planned for PostgreSQL integration in a later phase

API Routes

Health Check

Request:

GET /health

Curl:

curl http://127.0.0.1:3000/health

Response:

{
  "status": "ok",
  "service": "namma-axum-starter"
}

Demo Users

Request:

GET /api/users

Curl:

curl http://127.0.0.1:3000/api/users

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Ananya",
      "email": "ananya@example.com"
    },
    {
      "id": 2,
      "name": "Rahul",
      "email": "rahul@example.com"
    }
  ]
}

The users route returns sample data only. PostgreSQL and SQLx integration are planned for a later phase.

Folder Structure

.
├── Cargo.toml
├── README.md
├── ROADMAP.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── LICENSE
├── .gitignore
├── .env.example
└── src
    ├── main.rs
    ├── app.rs
    ├── config.rs
    ├── error.rs
    ├── response.rs
    ├── routes
    │   ├── mod.rs
    │   ├── health.rs
    │   └── users.rs
    └── middleware
        └── mod.rs

Path	Purpose
Cargo.toml	Rust package metadata and dependencies
README.md	Main project guide for GitHub visitors
ROADMAP.md	Planned project phases and learning direction
CONTRIBUTING.md	Guide for contributors
CODE_OF_CONDUCT.md	Community behavior expectations
LICENSE	MIT license
.gitignore	Files and folders Git should ignore
.env.example	Example local environment configuration
src/main.rs	Application entry point and server startup
src/app.rs	Axum router setup and shared app state
src/config.rs	Environment variable loading
src/error.rs	Application and configuration error types
src/response.rs	Shared JSON response helpers
src/routes/mod.rs	Route registration
src/routes/health.rs	Health check route
src/routes/users.rs	Demo users route
src/middleware/mod.rs	Middleware setup such as CORS

How To Run Locally

Install the latest stable Rust toolchain from rustup.rs.

Clone the repository:

git clone https://github.com/NammaRust/namma-axum-starter.git
cd namma-axum-starter

Create a local environment file:

cp .env.example .env

Run the server:

cargo run

The server starts at:

http://127.0.0.1:3000

Test the routes:

curl http://127.0.0.1:3000/health
curl http://127.0.0.1:3000/api/users

You can also open these URLs in your browser:

http://127.0.0.1:3000/health
http://127.0.0.1:3000/api/users

Environment Variables

Variable	Example	Purpose
APP_HOST	127.0.0.1	Host address for the server
APP_PORT	3000	Port for the server
RUST_LOG	debug	Log level and tracing filter

Example:

APP_HOST=127.0.0.1
APP_PORT=3000
RUST_LOG=debug

New To Rust Backend?

Start with these files:

• README.md to understand the project
• src/main.rs to see how the server starts
• src/app.rs to see how the router is created
• src/routes/health.rs to read the simplest route
• src/routes/users.rs to see a JSON response with sample data
• src/config.rs to understand environment variables
• CONTRIBUTING.md to learn how to make your first contribution

You do not need to understand every module before contributing. Documentation fixes, examples, tests, and small route improvements are useful contributions.

How To Contribute

Please read CONTRIBUTING.md before opening a pull request.

This project welcomes docs, code, tests, examples, issue reports, and reviews. If you are new to Rust or open source, start with small improvements and ask questions when you are unsure.

Good First Issue Examples

• Add README improvements
• Add route documentation
• Add a test for the health route
• Add comments that help beginners understand code
• Improve error response examples
• Add middleware explanation
• Add curl examples
• Add an example issue template
• Improve wording in the roadmap

Community

NammaRust is a Rust learning community. This project is a place for contributors to learn backend development, practice open-source collaboration, and build a useful starter project together.

License

This project is licensed under the MIT License. See LICENSE for details.

Maintainers

Maintained by NammaRust contributors.