Axum + Postgres Application Boilerplate

This repository contains an application template built using Axum and PostgreSQL. It serves as a starting point for creating a new Axum server.

GraphQL

Swagger

The full list of crates used can be found in the Cargo.toml file. However, here are some key ones:

• Axum - A user-friendly, modular web framework built with Tokio, Tower, and Hyper.
• Sea-ORM - An async & dynamic ORM for Rust, supporting PostgreSQL, MySQL, SQLite, and MSSQL.
• Tracing - A framework for instrumenting Rust programs to collect structured, event-based diagnostic information.
• Chrono - A comprehensive Date and Time library for Rust.
• Serde - A framework for efficiently and generically serializing and deserializing Rust data structures.
• Uuid - A library for generating and parsing UUIDs.

Table of Contents

• Features
• Project Structure
  • Source Code
    • Common Utilities
    • Database
    • Modules
    • Core Files
  • Configuration and Build Files
  • Documentation
• Getting Started
  • Clone this Repository
  • Run Postgres
  • Configure the Application
  • Set Up the Application Database
  • Starting the Application
  • Autoreloading
• Running with Docker Compose
• Production Build

Features

• Project Structure

  • Modular Axum + PostgreSQL setup
  • Environment-based configuration
  • Docker support

• Database

  • Sea-ORM integration
  • Database migrations

• API

  • REST endpoints
  • GraphQL support
  • API versioning
  • OpenAPI/Swagger documentation

• Authentication & Authorization

  • JWT authentication
  • Role-based access control (RBAC)

• Error Handling & Logging

  • Centralized error handling
  • Logging with Tracing

• Testing

  • Unit tests
  • Integration tests
  • API tests

• Security

  • Rate limiting
  • CORS configuration
  • Input validation

• Monitoring & Observability

  • Metrics collection
  • Health checks
  • Performance monitoring

• Developer Experience

  • Code generation tools
  • Development scripts
  • CI/CD pipeline configuration

Project Structure

.
├── src/                  # Source code
│   ├── common/           # Common utilities and shared code
│   │   ├── utils/        # Utility functions and helpers
│   │   ├── cfg.rs        # Configuration management
│   │   ├── middleware.rs # Custom middleware implementations
│   │   ├── api_error.rs  # Error handling and custom error types
│   │   └── telemetry.rs  # Logging and observability setup
│   │
│   ├── database/         # Database configuration and migrations
│   │   ├── migrations/   # Database migration files
│   │   └── mod.rs        # Database connection and setup
│   │
│   ├── modules/          # Application modules and features
│   │   ├── auth/         # Authentication and authorization
│   │   ├── health/       # Health check endpoints
│   │   ├── users/        # User management
│   │   └── mod.rs        # Module registration and exports
│   │
│   ├── app.rs            # Application setup and configuration
│   ├── doc.rs            # API documentation setup
│   ├── lib.rs            # Library entry point
│   ├── main.rs           # Application entry point
│   └── query_root.rs     # GraphQL query root definitions
│
├── docs/                 # Documentation files
│   └── images/           # Documentation images and diagrams
│
├── Cargo.toml            # Project dependencies and metadata
├── docker-compose.yml    # Docker Compose configuration
├── Dockerfile            # Docker build instructions
└── .env.sample           # Sample environment variables

Each directory and file serves a specific purpose:

Source Code (src/)

Common Utilities (src/common/)

• utils/: Reusable helper functions and utilities
• cfg.rs: Environment configuration and settings management
• middleware.rs: Custom middleware for request processing
• api_error.rs: Centralized error handling and custom error types
• telemetry.rs: Logging, tracing, and observability setup

Database (src/database/)

• migrations/: Database schema migration files
• mod.rs: Database connection pool and configuration

Modules (src/modules/)

