Improved Documentation

Author: cimnine

.docker/Wagonfile

@@ -5,20 +5,17 @@ RUN apt-get update && apt-get install -y \
     imagemagick \
  && rm -rf /var/lib/apt/lists/*
 
-RUN ln -s /app/.docker/entrypoint /bin/entrypoint; \
-    ln -s /app/.docker/waitfortcp /bin/waitfortcp
-
 WORKDIR /app/hitobito/
 COPY hitobito/Wagonfile.ci ./Wagonfile
 COPY hitobito/Gemfile hitobito/Gemfile.lock ./
 RUN bundle install
 
-ENV HITOBITO_WAGONS ""
-COPY .docker/Wagonfile ./
-
 WORKDIR /app/
 COPY ./ ./
 
+RUN ln -s /app/.docker/entrypoint /bin/entrypoint; \
+    ln -s /app/.docker/waitfortcp /bin/waitfortcp
+
 WORKDIR /app/hitobito/
 RUN bundle install
 
@@ -31,7 +28,7 @@ ENTRYPOINT [ "/bin/entrypoint" ]
 CMD [ "rails", "server", "-b", "0.0.0.0" ]
 
 ####################################################################
-FROM dev as test
+FROM base as test
 
 ENV RAILS_ENV=test
 

Dockerfile

@@ -1,16 +1,34 @@
 # Hitobito
 
-_hitobito_ is an open source web application to manage complex group hierarchies with members, events and a lot more.
+_Hitobito_ is an open source web application to manage complex group hierarchies with members, events and a lot more.
+A quick way to begin working on Hitobito and it's wagons is using _Docker_ and _docker-compose_.
+
+## System Requirements
+
+In order to use this method, you need to have [Docker][docker] and _[docker-compose][doco]_ installed on your computer.
+The free _Docker Community Edition (CE)_ works perfectly fine.
+
+[docker]: https://docs.docker.com/install/
+[doco]: https://docs.docker.com/compose/install/
 
 ## Preparation
 
-Check out the hitobito projects you'd like to build:
+First, you need to clone this repository:
+
+```bash
+git clone https://github.com/nxt-engineering/hitobito-docker.git hitobito \
+  && cd hitobito
+```
+
+This contains only the Docker instructions.
+But you will also need the Hitobito source code.
+That's why you need to clone the Hitobito core project and the specific Hitobito wagon you'd like to work on:
 
 ```bash
 # core project
 git clone https://github.com/hitobito/hitobito.git
 
-# wagon projects
+# wagon project(s)
 git clone https://github.com/hitobito/hitobito_generic.git
 ```
 
@@ -19,19 +37,18 @@ You need to set up at least one wagon project.
 The final structure should look something like this:
 
 ```bash
-$ ls -l
+$ ls -lh
 total 16K
 -rw-r--r--  1 user 1.3K Jul 15 10:57 Dockerfile
 -rw-r--r--  1 user 1.4K Jul 15 17:43 README.md
 -rw-r--r--  1 user  625 Jul 15 17:41 docker-compose.yml
 drwxr-xr-x 36 user 1.2K Jul 15 13:56 hitobito
 drwxr-xr-x 27 user  864 Jun 11 09:30 hitobito_generic
-drwxr-xr-x 29 user  928 Jul 15 09:43 hitobito_insieme
 ```
 
 ## Docker Runtime
 
-The simplest way to work on hitobito is to use Docker:
+To start the Hitobito application, run the following commands in your shell:
 
 ```bash
 # Start the application
@@ -44,17 +61,8 @@ echo "http://$(docker-compose port app 3000)"
 echo "http://$(docker-compose port mail 1080)"
 ```
 
-### Exposed Ports
-
-The `docker-compose.yml` file does expose all relevant ports.
-But it does not assign them a well-known port.
-This means, that it is _intentionally_ not possible to access the main application using `http://localhost:3000`!
-Either you use `docker-compose ps` (or the `docker-compose port SERVICE PORTNUMBER` command) to get the actual port Docker assigned – or you use something like [Reception](https://github.com/nxt-engineering/reception).
-
-Why would you need this _Reception_ thingy? Because it makes all the services accessible through a reverse proxy that is accessible using `http://SERVICENAME.PROJECTNAME.docker` (or `http://SERVICENAME.PROJECTNAME.local` on Linux).
-This makes work more convenient and allows to have multiple projects, that all bind to the same port (e.g. `3000`), running at the same time.
-(Because Docker will handle the port conflict for us.)
-As an extra you get an overview over all running services and their exposed ports for free at `http://reception.docker` (or `http://reception.local` on linux).
+It will initially take a while to prepare the initial Docker images, to prepare the database and to start the application.
+The process will be shorter on subsequent starts.
 
 ## First Login
 
@@ -124,3 +132,35 @@ docker-compose up sphinx
 
 The server does not automatically re-index.
 In order to re-index, run the indexer again.
+
+## Clean up / Reset
+
+Once you've made your changes and decide to stop working on the project, you should clean up. The following command will remove all data that was created by Docker and _docker-compose_.
+
+```bash
+docker-compose down --volumes --remove-orphans --rmi local
+```
+
+This method is also not too bad if your working environment got screwed up somehow and you'd like to try a fresh start.
+
+## Internals
+
+Here follows a dicussion about why certain things were done a certain way in this repository.
+
+### Exposed Ports
+
+The `docker-compose.yml` file does expose all relevant ports.
+But it does not assign them a well-known port.
+This means, that it is _intentionally_ not possible to access the main application using `http://localhost:3000`!
+Either you use `docker-compose ps` (or the `docker-compose port SERVICE PORTNUMBER` command) to get the actual port Docker assigned – or you use something like [Reception](https://github.com/nxt-engineering/reception).
+
+Why would you need this _Reception_ thingy? Because it makes all the services accessible through a reverse proxy that is accessible using `http://SERVICENAME.PROJECTNAME.docker` (or `http://SERVICENAME.PROJECTNAME.local` on Linux).
+This makes work more convenient and allows to have multiple projects, that all bind to the same port (e.g. `3000`), running at the same time.
+(Because Docker will handle the port conflict for us.)
+As an extra you get an overview over all running services and their exposed ports for free at `http://reception.docker` (or `http://reception.local` on linux).
+
+### Mounts
+
+The current directy is mounted by _docker-compose_ into the running containers.
+The main advantage is a much simpler workflow, because it allows you to change your 'local' files and they are immediately picked up by the commands in the server.
+I.e. you don't have to re-build the Docker images after every time.