Stop installing Postgres on your laptop : use Docker instead

Tired of managing a full-blown DB server on your development machine ?

Let’s give Docker a try!

Getting started with Docker

First, if your development machine is not running Linux (ie if you’re running windows or mac os x), it’s easier to use boot2docker to get started, since it will take care of installing:

  • VirtualBox (if you already have it installed, don’t worry, it won’t overwrite your current configuration)
  • A Linux VM (based on the latest boot2docker.iso, that will run virtusalized in Virtual Box)
  • Boot2Docker Management Tool v1.4.1
  • Docker Client v1.4.1

Once you’re able to successfully run:

$ docker run helloworld

you’re ready to proceed with PostgreSQL.

PostgreSQL running on Docker for development

Let’s grab the latest version of the PostgreSQL image from Docker official repository, and let’s start the database:

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

A few explanation about this command line:

  • -p 5432:5432 : means that we port forward the container (effectively running the db) 5432 port to the host (in my case, running boot2docker, the VirtualBox vm named boot2docker-vm) 5432 port – since the postgres image EXPOSE the port 5432 for its service, we will be able to connect to the db using this port
  • –name : the name of your container – you can see all your containers and their names using theShell
    $ docker ps -a


  • -e : sets an environment variable (in our case the postgres user password will be « password »)
  • -d : runs the container in detached mode
  • postgres : the name of the image (by default the latest version)

Let’s have a look at the newly created container:

$ docker ps
CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS              PORTS                    NAMES
1dece489d6d0        postgres:latest     "/docker-entrypoint.   7 minutes ago       Up 7 minutes>5432/tcp   postgres

We just got confirmation that our container, named postgres, is running the latest postgres image, and does the proper port forwarding.

Oh ! one last thing ! If using boot2docker, you have to know the ip address of the container’s host:

$ boot2docker ip

That’s it ! You’re all set ! You just installed a PostgreSQL db on your laptop without polluting your environment (it’s dockerized !), and you can access it from your app connecting to on port 5432 as postgres with the password « password »

Interesting things to know

Client tools

I used to run PostgreSQL on a mac, using homebrew, and along with the server came the client tools such as pgql, pg_restore, pg_dump.

Now I use the ones bundled with pgAdmin3, on a typical mac install they are located in /Applications/

$ ls /Applications/
branding    docs        i18n        pg_dump        pg_dumpall    pg_restore    plugins.d    psql        settings.ini

Stopping / starting your dockerized PostgreSQL server

When you start working with your DB, you may want to not loose your changes. Hopefully, Docker can save the changes brought to your container.

If your container is running, find its id:

$ docker ps
CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS              PORTS                    NAMES
1dece489d6d0        postgres:latest     "/docker-entrypoint.   6 days ago          Up 6 days >5432/tcp   postgres

Then stop it:

$ docker kill 1dece489d6d0

or since the container is named:

$ docker kill postgres

To restart it, it’s just as easy as:

$ docker start  postgres

You can check it’s back on with:

$ docker ps
CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS              PORTS                    NAMES
1dece489d6d0        postgres:latest     "/docker-entrypoint.   6 days ago          Up 1 seconds>5432/tcp   postgres

Another approach (more production oriented approach) would be to use data volume containers

Boot2docker shutting down

From times to times (when my laptop goes to sleep or connect to another wifi hotspot) my boot2docker virtual box vm shuts itself down: so I restart it with:

$ boot2docker start

Anthony Dahanne

Anthony Dahanne is a Java software developer for 8 years, his favorite topics are Android, building tools, Continuous Integration and, of course, core Java development. Working for Terracotta, he currently implements the REST management interface for EhCache.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Newest Most Voted
Inline Feedbacks
View all comments
8 years ago

That worked quite nicely for me. One thing though — How can I change the default password used above on a local docker container persistently?

~ aplatypus

Anthony Dahanne
8 years ago

hey there,
you can use the environment variable POSTGRES_PASSWORD to change the db password.
Once your container is started with such an environment variable, it’s “persistently configured”
Using environment variable is a great way to configure containers.

8 years ago

Thanks for that Anthony. I was hoping for something more opaque such as updating the database users table, e.g.: createuser -U postgres -P pgAdmin Or \password postgres For that though, the database contents would need to persist (be updated) too between container instances I guess. Is that correct? May be you can follow-up with a method to ‘keep’ the data store between reboots/instances — That would be very useful. Before I go, I had a thought for unit testing and system tests — Whereby the same docker-postgres container could be made to point to different database stores. So each data… Read more »

Byron Kiourtzoglou
Byron Kiourtzoglou
6 years ago

Nice read, well done!

Back to top button