Merge ~ubuntu-docker-images/ubuntu-docker-images/+git/apache2:improve-template into ~ubuntu-docker-images/ubuntu-docker-images/+git/apache2:edge

[Sergio Durigan Junior]

Start improving the template mechanism. This is a WIP.

[Sergio Durigan Junior (sergiodj)]

This is now ready for review. The commit message explains it all.

[Sergio Durigan Junior (sergiodj)]

FWIW, this will be affected by Valentin's MP 394365.

[Lucas Kanashiro (lucaskanashiro)]

Thank you for those changes Sergio!

I was thinking if it would not be better if we do not commit the templates directory and add it to the .gitignore. Otherwise we will need to keep adding commits just updating templates. What do you think? Then we would have the expected content in all git repos but all the template files will be committed only in the templates git repo.

Besides that it LGTM. However, as you mentioned, let's first merge Valentin's MP and adapt this one to match his changes.

review: Needs Fixing

[Sergio Durigan Junior (sergiodj)]

Thanks for the review, Lucas. I've updated everything according to Valentin's MP, and also tweaked the Makefile a bit more. I'd appreciate if you could take a second look. Thanks!

[Lucas Kanashiro (lucaskanashiro)]

LGTM, +1.

review: Approve

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2a4e9c0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+templates/README.md
+templates/channels_message.md
+templates/common_usage.md
+templates/header.md
diff --git a/HACKING.md b/HACKING.md
index d929d68..cfa9b96 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -21,3 +21,31 @@ $ docker build -t ubuntu/apache2:test .
   you can also check the README.md file.
 
 * If everything goes well submit a merge proposal.
+
+# Generating the documentation
+
+The documentation (`README.md` and some files in the `examples/`
+directory) are generated using templates.  In order to do that, you
+need to follow some steps.
+
+```
+$ pwd
+~/work/apache2
+$ cd ..
+$ git clone https://github.com/misterw97/RenderDown
+$ cd apache2
+$ make all-doc
+```
+
+If you already have the `RenderDown` repository cloned somewhere else,
+you can tell `make` about it:
+
+```
+$ RENDERDOWN=/path/to/renderdown.py make all-doc
+```
+
+# Hacking the documentation templates
+
+You can find some of the templates used to generated the documentation
+inside the `templates/` directory.  You can also look at the `data/`
+directory for the files used to feed the templates.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..6a49a17
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,31 @@
+RENDERDOWN ?= ../RenderDown/renderdown.py
+PYTHON ?= python3
+
+README_TEMPLATE = templates/README_DOCKERHUB.md
+
+TEMPLATE_FILES = $(README_TEMPLATE) \
+	templates/channels_message.md \
+	templates/common_usage.md \
+	templates/header.md
+
+all: all-doc
+
+all-doc: clean-doc readme examples
+
+templates/%.md:
+	wget -nv https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/templates/plain/$@ -O $@
+
+readme: $(TEMPLATE_FILES)
+	mv -v $(README_TEMPLATE) templates/README.md
+	$(PYTHON) $(RENDERDOWN) templates/README.md > README.md
+
+examples:
+	$(PYTHON) $(RENDERDOWN) templates/apache2-deployment.yml > examples/apache2-deployment.yml
+	$(PYTHON) $(RENDERDOWN) templates/docker-compose.yml > examples/docker-compose.yml
+
+clean: clean-doc
+
+clean-doc:
+	rm -fv $(TEMPLATE_FILES) README.md examples/apache2-deployment.yml examples/docker-compose.yml
+
+.PHONY: examples readme clean clean-doc all all-doc
diff --git a/README.md b/README.md
index 495cd2f..2d96fd9 100644
--- a/README.md
+++ b/README.md
@@ -1,141 +1,89 @@
 # Apache2 | Ubuntu
 
