uniformize READMEs to 'Usage with docker' (refs #27)

mborne · Dec 10, 2022 · 15af65d · 15af65d
1 parent 0fbd2dc
commit 15af65d
Show file tree

Hide file tree

Showing 28 changed files with 85 additions and 94 deletions.
diff --git a/README.md b/README.md
@@ -21,13 +21,14 @@ See [notes about docker-compose](docs/docker-compose.md) for more details.
 | [traefik](traefik/README.md) | A reverse proxy/load balancer including **configuration discovery** mechanism | &#9745; | &#9745; |
 | [whoami](whoami/README.md)   | An helloworld to discover [traefik](traefik/README.md)                        | &#9745; | &#9745; |
 
-### CI/CD
+### CI/CD pipeline
 
 | Name                             | Description                                                                 | Docker  |   K8S   |
 | -------------------------------- | --------------------------------------------------------------------------- | :-----: | :-----: |
 | [Jenkins](jenkins/README.md)     | Open source automation server with hundred of plugins (ansible, jmeter,...) | &#9745; | &#9745; |
 | [ArgoCD](argocd/README.md)       | GitOps **continuous delivery** tool for **Kubernetes**                      |   NA    | &#9745; |
 | [SonarQube](sonarqube/README.md) | Centralisation of Code Quality and Code Security metrics                    | &#9745; | &#9744; |
+| [Vault](vault/README.md) | Secret storage and management server with an API | &#9745; | &#9744; |
 
 ### Authentication
 
@@ -36,12 +37,6 @@ See [notes about docker-compose](docs/docker-compose.md) for more details.
 | [Keycloak](keycloak/README.md) | Open Source Identity and Access Management providing (**OIDC, SAML**) | &#9745; | &#9744; |
 | [OpenLDAP](openldap/README.md) | Community developed **LDAP** software                                 | &#9745; | &#9744; |
 
-### Secrets
-
-| Name                     | Description                                      | Docker  |   K8S   |
-| ------------------------ | ------------------------------------------------ | :-----: | :-----: |
-| [Vault](vault/README.md) | Secret storage and management server with an API | &#9745; | &#9744; |
-
 ### Storage
 
 | Name                             | Description                                                                                             | Docker  |                             K8S                              |
@@ -64,7 +59,7 @@ See [notes about docker-compose](docs/docker-compose.md) for more details.
 | Name                                     | Description                                                                           | Docker  |   K8S   |
 | ---------------------------------------- | ------------------------------------------------------------------------------------- | :-----: | :-----: |
 | [Elasticsearch](elasticsearch/README.md) | ELK - Log storage and indexation                                                      | &#9745; | &#9745; |
-| [Kibana](kibana/README.md)               | ELK - User Interface                                                                  | &#9745; | &#9745; |
+| [Kibana](kibana/README.md)               | ELK - User Interface                                                                  | &#9745; | &#9744; |
 | [OpenSearch](opensearch/README.md)       | Forked from [Elasticsearch](https://www.elastic.co/fr/elasticsearch/) by AWS          | &#9745; | &#9745; |
 | [Netdata](netdata/README.md)             | A monitoring tool with an easy setup                                                  | &#9745; | &#9744; |
 | [Fluend](fluentd/README.md)              | An attempt to configure [Fluend](https://www.fluentd.org/) to collect containers logs | &#9745; | &#9744; |

diff --git a/adminer/README.md b/adminer/README.md
@@ -1,8 +1,8 @@
 # adminer
 
-Docker container running [adminer](https://hub.docker.com/_/adminer/)
+Container running [adminer](https://hub.docker.com/_/adminer/).
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start adminer : `docker-compose up -d`
 * Open https://adminer.dev.localhost/

diff --git a/argocd/README.md b/argocd/README.md
@@ -1,6 +1,8 @@
 
 
-# [Argo CD](https://argo-cd.readthedocs.io/en/stable/)
+# Argo CD
+
+Container running [Argo CD](https://argo-cd.readthedocs.io/en/stable/).
 
 ## Usage with kustomize
 

diff --git a/cloudbeaver/README.md b/cloudbeaver/README.md
@@ -1,8 +1,8 @@
 # CloudBeaver
 
-Container running [dbeaver/cloudbeaver](https://hub.docker.com/r/dbeaver/cloudbeaver) official image.
+Container running [dbeaver/cloudbeaver](https://hub.docker.com/r/dbeaver/cloudbeaver).
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start cloudbeaver : `docker-compose up -d`
 * Open https://cloudbeaver.dev.localhost/

diff --git a/elasticsearch/README.md b/elasticsearch/README.md
@@ -6,7 +6,7 @@ Containers running [Elasticsearch](https://www.elastic.co/elasticsearch/) for **
 
 * [max_map_count >= 262144](../docs/max_map_count.md)
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start elasticsearch : `docker-compose up -d`
 * Open https://es.dev.localhost or https://es.dev.localhost/_cat/nodes?v&pretty
@@ -30,7 +30,25 @@ kubectl apply -f https://download.elastic.co/downloads/eck/2.2.0/operator.yaml
 
 ...and usage in [geonetwork/manifest/base/elasticsearch.yaml](../geonetwork/manifest/base/elasticsearch.yaml) / [geonetwork/manifest/base/statefulset.yaml](../geonetwork/manifest/base/statefulset.yaml)
 
-## See also
+
+## Troubleshooting
+
+### vm.max_map_count too low
+
+> [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
+
+```bash
+sudo sysctl -w vm.max_map_count=262144
+```
+
+### Disable disk quota / watermark
+
+```bash
+bash disable-quota.sh
+```
+
+
+## Resources
 
 * [Install Elasticsearch with Docker](https://www.elastic.co/guide/en/elasticsearch/reference/7.15/docker.html#docker)
 * [How to disable ElasticSearch disk quota / watermark](https://techoverflow.net/2019/04/17/how-to-disable-elasticsearch-disk-quota-watermark/) : avoid read-only problems

diff --git a/elasticsearch/debug-compose.md b/elasticsearch/debug-compose.md
diff --git a/fluentd/README.md b/fluentd/README.md
@@ -1,12 +1,16 @@
 # Fluentd
 
+**WORK IN PROGRESS**
+
 Container running [fluentd](https://www.fluentd.org/) to collect logs.
 
 ## Pre-requisite
 
 * [OpenSearch](../opensearch/README.md) ( see [fluentd/conf/fluent.conf](fluentd/conf/fluent.conf) )
 
-## Usage with docker-compose
+## Usage with docker
+
+* Read [conf/fluent.conf](conf/fluent.conf)
 
 * Start containers :
 
@@ -34,8 +38,6 @@ docker run --rm --log-driver=fluentd --log-opt tag="docker.echo.{{.ID}}" ubuntu
 
 ## Usage with helm
 
-**WORK IN PROGRESS**
-
 * Add repository : `helm repo add fluent https://fluent.github.io/helm-charts`
 * Update helm repositories : `helm repo update`
 * Create namespace : `kubectl create namespace fluent-system`
@@ -51,7 +53,7 @@ Note :
 
 * see [fluent-bit/values.yaml](https://github.com/fluent/helm-charts/blob/main/charts/fluent-bit/values.yaml)
 
-## Reference
+## Resources
 
 * [docs.fluentd.org - container-deployment/docker-compose](https://docs.fluentd.org/container-deployment/docker-compose)
 * [www.fluentd.org - Docker Logging](https://www.fluentd.org/guides/recipes/docker-logging)
diff --git a/geonetwork/README.md b/geonetwork/README.md
@@ -1,8 +1,8 @@
 # GeoNetwork (CSW, CSW-T)
 
-Docker container running [GeoNetwork](https://geonetwork-opensource.org/).
+Container running [GeoNetwork](https://geonetwork-opensource.org/).
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start [Elasticsearch](../elasticsearch/README.md#usage-with-docker-compose)
 * Start geonetwork : `docker-compose up -d`

diff --git a/geoserver/README.md b/geoserver/README.md
@@ -1,11 +1,11 @@
 
-# GeoServer (WMS, WFS, WMTS)
+# GeoServer
 
-Docker container running [GeoServer](https://geoserver.org/)
+Container running [GeoServer](https://geoserver.org/) to serve spatial data (WMS, WFS, WMTS).
 
-## Usage with docker-compose
+## Usage with docker
 
-* Build GeoServer : `docker-compose build`
+* Build GeoServer : `docker-compose build` (see [Dockerfile](Dockerfile))
 
 * Start GeoServer : `docker-compose up -d`
 

diff --git a/jenkins/README.md b/jenkins/README.md
@@ -2,7 +2,7 @@
 
 Container running [Jenkins](https://www.jenkins.io/).
 
-## Usage with docker-compose
+## Usage with docker
 
 See [github.com - mborne/docker-jenkins](https://github.com/mborne/docker-jenkins#docker-jenkins)
 

diff --git a/keycloak/README.md b/keycloak/README.md
@@ -1,10 +1,10 @@
-# [Keycloak](https://www.keycloak.org/)
+# Keycloak
 
-## Usage
+Container running [Keycloak](https://www.keycloak.org/).
 
-* Start [postgis](../postgis/README.md) and `createdb keycloak`
+## Usage
 
-* Start keycloak : `KEYCLOAK_ADMIN_PASSWORD=ChangeIt docker compose up -d`
+* Start keycloak stack : `KEYCLOAK_ADMIN_PASSWORD=ChangeIt docker compose up -d`
 
 * Open http://keycloak.dev.localhost
 

diff --git a/kibana/README.md b/kibana/README.md
@@ -1,8 +1,8 @@
 # Kibana
 
-Docker container running [Kibana](https://www.elastic.co/kibana/) as a single node for dev purpose.
+Container running  [Kibana](https://www.elastic.co/kibana/) for **DEV purpose**.
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start kibana : `docker-compose up -d`
 * Open https://kibana.dev.localhost
diff --git a/kubernetes-dashboard/README.md b/kubernetes-dashboard/README.md
@@ -20,7 +20,7 @@ kubectl -n kubernetes-dashboard get secret \
 * Start `kubectl proxy`
 * Open http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/
 
-## Reference
+## Resources
 
 * [kubernetes.io - Tableau de bord (Dashboard)](https://kubernetes.io/fr/docs/tasks/access-application-cluster/web-ui-dashboard/)
 * [github.com - kubernetes/dashboard](https://github.com/kubernetes/dashboard/)
diff --git a/longhorn/README.md b/longhorn/README.md
@@ -1,11 +1,9 @@
 # Longhorn
 
-[Longhorn](https://longhorn.io/) is a cloud native distributed block storage for Kubernetes :
-
+Container runner [Longhorn](https://longhorn.io/) which is a cloud native distributed block storage for Kubernetes :
 
 ![Longhorn nodes](img/longhorn-nodes.png)
 
-
 ## System requirements
 
 ```bash

diff --git a/mailer/README.md b/mailer/README.md
@@ -1,11 +1,18 @@
 # mailer
 
-STMP relay based on [namshi/smtp](https://hub.docker.com/r/namshi/smtp) image.
+Container running [namshi/smtp](https://hub.docker.com/r/namshi/smtp) which is a STMP relay.
 
-## Usage with docker-compose
+> **Warning:** See [namshi/smtp -tags](https://hub.docker.com/r/namshi/smtp/tags) currently displaying **Last pushed 3 years ago by namshi**.
 
-* 1) Create `config.env` file (see [config.env.dist](config.env.dist) or [namshi/smtp on dockerhub](https://hub.docker.com/r/namshi/smtp) )
-* 2) Start container : `docker-compose up -d`
+## Usage with docker
+
+* Create `config.env` file to provide `GMAIL_USER` and `GMAIL_PASSWORD`
+
+> See [config.env.dist](config.env.dist) or [namshi/smtp on dockerhub](https://hub.docker.com/r/namshi/smtp)
+
+* Start container : `docker-compose up -d`
+
+* Configure other tools to use `mailer:25` to send mails.
 
 ## Testing
 

diff --git a/mailhog/README.md b/mailhog/README.md
@@ -1,8 +1,8 @@
-# [MailHog](https://github.com/mailhog/MailHog#readme)
+# MailHog
 
-Docker container running mailhog to test email sending from application
+Container running running [MailHog](https://github.com/mailhog/MailHog#readme) to test email sending from applications.
 
-## Usage
+## Usage with docker
 
 * Start postgis : `docker-compose up -d`
 
@@ -20,6 +20,6 @@ this is a test email
 quit
 ```
 
-* Open http://mailhog.localhost or http://mailhog.localhost/api/v2/messages
+* Open http://mailhog.dev.localhost or http://mailhog.dev.localhost/api/v2/messages
 
 ![Test email](doc/test-email.png)
diff --git a/minio/README.md b/minio/README.md
@@ -2,7 +2,7 @@
 
 Container running [MinIO](https://min.io/) offering S3 compatible object storage.
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start containers : `MINIO_ROOT_PASSWORD=ChangeIt docker compose up -d`
 * Open https://minio.dev.localhost/

diff --git a/netdata/README.md b/netdata/README.md
@@ -2,7 +2,7 @@
 
 Container running [netdata/netdata](https://hub.docker.com/r/netdata/netdata) image.
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start instance : `NETDATA_NAME=${HOSTNAME} docker-compose up -d`
 * Open https://netdata.dev.localhost or http://localhost:19999

diff --git a/nextcloud/README.md b/nextcloud/README.md
@@ -1,10 +1,8 @@
 # Nextcloud
 
-## Description
-
 Container running [nextcloud](https://hub.docker.com/_/nextcloud) official image.
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start nextcloud : `docker-compose up -d`
 

diff --git a/nexus/README.md b/nexus/README.md
@@ -1,14 +1,12 @@
 # Nexus
 
-## Description
+Containers running [sonatype/nexus3](https://hub.docker.com/r/sonatype/nexus3/).
 
-Containers running [sonatype/nexus3](https://hub.docker.com/r/sonatype/nexus3/)
-
-## Usage with docker-compose
+## Usage with docker
 
 * Start nexus : `docker-compose up -d`
 
-* Retreive initial admin password : `docker exec -ti nexus cat /nexus-data/admin.password`
+* Retrieve initial admin password : `docker exec -ti nexus cat /nexus-data/admin.password`
 
 * Open nexus : https://nexus.dev.localhost/
 
@@ -33,5 +31,3 @@ docker push registry.dev.localhost/hello-world:latest
 
 Check https://registry.dev.localhost/v2/_catalog and https://registry.dev.localhost/v2/hello-world/tags/list
 
-
-
diff --git a/openldap/README.md b/openldap/README.md
@@ -1,7 +1,5 @@
 # [OpenLDAP](https://www.openldap.org/)
 
-## Description
-
 Containers running [osixia/openldap](https://github.com/osixia/docker-openldap#osixiaopenldap) and [osixia/docker-phpLDAPadmin](https://github.com/osixia/docker-phpLDAPadmin).
 
 ## Usage

diff --git a/opensearch/README.md b/opensearch/README.md
@@ -6,7 +6,7 @@ Containers running [OpenSearch](https://opensearch.org/) for **DEV purpose**.
 
 * [max_map_count >= 262144](../docs/max_map_count.md)
 
-## Usage with docker-compose
+## Usage with docker
 
 WARNING : Read [docker-compose.yml](docker-compose.yml) and note that **security is disabled**!
 

diff --git a/postgis/README.md b/postgis/README.md
@@ -1,8 +1,8 @@
 # PostGIS
 
-Container running [postgis](https://registry.hub.docker.com/r/postgis/postgis/).
+Container running [PostgreSQL with the spatial extension PostGIS](https://registry.hub.docker.com/r/postgis/postgis/).
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start postgis :
 

diff --git a/sonarqube/README.md b/sonarqube/README.md
@@ -1,8 +1,8 @@
 # SonarQube
 
-Container running [SonarQube](https://www.sonarqube.org/) official image.
+Container running [SonarQube](https://www.sonarqube.org/).
 
-## Usage with docker-compose
+## Usage with docker
 
 * Start : `docker-compose up -d`
 * Open https://sonarqube.dev.localhost

diff --git a/traefik/README.md b/traefik/README.md
@@ -2,9 +2,7 @@
 
 Container running [traefik proxy](https://doc.traefik.io/traefik/).
 
-## Usage with docker-compose
-
-### Getting started
+## Usage with docker
 
 * Build [mborne/traefik-dev](img/traefik-dev/README.md) image : `docker compose build --pull`
 * Start traefik : `docker compose up -d`