Production-ready HTMX starter with Python, FastAPI, Jinja2, and PostgreSQL. One-click deploy to Railway.
HTMX + FastAPI + PostgreSQL Starter is a production-ready template for building hypermedia-driven web applications. It combines HTMX for dynamic interactions without JavaScript, Python with FastAPI and Jinja2 for server-side rendering, and PostgreSQL for persistent storage. Deploy in one click and start building.
The template deploys as a Python application built via multi-stage Dockerfile. It connects to a PostgreSQL instance over Railway's private network using asyncpg with connection pooling. Database migrations run automatically on startup, creating the required tables without manual SQL. The application reads DATABASE_URL from environment variables and listens on the port assigned by Railway. A health check endpoint at /health pings the database and returns status, ensuring Railway can verify deployments before routing traffic. Tailwind CSS and HTMX load via CDN, so there is no frontend build step.
- Rapid prototyping of server-rendered web apps that need dynamic interactions without the complexity of React, Vue, or other JavaScript frameworks
- Building internal tools, admin panels, and CRUD dashboards where Python's ecosystem and FastAPI's async performance matter but a full SPA is overkill
- Learning HTMX patterns (hx-get, hx-post, hx-swap, hx-target) with a working reference application backed by a real database
- A Railway PostgreSQL database instance (added via the Railway dashboard or CLI)
- The
DATABASE_URLenvironment variable set to${{Postgres.DATABASE_URL}}on the web service
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying HTMX + FastAPI + PostgreSQL Starter on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
A complete, working Todo application that demonstrates the full HTMX + FastAPI stack. No JavaScript frameworks, no build steps for the frontend, no client-side state management. Just HTML over the wire.
| Layer | Technology | Role |
|---|---|---|
| Frontend | HTMX 2.0.7 + Tailwind CSS | Hypermedia-driven interactions via CDN |
| Templating | Jinja2 3.1 | Server-side HTML rendering with template inheritance |
| Routing | FastAPI 0.115 | High-performance async Python framework |
| Database | PostgreSQL + asyncpg 0.30 | Async connection pooling, prepared statements |
| Deploy | Dockerfile (multi-stage) | Python 3.12-slim final image |
HTMX lets you build dynamic UIs by returning HTML fragments from the server instead of JSON. No React, no Vue, no bundle. Your FastAPI backend renders HTML, HTMX swaps it into the DOM. The browser does what browsers do best.
Jinja2 is the standard Python templating engine with template inheritance, macros, and filters. It integrates natively with FastAPI through Starlette's templating support.
FastAPI is one of the fastest Python web frameworks with automatic OpenAPI docs, type validation via Pydantic, and native async/await support. It handles the HTTP layer so you focus on your application.
PostgreSQL needs no introduction. The asyncpg driver gives you connection pooling and direct access to PostgreSQL-specific features with full async support, no ORM in the way.
.
├── main.py # FastAPI app, routes, middleware
├── database.py # asyncpg connection pool + auto-migration
├── templates/
│ ├── layout.html # Base HTML with HTMX + Tailwind CDN
│ ├── home.html # Home page with todo list
│ └── todo_item.html # HTMX-powered todo item component
├── requirements.txt # Python dependencies
└── Dockerfile # Multi-stage build (python:3.12-slim)
The Todo app showcases core HTMX patterns you'll use in real projects:
hx-post+hx-target+hx-swap="afterbegin"- Create items and prepend to list without page reloadhx-patch+hx-target(self) - Toggle completion with in-place swaphx-delete+hx-swap="outerHTML"- Remove items with smooth DOM removalhx-on::after-request- Reset form after successful submission- Health check endpoint -
/healthreturns JSON status with DB ping
Click the button above or:
- Fork this repo
- Create a new project on Railway
- Add a PostgreSQL database
- Add a service from your forked repo
- Set the variable:
DATABASE_URL=${{Postgres.DATABASE_URL}} - Railway auto-detects the Dockerfile and deploys
The app auto-migrates the database on startup. No manual SQL needed.
# Prerequisites: Python 3.12+, PostgreSQL running locally
# Clone and run
git clone https://github.com/atoolz/railway-htmx-python-fastapi-jinja2-pg.git
cd railway-htmx-python-fastapi-jinja2-pg
# Create virtual environment
python -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Set your database URL
export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
# Run the server
python main.pyOpen http://localhost:8080.
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL |
Yes | - | PostgreSQL connection string |
PORT |
No | 8080 |
Server port (Railway sets this automatically) |
This is one of 15 HTMX starter templates covering different backend stacks, all following the same pattern and ready for Railway deployment:
| Stack | Status |
|---|---|
| Bun + Elysia | Coming soon |
| .NET + Razor | Coming soon |
| Elixir + Phoenix | Coming soon |
| Go + Chi | Live |
| Go + Echo | Live |
| Go + Fiber | Live |
| Java + Spring Boot (MySQL) | Live |
| Java + Spring Boot (PostgreSQL) | Live |
| Node + Express | Live |
| Node + Hono | Live |
| PHP + Laravel | Live |
| Python + Django | Live |
| Python + FastAPI | This repo |
| Ruby + Rails 8 | Live |
| Rust + Axum + Askama | Live |
Built by AToolZ for the HTMX community