+Current Apache2 Docker Image from Ubuntu. Receives security updates and rolls to newer Apache2 or Ubuntu LTS. This repository is exempted from per-user rate limits. For [LTS Docker Image](https://ubuntu.com/security/docker-images) versions of this image, see `lts/apache2`. 
+
+
 ## About Apache2
 
 The Apache HTTP Server Project's goal is to build a secure, efficient and extensible HTTP server as standards-compliant open source software. The result has long been the number one web server on the Internet. Read more on the [apache2 website](https://httpd.apache.org/).
 
-## Tags
 
-* `2.4.41-focal`, `2.4.41`, `2.4-focal`, `2.4`, `2-focal`, `2`, `focal`, `beta` - **/!\ this is a beta release**
+## Tags and Architectures
+![LTS](https://assets.ubuntu.com/v1/0a5ff561-LTS%402x.png?h=17)
+Up to 5 years free security maintenance `from lts/apache2`.
+
+![ESM](https://assets.ubuntu.com/v1/572f3fbd-ESM%402x.png?h=17)
+Up to 10 years customer security maintenance `from store/canonical/apache2`.
 
-## Architectures supported
+_Tags in italics are not available in ubuntu/apache2 but are shown here for completeness._
+
+| Channel Tag | | | Currently | Architectures |
+|---|---|---|---|---|
+| **`2.4-20.04_beta`**    | | | Apache2 2.4.41 on Ubuntu 20.04 LTS | `amd64`, `arm64`, `ppc64el`, `s390x` |
+| _`track_risk`_ |
+
+Channel tag shows the most stable channel for that track ordered `stable`, `candidate`, `beta`, `edge`. More risky channels are always implicitly available. So if `beta` is listed, you can also pull `edge`. If `candidate` is listed, you can pull `beta` and `edge`. When `stable` is listed, all four are available. Images are guaranteed to progress through the sequence `edge`, `beta`, `candidate` before `stable`.
 
-* `amd64`, `arm64`, `ppc64el`, `s390x`
 
 ## Usage
 
-### Docker CLI
+Launch this image locally:
 
+```sh
+docker run -d --name apache2-container -e TZ=UTC -p 8080:80 ubuntu/apache2:2.4-20.04_beta
 ```
-$ docker run -d --name apache2 -p 8080:80 -e TZ=UTC ubuntu/apache2:edge
-```
-
-You can now point your browser to http://localhost:8080/ and verify that it works.
+Access your Apache2 server at `http://localhost:8080`.
 
 #### Parameters
 
 | Parameter | Description |
 |---|---|
 | `-e TZ=UTC` | Timezone. |
+| `-p 8080:80` | Expose Apache2 on `localhost:8080`. |
 | `-v /local/path/to/website:/var/www/html` | Mount and serve a local website. |
-| `-p 8080:80` | Expose apache2 on `localhost:8080`. |
-| `-v /my/config/apache2.conf:/etc/apache2/apache2.conf` | Mount a local configuration `apache2.conf` (download this [example file](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/apache2.conf)). |
-| `-v /local/path/to/website.conf:/etc/apache2/sites-enabled/website.conf` | Mount and serve a local website, usually as a `VirtualHost`. |
+| `-v /path/to/apache2.conf:/etc/apache2/apache2.conf` | Local [configuration file](https://httpd.apache.org/docs/2.4/) `apache2.conf` (try [this example](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/apache2.conf)). |
+
 
 #### Testing/Debugging
 
-In case you need to debug what is happening with the container you can run `docker logs <name_of_the_container>`. To get access to an interactive shell run:
+To debug the container:
 
+```sh
+docker logs -f apache2-container
 ```
-$ docker exec -it <name_of_the_container> /bin/bash
-```
-
-### Deploy with Kubernetes
 
-You can use your favorite Kubernetes distribution; if you don't have one, consider [installing MicroK8s](https://microk8s.io/).
-
-With microk8s running, enable the `dns` and `storage` add-ons:
+To get an interactive shell:
 
 ```sh
-$ microk8s enable dns storage
+docker exec -it apache2-container /bin/bash
 ```
 
-```sh
-$ microk8s kubectl create configmap apache2-config --from-file=apache2=config/apache2.conf
-```
 
-Use the sample deployment yaml provided [here](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/apache2-deployment.yml).  You will also need to download the contents of the `html` directory [here](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/html)
-
-<details>
-  <summary>Apply the `apache2-deployment.yml` (click to expand)</summary>
-
-```yaml
-# apache2-deployment.yml
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: apache2-deployment
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: apache2
-  template:
-    metadata:
-      labels:
-        app: apache2
-    spec:
-      containers:
-      - name: apache2
-        image: ubuntu/apache2:edge
-        volumeMounts:
-        - name: apache2-config-volume
-          mountPath: /etc/apache2/apache2.conf
-          subPath: apache2.conf
-        - name: apache2-config-volume
-          mountPath: /srv/www/index.html
-          subPath: index.html
-        ports:
-        - containerPort: 80
-          name: apache2
-          protocol: TCP
-      volumes:
-        - name: apache2-config-volume
-          configMap:
-            name: apache2-config
-            items:
-            - key: apache2
-              path: apache2.conf
-            - key: apache2-site
-              path: index.html
----
-apiVersion: v1
-kind: Service
-metadata:
-  name: apache2-service
-spec:
-  type: NodePort
-  selector:
-    app: apache2
-  ports:
-  - protocol: TCP
-    port: 80
-    targetPort: 80
-    nodePort: 30080
-    name: apache
-```
-</details>
+## Deploy with Kubernetes
 
-```
-$ microk8s kubectl apply -f apache2-deployment.yml
-```
+Works with any Kubernetes; if you don't have one, we recommend you [install MicroK8s](https://microk8s.io/) and `microk8s.enable dns storage` then `snap alias microk8s.kubectl kubectl`.
 
-You will now be able to connect to the Apache server on `localhost:30080`.
+Download
+[apache2.conf](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/apache2.conf), [index.html](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/html/index.html) and
+[apache2-deployment.yml](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/apache2-deployment.yml) and set `containers.apache2.image` in `apache2-deployment.yml` to your chosen channel tag (e.g. `ubuntu/apache2:2.4-20.04_beta`), then:
 
-## Bugs and Features request
+```sh
+kubectl create configmap apache2-config --from-file=apache2=apache2.conf --from-file=apache2-site=index.html
+kubectl apply -f apache2-deployment.yml
+```
+
+You will now be able to connect to the apache2 server on `http://localhost:30080`.
 
-If you find a bug in our image or want to request a specific feature file a bug here:
+## Bugs and feature requests
 
-https://bugs.launchpad.net/ubuntu-docker-images/+filebug
+If you find a bug in our image or want to request a specific feature, please file a bug here:
 
-In the title of the bug add `apache2: <reason>`.
+[https://bugs.launchpad.net/ubuntu-docker-images/+filebug](https://bugs.launchpad.net/ubuntu-docker-images/+filebug)
 
-Make sure to include:
+Please title the bug "`apache2: <issue summary>`". Make sure to include the digest of the image you are using, from:
 
-* The digest of the image you are using, you can find it using this command replacing `<tag>` with the one you used to run the image:
 ```sh
-$ docker images --no-trunc --quiet ubuntu/apache2:<tag>
+docker images --no-trunc --quiet ubuntu/apache2:<tag>
 ```
-* Reproduction steps for the deployment
-* If it is a feature request, please provide as much detail as possible
+
+
diff --git a/data/apache2.yaml b/data/apache2.yaml
new file mode 100644
index 0000000..e95c47f
--- /dev/null
+++ b/data/apache2.yaml
@@ -0,0 +1,43 @@
+application: Apache2
+main: true
+repo: apache2
+description: >
+  The Apache HTTP Server Project's goal is to build a secure, efficient and extensible HTTP server as standards-compliant open source software. The result has long been the number one web server on the Internet. Read more on the [apache2 website](https://httpd.apache.org/).
+version: 2.4.41
+base: Ubuntu 20.04 LTS
+architectures:
+  - amd64
+  - arm64
+  - ppc64el
+  - s390x
+docker:
+  parameters:
+    - -p 8080:80
+  access: Access your Apache2 server at `http://localhost:8080`.
+parameters:
+  - type: -e
+    value: TZ=UTC
+    description: Timezone.
+  - type: -p
+    value: 8080:80
+    description: Expose Apache2 on `localhost:8080`.
+  - type: -v
+    value: /local/path/to/website:/var/www/html
+    description: Mount and serve a local website.
+  - type: -v
+    value: /path/to/apache2.conf:/etc/apache2/apache2.conf
+    description: Local [configuration file](https://httpd.apache.org/docs/2.4/) `apache2.conf` (try [this example](https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/apache2.conf)).
+debug:
+  - nothing
+microk8s:
+  configmap:
+    files:
+      - key: apache2
+        name: apache2.conf
+        link: https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/apache2.conf
+      - key: apache2-site
+        name: index.html
+        link: https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/config/html/index.html
+  deploy:
+    link: https://git.launchpad.net/~canonical-server/ubuntu-docker-images/+git/apache2/plain/examples/apache2-deployment.yml
+    access: You will now be able to connect to the apache2 server on `http://localhost:30080`.
diff --git a/examples/apache2-deployment.yml b/examples/apache2-deployment.yml
index 6715f11..7f217a6 100644
--- a/examples/apache2-deployment.yml
+++ b/examples/apache2-deployment.yml
@@ -15,7 +15,7 @@ spec:
     spec:
       containers:
       - name: apache2
-        image: ubuntu/apache2:edge
+        image: ubuntu/apache2:latest
         volumeMounts:
         - name: apache2-config-volume
           mountPath: /etc/apache2/apache2.conf
@@ -51,3 +51,4 @@ spec:
     targetPort: 80
     nodePort: 30080
     name: apache
+
diff --git a/examples/docker-compose.yml b/examples/docker-compose.yml
index a27b6bc..24575c5 100644
--- a/examples/docker-compose.yml
+++ b/examples/docker-compose.yml
@@ -2,9 +2,10 @@ version: '2'
 
 services:
     apache2:
-        image: ubuntu/apache2:edge
+        image: ubuntu/apache2:latest
         ports:
             - 8080:80
         volumes:
             - ./config/apache2.conf:/etc/apache2/apache2.conf:ro
             - ./config/html:/srv/www:ro
+
diff --git a/templates/apache2-deployment.yml b/templates/apache2-deployment.yml
new file mode 100644
index 0000000..daa623d
--- /dev/null
+++ b/templates/apache2-deployment.yml
@@ -0,0 +1,56 @@
+<%
+    baserepo='ubuntu'
+%>\
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: apache2-deployment
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: apache2
+  template:
+    metadata:
+      labels:
+        app: apache2
+    spec:
+      containers:
+      - name: apache2
+        image: ${baserepo}/apache2:latest
+        volumeMounts:
+        - name: apache2-config-volume
+          mountPath: /etc/apache2/apache2.conf
+          subPath: apache2.conf
+        - name: apache2-config-volume
+          mountPath: /srv/www/index.html
+          subPath: index.html
+        ports:
+        - containerPort: 80
+          name: apache2
+          protocol: TCP
+      volumes:
+        - name: apache2-config-volume
+          configMap:
+            name: apache2-config
+            items:
+            - key: apache2
+              path: apache2.conf
+            - key: apache2-site
+              path: index.html
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: apache2-service
+spec:
+  type: NodePort
+  selector:
+    app: apache2
+  ports:
+  - protocol: TCP
+    port: 80
+    targetPort: 80
+    nodePort: 30080
+    name: apache
diff --git a/templates/docker-compose.yml b/templates/docker-compose.yml
new file mode 100644
index 0000000..6c5c92f
--- /dev/null
+++ b/templates/docker-compose.yml
@@ -0,0 +1,13 @@
+<%
+    baserepo='ubuntu'
+%>\
+version: '2'
+
+services:
+    apache2:
+        image: ${baserepo}/apache2:latest
+        ports:
+            - 8080:80
+        volumes:
+            - ./config/apache2.conf:/etc/apache2/apache2.conf:ro
+            - ./config/html:/srv/www:ro