diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 000000000..21daa2026
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,26 @@
+# we try to aoid adding files to the docker images that change often
+# or that are not needed for running the docker image
+# tis greatly reduces the amount of times we need to rerun `npm install` when building image locally
+# https://codefresh.io/blog/not-ignore-dockerignore/
+# https://docs.docker.com/engine/reference/builder/#dockerignore-file
+
+# consider them hidden
+.*
+
+# not going to run tests inside the docker container
+test/
+
+# do not copy over node_modules we will run `npm install` anyway
+node_modules
+
+# output from test runs and similar things
+*.log
+coverage/
+
+# IDE config files
+jsconfig.json
+*.iml
+
+# let's not get to recursive ;)
+Dockerfile*
+docker-compose*.yaml
diff --git a/.env b/.env
new file mode 100644
index 000000000..6ec7c6b6d
--- /dev/null
+++ b/.env
@@ -0,0 +1,2 @@
+# default values for docker-compose
+PORT=4873
diff --git a/Dockerfile b/Dockerfile
index 9718435e5..a54ed0ba9 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -17,8 +17,9 @@ RUN addgroup -S verdaccio && adduser -S -g verdaccio verdaccio && \
 
 USER verdaccio
 
-EXPOSE 4873
+ENV PORT 4873
+EXPOSE $PORT
 
 VOLUME ["/verdaccio"]
 
-CMD ["sh", "-c", "${APPDIR}/bin/verdaccio --config /verdaccio/conf/config.yaml --listen 0.0.0.0:4873"]
+CMD ["sh", "-c", "${APPDIR}/bin/verdaccio --config /verdaccio/conf/config.yaml --listen 0.0.0.0:${PORT}"]
diff --git a/README.md b/README.md
index 0472cb331..1e2229a48 100644
--- a/README.md
+++ b/README.md
@@ -62,11 +62,13 @@ When you start a server, it auto-creates a config file.
 
 ### Docker
 
-To use the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
+#### Prebuilt images
+
+To pull the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
 
 `docker pull verdaccio/verdaccio`
 
-#### By tags
+##### Tagged Versions
 
 Since version `v2.x` you can pull docker images by [tag](https://hub.docker.com/r/verdaccio/verdaccio/tags/), as follows:
 
@@ -81,29 +83,48 @@ For a minor version:
 docker pull verdaccio/verdaccio:2.1
 ```
 
-For a specific (minor) version:
+For a specific (patch) version:
 
 ```bash
 docker pull verdaccio/verdaccio:2.1.7
 ```
 
-#### Build your own Docker image
+#### Running verdaccio using Docker
 
+To run the docker container:
 ```bash
-docker build -t verdaccio .
+docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
+```
+The last argument defines which image to use. 
+The above line will pull the latest prebuilt image from dockerhub, if you haven't done that already.
+
+If you have [build an image locally](#build-your-own-docker-image) use `verdaccio` as the last argument.
+
+
+You can use `-v` to mount `conf` and `storage` to the hosts filesystem:
+```bash
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio -p 4873:4873 \
+  -v $V_PATH/conf:/verdaccio/conf \
+  -v $V_PATH/storage:/verdaccio/storage \
+  verdaccio/verdaccio
 ```
 
-There is also an npm script for building the docker image, so you can also do:
+#### Docker and custom port configuration
+Any `host:port` configured in `conf/config.yaml` under `listen` is currently ignored when using docker.
 
+If you want to reach verdaccio docker instance under different port, lets say `5000`
+in your `docker run` command replace `-p 4873:4873` with `-p 5000:4873`.
+
+In case you need to specify which port to listen to **in the docker container**,
+since version 2.?.? you can do so by providing additional arguments to `docker run`: `--env PORT=5000`
+This changes which port the docker container exposes and the port verdaccio listens to.
+
+Of course the numbers you give to `-p` paremeter need to match,
+so assuming you want them to all be the same this is what you could copy, paste and adopt:
 ```bash
-npm run build-docker
-```
-
-If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available.
-To build the docker image for raspberry pi execute:
-
-```bash
-npm run build-docker:rpi
+PORT=5000; docker run -it --rm --name verdaccio \ 
+  --env PORT -p $PORT:$PORT
+  verdaccio/verdaccio
 ```
 To run the docker container:
 
@@ -124,9 +145,11 @@ Note: The build might take some minutes to build locally.
 $ docker-compose up --build
 ```
 
+You can set the port to use (for both comtainer and host) by prefixing the above command with `PORT=5000 `.
+
 Docker will generate a named volume in which to store persistent application data. You can use `docker inspect` or `docker volume inspect` to reveal the physical location of the volume and edit the configuration, such as:
  
-```bash
+```
 $ docker volume inspect verdaccio_verdaccio
 [
     {
@@ -140,6 +163,28 @@ $ docker volume inspect verdaccio_verdaccio
 
 ```
 
+#### Build your own Docker image
+
+```bash
+docker build -t verdaccio .
+```
+
+There is also an npm script for building the docker image, so you can also do:
+
+```bash
+npm run build-docker
+```
+
+Note: The first build takes some minutes to build because it needs to run `npm install`,
+and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
+
+If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available.
+To build the docker image for raspberry pi execute:
+
+```bash
+npm run build-docker:rpi
+```
+
 Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.
 
 ##### Docker Examples
diff --git a/conf/docker.yaml b/conf/docker.yaml
index 0b770deb3..2cebb6c0c 100644
--- a/conf/docker.yaml
+++ b/conf/docker.yaml
@@ -1,6 +1,10 @@
 #
-# This is the default config file. It allows all users to do anything,
-# so don't use it on production systems.
+# This is the config file used for the docker images.
+# It allows all users to do anything, so don't use it on production systems.
+#
+# Do not configure host and port under `listen` in this file
+# as it will be ignored when using docker.
+# see https://github.com/verdaccio/verdaccio#docker-and-custom-port-configuration
 #
 # Look here for more config file examples:
 # https://github.com/verdaccio/verdaccio/tree/master/conf
diff --git a/docker-compose.yaml b/docker-compose.yaml
index d81dc16b8..d0f86d661 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -1,10 +1,12 @@
-version: '2'
+version: '2.1'
 services:
   verdaccio:
     build: .
     container_name: verdaccio
+    environment:
+      - PORT
     ports:
-      - "4873:4873"
+      - $PORT:$PORT
     volumes:
        - verdaccio:/verdaccio
 volumes: