Production-ready HTMX starter with Java, Spring Boot, Thymeleaf, and PostgreSQL. One-click deploy to Railway.

Deploy and Host HTMX + Spring Boot + PostgreSQL Starter on Railway

HTMX + Spring Boot + PostgreSQL Starter is a production-ready template for hypermedia-driven web apps. It uses HTMX for partial updates, Spring Web + Thymeleaf for server-rendered HTML, JPA + Flyway for persistence, and PostgreSQL. DATABASE_URL is parsed from Railway (postgres:// / postgresql://) into a HikariCP datasource. Tailwind and HTMX load from CDN.

About Hosting

Multi-stage Dockerfile (Maven build, JRE runtime). Flyway runs migrations on startup. GET /health returns JSON and checks the database. PORT defaults to 8080.

Dependencies for Hosting

• Railway PostgreSQL (or compatible URL in DATABASE_URL)
• DATABASE_URL = ${{Postgres.DATABASE_URL}} on the web service

Deployment Dependencies

• HTMX
• Spring Boot
• Thymeleaf
• Flyway

Why Deploy on Railway?

Railway hosts your stack with minimal configuration and scales as you grow.

What's Inside

Layer	Technology	Role
Frontend	HTMX 2.0.7 + Tailwind (CDN)	Partial page updates
Templating	Thymeleaf	SSR + fragments for HTMX swaps
API	Spring Web	REST + HTML responses
Database	PostgreSQL + JPA + Flyway	Entities, migrations

Project Structure

.
├── src/main/java/com/atoolz/htmx/
│   ├── HtmxApplication.java
│   ├── config/RailwayDataSourceConfig.java
│   └── todo/                    # Entity, repository, controller
├── src/main/resources/
│   ├── application.yaml
│   ├── db/migration/V1__todos.sql
│   └── templates/
│       ├── home.html
│       └── fragments/todo-item.html
├── pom.xml
└── Dockerfile

HTMX Patterns Demonstrated

• hx-post, hx-patch, hx-delete with hx-target / hx-swap
• Health check — GET /health

Deploy to Railway

1. Fork this repo (or connect it)
2. New project → add PostgreSQL
3. Add a web service from this repo (Dockerfile root)
4. Set DATABASE_URL = ${{Postgres.DATABASE_URL}}
5. Health check path: /health

Local Development

# Java 21 + Maven + local PostgreSQL
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
mvn spring-boot:run

Open http://localhost:8080.

Environment Variables

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL URL (postgres:// or postgresql://); on Railway reference ${{Postgres.DATABASE_URL}}
PORT	No	8080	HTTP port

Railway template: PostgreSQL service variables

Use one variable per line when defining the PostgreSQL plugin service. The web service typically references the plugin’s canonical URL (see last lines). Generate POSTGRES_PASSWORD with Railway’s secret helper — do not commit real passwords.

Template icon (Railway): assets/icon.svg

PGDATA="" # data directory (volume); often set by the image
PGHOST="${{RAILWAY_PRIVATE_DOMAIN}}" # private hostname for other Railway services
PGPORT="" # omit for default 5432, or set explicitly
PGUSER="${{POSTGRES_USER}}" # DB role; keep aligned with POSTGRES_USER
PGDATABASE="${{POSTGRES_DB}}" # database name
PGPASSWORD="${{POSTGRES_PASSWORD}}" # password for PGUSER
POSTGRES_DB="" # DB created on first init (official image / plugin)
DATABASE_URL="postgresql://${{PGUSER}}:${{POSTGRES_PASSWORD}}@${{RAILWAY_PRIVATE_DOMAIN}}:5432/${{PGDATABASE}}" # in-cluster connection string
POSTGRES_USER="" # superuser name on first init
SSL_CERT_DAYS="" # optional TLS cert lifetime if you generate certs
POSTGRES_PASSWORD="${{ secret(32, \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ\") }}" # generated root password
DATABASE_PUBLIC_URL="postgresql://${{PGUSER}}:${{POSTGRES_PASSWORD}}@${{RAILWAY_TCP_PROXY_DOMAIN}}:${{RAILWAY_TCP_PROXY_PORT}}/${{PGDATABASE}}" # TCP proxy for external clients
RAILWAY_DEPLOYMENT_DRAINING_SECONDS="" # drain window during deploys

# Web service (Spring Boot) — reference the Postgres plugin:
DATABASE_URL="${{Postgres.DATABASE_URL}}" # postgres:// or postgresql://; parsed by RailwayDataSourceConfig

Part of the HTMX Railway Collection

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)	This repo
Node + Express	Live
Node + Hono	Live
PHP + Laravel	Live
Python + Django	Live
Python + FastAPI	Live
Ruby + Rails 8	Live
Rust + Axum + Askama	Live

License

MIT

---

_{Built by AToolZ for the HTMX community}