Merge pull request #660 from usrpro/update-dev-docs

Update Dev-docs to use build.yml for building

docs/contributors/environment.rst

@@ -5,39 +5,51 @@ Docker containers
 -----------------
 
 The development environment is quite similar to the production one. You should always use
-the ``master`` version when developing. Simply add a build directive to the images
+the ``master`` version when developing.
-you are working on in the ``docker-compose.yml``:
 
-.. code-block:: yaml
+Building images
+```````````````
 
-  webdav:
+We supply a separate ``test/build.yml`` file for
-    build: ./optional/radicale
+convenience. To build all Mailu containers:
-    image: mailu/$WEBDAV:$VERSION
-    restart: always
-    env_file: .env
-    volumes:
-      - "$ROOT/dav:/data"
-
-  admin:
-    build: ./core/admin
-    image: mailu/admin:$VERSION
-    restart: always
-    env_file: .env
-    volumes:
-      - "$ROOT/data:/data"
-      - "$ROOT/dkim:/dkim"
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-    depends_on:
-      - redis
-
-
-The build these containers.
 
 .. code-block:: bash
 
-  docker-compose build admin webdav
+  docker-compose -f tests/build.yml build
 
-Then you can simply start the stack as normal, newly-built images will be used.
+The ``build.yml`` file has two variables:
+
+#. ``$DOCKER_ORG``: First part of the image tag. Defaults to *mailu* and needs to be changed
+   only  when pushing to your own Docker hub account.
+#. ``$VERSION``: Last part of the image tag. Defaults to *local* to differentiate from pulled
+   images.
+
+To re-build only specific containers at a later time.
+
+.. code-block:: bash
+
+  docker-compose -f tests/build.yml build admin webdav
+
+If you have to push the images to Docker Hub for testing in Docker Swarm or a remote
+host, you have to define ``DOCKER_ORG`` (usually your Docker user-name) and login to
+the hub.
+
+.. code-block:: bash
+
+  docker login
+  Username: Foo
+  Password: Bar
+  export DOCKER_ORG="Foo"
+  export VERSION="feat-extra-app"
+  docker-compose -f tests/build.yml build
+  docker-compose -f tests/build.yml push
+
+Running containers
+``````````````````
+
+To run the newly created images: ``cd`` to your project directory. Edit ``.env`` to set
+``VERSION`` to the same value as used during the build, which defaults to ``local``.
+After that you can run:
 
 .. code-block:: bash
 

tests/build.yml

@@ -3,54 +3,54 @@ version: '3'
 services:
 
   front:
-    image: $DOCKER_ORG/nginx:$VERSION
+    image: ${DOCKER_ORG:-mailu}/nginx:${VERSION:-local}
     build: ../core/nginx
 
   imap:
-    image: $DOCKER_ORG/dovecot:$VERSION
+    image: ${DOCKER_ORG:-mailu}/dovecot:${VERSION:-local}
     build: ../core/dovecot
 
   smtp:
-    image: $DOCKER_ORG/postfix:$VERSION
+    image: ${DOCKER_ORG:-mailu}/postfix:${VERSION:-local}
     build: ../core/postfix
 
   antispam:
-    image: $DOCKER_ORG/rspamd:$VERSION
+    image: ${DOCKER_ORG:-mailu}/rspamd:${VERSION:-local}
     build: ../services/rspamd
 
   antivirus:
-    image: $DOCKER_ORG/clamav:$VERSION
+    image: ${DOCKER_ORG:-mailu}/clamav:${VERSION:-local}
     build: ../optional/clamav
 
   webdav:
-    image: $DOCKER_ORG/radicale:$VERSION
+    image: ${DOCKER_ORG:-mailu}/radicale:${VERSION:-local}
     build: ../optional/radicale
 
   admin:
-    image: $DOCKER_ORG/admin:$VERSION
+    image: ${DOCKER_ORG:-mailu}/admin:${VERSION:-local}
     build: ../core/admin
 
   roundcube:
-    image: $DOCKER_ORG/roundcube:$VERSION
+    image: ${DOCKER_ORG:-mailu}/roundcube:${VERSION:-local}
     build: ../webmails/roundcube
 
   rainloop:
-    image: $DOCKER_ORG/rainloop:$VERSION
+    image: ${DOCKER_ORG:-mailu}/rainloop:${VERSION:-local}
     build: ../webmails/rainloop
 
   fetchmail:
-    image: $DOCKER_ORG/fetchmail:$VERSION
+    image: ${DOCKER_ORG:-mailu}/fetchmail:${VERSION:-local}
     build: ../services/fetchmail
 
   none:
-    image: $DOCKER_ORG/none:$VERSION
+    image: ${DOCKER_ORG:-mailu}/none:${VERSION:-local}
     build: ../core/none
 
   docs:
-    image: $DOCKER_ORG/docs:$VERSION
+    image: ${DOCKER_ORG:-mailu}/docs:${VERSION:-local}
     build: ../docs
 
   setup:
-    image: $DOCKER_ORG/setup:$VERSION
+    image: ${DOCKER_ORG:-mailu}/setup:${VERSION:-local}
     build: ../setup