• auth/: Authentication and authorization logic

  auth/
  ├── controller.rs         # Authentication endpoints and handlers
  ├── service.rs            # Authentication business logic
  ├── mod.rs                # Module exports and route registration
  ├── dto/                  # Data Transfer Objects
  │   └── mod.rs            # Auth request/response structures
  └── guards/               # Authentication guards
      ├── auth_guard.rs     # JWT authentication guard
      ├── admin_guard.rs    # Admin role guard
      ├── graphql_guards.rs # GraphQL-specific guards
      └── mod.rs            # Guard exports

• health/: Health check endpoints and monitoring
• users/: User management and related functionality

  users/
  ├── controller.rs      # HTTP request handlers and route definitions
  ├── service.rs         # Business logic and data operations
  ├── mod.rs             # Module exports and route registration
  ├── dto/               # Data Transfer Objects
  │   └── mod.rs         # Request/Response data structures
  ├── entities/          # Database entity definitions
  │   └── mod.rs         # User entity and related models
  └── enums/             # User-related enumerations
      ├── mod.rs         # Enum exports
      ├── user_role.rs   # User role definitions
      └── user_status.rs # User status definitions

• mod.rs: Module registration and exports

Core Files

• app.rs: Main application setup, middleware, and route configuration
• doc.rs: OpenAPI/Swagger documentation setup
• lib.rs: Library code and public API
• main.rs: Application entry point and server startup
• query_root.rs: GraphQL schema and resolver definitions

Configuration and Build Files

• Cargo.toml: Project dependencies and metadata
• docker-compose.yml: Docker Compose configuration for development
• Dockerfile: Docker build instructions
• .env.sample: Sample environment variables template

Documentation

• docs/: Project documentation
  • images/: Documentation images and diagrams

Getting Started

To begin with this project:

Clone this Repository

$ git clone https://github.com/nakamuraos/axum-postgres-boilerplate
$ cd axum-postgres-boilerplate

Run Postgres

The most straightforward way to run Postgres is by using a container with a pre-built image. The command below will start latest version of Postgres using Docker:

$ docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=password postgres

Configure the Application

The backend application is preferably configured via environment variables. To simplify the process during development, we can use .env files to avoid defining the variables each time. As a starting point, you can simply copy the sample .env file in this repo and modify the .env file as per the comments therein.

$ cp .env.sample .env

Starting the Application

With everything else set up, all you need to do now is:

$ cargo run

• The application will be available at http://localhost:8080
  • Swagger: http://localhost:8080/docs
  • GraphQL: http://localhost:8080/graphql

Autoreloading

To start the server and autoreload on code changes:

$ cargo install cargo-watch
$ cargo watch -q -x run

To format .json logs using jq:

$ cargo watch -q -x run | jq .

Running with Docker Compose

This project includes Docker Compose configuration for easy development and deployment. To run the application using Docker Compose:

1. Make sure you have Docker and Docker Compose installed on your system.

2. Copy the sample environment file:

$ cp .env.sample .env

3. Start the application and its dependencies (PostgreSQL):

$ docker-compose up

To run in detached mode (in the background):

$ docker-compose up -d

To stop the application:

$ docker-compose down

The application will be available at http://localhost:8080, and PostgreSQL will be accessible on port 5432.

Production Build

Building for Production

To create an optimized production build:

$ cargo build --release

The optimized binary will be available at target/release/server.

Production Deployment

Using Docker

1. Build the production Docker image:

$ docker build -t axum-postgres-boilerplate:prod .

2. Run the container:

$ docker run -d \
  --name axum-app \
  -p 8080:8080 \
  -v $(pwd)/.env:/app/.env \
  axum-postgres-boilerplate:prod

Manual Deployment

1. Copy the release binary to your production server:

$ scp target/release/server user@your-server:/path/to/deployment

2. Copy your production .env file:

$ scp .env user@your-server:/path/to/deployment

3. Run the application:

$ ./server

Production Considerations

• Use a reverse proxy (like Nginx) in front of your application
• Set up proper SSL/TLS certificates
• Use a production-grade PostgreSQL setup

Contributing

Contributions are always welcome! Feel free to check the current issues in this repository for tasks that need attention. If you find something missing or that could be improved, please open a new issue.