docker.recipes

Next.js + PostgreSQL

intermediate

React framework Next.js with PostgreSQL and Prisma ORM.

Overview

Next.js is a React-based full-stack web framework developed by Vercel that provides server-side rendering, static site generation, API routes, and automatic code splitting out of the box. Built on top of React, Next.js simplifies the development of production-ready web applications by handling complex configurations like webpack bundling, TypeScript support, and deployment optimizations automatically. The framework has become the de facto standard for React applications requiring SEO optimization and superior performance through its hybrid rendering capabilities. This stack combines Next.js with PostgreSQL, leveraging Prisma ORM as the database interface layer to create a robust full-stack solution. PostgreSQL's advanced relational database features, including ACID compliance, complex query capabilities, and JSON support, complement Next.js's API routes and server-side rendering perfectly. The integration allows developers to build data-intensive applications with type-safe database operations through Prisma's generated client, while PostgreSQL handles concurrent users and complex data relationships efficiently. This combination is ideal for teams building modern web applications that need both dynamic user interfaces and reliable data persistence. Startups scaling beyond simple CRUD operations, SaaS platforms requiring multi-tenant architectures, and enterprises migrating from legacy systems will find this stack particularly valuable. The type safety provided by Prisma's generated TypeScript client, combined with Next.js's built-in API routes, creates a development experience where database schema changes automatically propagate through the entire application stack.

Key Features

  • Server-side rendering and static site generation with automatic optimization based on page requirements
  • Prisma ORM integration with type-safe database queries and automatic TypeScript client generation
  • PostgreSQL ACID compliance ensuring data integrity across complex business transactions
  • Next.js API routes providing serverless function capabilities for backend logic
  • Automatic code splitting and lazy loading reducing initial bundle sizes
  • PostgreSQL JSON/JSONB support enabling hybrid relational-document data models
  • Prisma migrations with version control for database schema management
  • Next.js Image optimization with WebP conversion and responsive loading

Common Use Cases

  • 1E-commerce platforms requiring SEO-optimized product pages with inventory management
  • 2SaaS applications with user dashboards and complex data relationships
  • 3Content management systems with dynamic routing and user-generated content
  • 4Multi-tenant applications leveraging PostgreSQL's row-level security features
  • 5Real estate platforms with geospatial queries using PostGIS extensions
  • 6Financial applications requiring ACID transactions and audit trails
  • 7Social media platforms with user authentication and content feeds

Prerequisites

  • Docker and Docker Compose installed with at least 2GB available RAM for PostgreSQL
  • Node.js knowledge and familiarity with React hooks and component lifecycle
  • Basic understanding of SQL queries and relational database concepts
  • Port 3000 available for Next.js application access
  • Understanding of environment variables and database connection strings
  • Familiarity with Prisma schema definition and migration workflows

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  app: 
3    build: .
4    container_name: nextjs
5    environment: 
6      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
7    ports: 
8      - "3000:3000"
9    depends_on: 
10      - postgres
11    networks: 
12      - nextjs
13
14  postgres: 
15    image: postgres:16-alpine
16    container_name: postgres
17    environment: 
18      POSTGRES_DB: ${DB_NAME}
19      POSTGRES_USER: ${DB_USER}
20      POSTGRES_PASSWORD: ${DB_PASSWORD}
21    volumes: 
22      - postgres_data:/var/lib/postgresql/data
23    networks: 
24      - nextjs
25
26volumes: 
27  postgres_data: 
28
29networks: 
30  nextjs: 
31    driver: bridge

.env Template

.env
1DB_NAME=nextjs
2DB_USER=nextjs
3DB_PASSWORD=changeme

Usage Notes

  1. 1Docs: https://nextjs.org/docs
  2. 2Create Dockerfile with Node.js, multi-stage for production
  3. 3Run Prisma: docker compose exec app npx prisma migrate deploy
  4. 4Access at http://localhost:3000
  5. 5Prisma Studio: docker compose exec app npx prisma studio
  6. 6Use standalone output mode for smaller Docker images

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

app
app:
  build: .
  container_name: nextjs
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
  ports:
    - "3000:3000"
  depends_on:
    - postgres
  networks:
    - nextjs
postgres
postgres:
  image: postgres:16-alpine
  container_name: postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - nextjs

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  app:
5    build: .
6    container_name: nextjs
7    environment:
8      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
9    ports:
10      - "3000:3000"
11    depends_on:
12      - postgres
13    networks:
14      - nextjs
15
16  postgres:
17    image: postgres:16-alpine
18    container_name: postgres
19    environment:
20      POSTGRES_DB: ${DB_NAME}
21      POSTGRES_USER: ${DB_USER}
22      POSTGRES_PASSWORD: ${DB_PASSWORD}
23    volumes:
24      - postgres_data:/var/lib/postgresql/data
25    networks:
26      - nextjs
27
28volumes:
29  postgres_data:
30
31networks:
32  nextjs:
33    driver: bridge
34EOF
35
36# 2. Create the .env file
37cat > .env << 'EOF'
38DB_NAME=nextjs
39DB_USER=nextjs
40DB_PASSWORD=changeme
41EOF
42
43# 3. Start the services
44docker compose up -d
45
46# 4. View logs
47docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/nextjs-postgres/run | bash

Troubleshooting

  • Error: Cannot connect to PostgreSQL: Ensure DATABASE_URL environment variable matches PostgreSQL service credentials and container is fully started
  • Prisma generate fails: Run 'docker compose exec app npm install' to ensure all dependencies are installed in container
  • Next.js build fails with memory errors: Increase Docker Desktop memory allocation to minimum 4GB for production builds
  • Database migrations stuck: Use 'docker compose exec app npx prisma migrate reset' to reset development database state
  • Port 3000 already in use: Stop other Next.js processes or change port mapping in docker-compose.yml
  • PostgreSQL data persistence issues: Verify postgres_data volume is properly mounted and has correct permissions

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

nextjspostgres

Tags

#nextjs#react#postgres#prisma

Category

Full Web Stacks

Related Recipes

Ad Space