DEV Community

Cover image for Dockerizing a Next.js App with PostgreSQL and pgAdmin: A Step-by-Step Guide
Er. Ankit Parashar
Er. Ankit Parashar

Posted on

Dockerizing a Next.js App with PostgreSQL and pgAdmin: A Step-by-Step Guide

#docker #nextjs #postgres #javascript

Containerization simplifies full-stack development by packaging your application with its dependencies in an isolated environment. In this guide, we’ll walk through how to containerize a Next.js app, link it with a PostgreSQL database, and add pgAdmin for database management—all using Docker.

👉 Source Code: GitHub – next-docker-template

Why Use Docker for a Full-Stack Setup?

  • Uniform Development Environments: Works the same on every machine
  • Separation of Concerns: App, DB, and tooling run independently
  • Ease of Onboarding: New team members can start instantly
  • Scalability: Ready for CI/CD pipelines and production deployment

Project Structure Overview

The entire project resides in the next-app directory, following this layout:

next-app/
├── app/                    # Core Next.js app code
├── public/                 # Static files
├── nginx/                  # Optional: reverse proxy setup
├── Dockerfile              # Docker build instructions
├── docker-compose.yml      # Multi-service orchestration
├── .env                    # Environment config
├── generate-docker-files.js # Script to generate Docker files
Enter fullscreen mode Exit fullscreen mode

🛠 For complete project files and folder structure, refer to the GitHub repository linked above.

Dockerfile: Building the Next.js Application

The Dockerfile defines how the container image is built. We use a minimal Node.js base image, install dependencies, copy in the code, and expose the necessary port.

To keep this post clean, you can explore the file here:

🔗 Dockerfile on GitHub

docker-compose.yml: Service Orchestration

docker-compose.yml handles the setup of three services:

  • web: The main Next.js development server
  • db: A PostgreSQL database (version 16)
  • pgadmin: A web interface to manage PostgreSQL visually

All services run in their own containers but are connected via Docker’s internal network.

📄 Explore the full config file:

🔗 docker-compose.yml

PostgreSQL + pgAdmin: Local Database Setup

PostgreSQL is configured with default credentials (postgres for both user and password). pgAdmin is served at http://localhost:5050 and provides a GUI for managing the database.

Connecting pgAdmin to PostgreSQL

  1. Open pgAdmin in your browser (localhost:5050)
  2. Log in using:
  3. Add a new server:
    • Name: anything you like
    • Host: db (the Docker service name)
    • Username/Password: postgres / postgres

.dockerignore: Optimizing the Build

The .dockerignore file ensures certain files and directories are excluded from your Docker image to keep it lean and secure. Example entries include:

node_modules
.next
npm-debug.log
.env
.DS_Store
Enter fullscreen mode Exit fullscreen mode

Bonus: Auto-Generate Docker Setup Files

To speed up your setup, a helper script generate-docker-files.js is included. Run it once to auto-generate your Dockerfile, docker-compose.yml, and .dockerignore.

✏️ Script source:

generate-docker-files.js

Running Everything

With all configuration files in place, start your app using:

docker-compose up --build
Enter fullscreen mode Exit fullscreen mode

Then access the following:

  • Next.js App: http://localhost:3000
  • pgAdmin: http://localhost:5050
  • PostgreSQL: available locally on port 5432

Wrap-Up

You now have a fully dockerized Next.js development environment with PostgreSQL and pgAdmin. This stack provides a solid base for full-stack development, CI/CD pipelines, and scalable deployment.

⭐ Clone and explore the full project:

https://github.com/ankitparashar700/next-docker-template

Want to contribute or suggest improvements? Open an issue or fork the repo on GitHub.

Happy coding!

Top comments (0)