Update README

README.md

@@ -1,25 +1,56 @@
-# Docker files for Decidim [![CircleCI](https://circleci.com/gh/decidim/docker.svg?style=svg)](https://circleci.com/gh/decidim/docker)
+# Docker images for Decidim 
 
-## Docker images for development.
+There are two official images available for Decidim on Github Packages: `decidim` and `decidim-generator`.
 
-The development image is intended to be in conjunction with docker-compose. This image includes an script that makes feasible to keep ownership of the files created inside the container for for the user used ouside it.
+The `decidim` image is a dockerized Decidim app with standard core modules. It can be used for quickly spinning up a local instance and kick the tires, or for deployment if all you need are the core modules.
 
-It is convenient, but not absolutely mandatory that you create a volume for the /usr/local/bundle folder.
+The `decidim-generator` image is a base environment with all you need to generate a new Decidim app locally. It is also the base image from which the `decidim` image is built.
 
-## How to use it
+## Using the decidim (app) image
 
-With this docker image you can generate a new Decidim application. For instance for an application called HelloWorld:
+With this image you can run a pre-generated Decidim app:
+
+```bash
+docker run -it --rm \
+  -e DATABASE_USERNAME=postgres \
+  -e DATABASE_PASSWORD=postgres \
+  -e DATABASE_HOST=host.docker.internal \
+  -e RAILS_ENV=development \
+  -p 3000:3000 \
+  docker.pkg.github.com/decidim/docker/decidim:latest
+```
+
+```bash
+docker run -it --rm \
+  -e DATABASE_URL="postgres://user:pass@postgres-host/decidim-production-db" \
+  -p 3000:3000 \
+  docker.pkg.github.com/decidim/docker/decidim:latest
+```
+
+## Using the decidim-generator image
+
+With this image you can generate a new Decidim application:
 
 ```bash
 APP_NAME=HelloWorld
-docker run -it -v "$(pwd):/code" decidim/decidim ${APP_NAME}
+IMAGE=docker.pkg.github.com/decidim/docker/decidim-generator:latest
+docker run -it -v "$(pwd):/code" ${IMAGE} ${APP_NAME}
 sudo chown -R $(whoami): ${APP_NAME}
 ```
 
-Then you can continue with the process detailed on [Getting Started](https://github.com/decidim/decidim/blob/master/docs/getting_started.md).
+From here on you can follow the steps on the [Getting Started](https://github.com/decidim/decidim/blob/master/docs/getting_started.md) guide.
+
+### Using decidim-generator with docker-compose
+
+The generator image can be used in conjunction with docker-compose, and the core [decidim/decidim](https://github.com/decidim/decidim) repo already offers a [docker-compose.yml](https://github.com/decidim/decidim/blob/develop/docker-compose.yml) file (currently pointing to the Docker Hub `decidim/decidim:latest-dev` image).
+
+It is convenient, but not absolutely mandatory to create a volume for the /usr/local/bundle folder.
+
+## Docker Hub images
+
+We're in the process of adopting Github Actions for our automated image build and publishing, and while that flow currently only publishes to Github Packages, there's another flow on circleci publishing images to Docker Hub.
 
-## Publish a new version
+We plan to phase out the circleci flow soon, and publish to Docker Hub with Github Actions as well.
 
-To publish a new version on [Docker Hub](https://hub.docker.com/r/decidim/decidim/) it's necessary to make a PR and change the DECIDIM_VERSION on circle-ci.yml to the last pulished version on rubygems.
+Meanwhile, be aware that Docker Hub and Github Package images are gradually diverging.
 
-CircleCI will execute automatically the bash scripts on scripts/ to build the images and publish them on Docker Hub.