Merge pull request #1073 from SUSE/tomcat_readme

Convert tomcat readme into a Jinja2 template

src/bci_build/package/__init__.py

@@ -960,6 +960,15 @@ def reference(self) -> str:
         """
         pass
 
+    @property
+    def pretty_reference(self) -> str:
+        """
+        Returns the human readable pretty URL to this image. Used in image documentation.
+        """
+        return (
+            f"{self.registry}/{self._registry_prefix}/{self.name}:{self.version_label}"
+        )
+
     @property
     def description(self) -> str:
         """The description of this image which is inserted into the

src/bci_build/package/appcontainers.py

@@ -721,93 +721,6 @@ def _get_nginx_kwargs(os_version: OsVersion):
 """,
         entrypoint_user="tomcat",
         logo_url="https://tomcat.apache.org/res/images/tomcat.png",
-        extra_files={
-            "README.md": rf"""# Tomcat {tomcat_major} Container Image
-​
-Apache Tomcat (Tomcat for short) is a free and open-source implementation of the
-Jakarta Servlet, Jakarta Expression Language, and WebSocket technologies. It
-provides a pure Java HTTP web server environment that can run Java code. It is a
-Java web application server and not a complete JEE application server.
-​
-​
-## How to use the image
-​
-By default, the image launches Tomcat with the same configuration as the one
-that comes with SUSE Linux Enterprise Server. The difference is that logging is
-sent to stdout, meaning that the `podman logs tomcat` command displays Tomcat
-logs.
-​
-For security reasons, the image runs as the **tomcat** user. This means that
-additional packages cannot be installed via `zypper`, unless the user becomes
-`root`.
-​
-To deploy an application, copy the `.war` file file into
-`$CATALINA_BASE/webapps` (either during a container build or by bind-mounting
-the directory), and launch the container using the following command:
-```ShellSession
-$ podman run -d --rm -p 8080:8080 registry.suse.com/suse/tomcat:{tomcat_major}
-```
-​
-The deployed webapp is then accessible via `http://localhost:8080/$webapp_name`.
-​
-
-### How to use the image with rootless Podman
-
-The container image can be used in rootless mode with Podman. Keep in mind that
-Podman remaps the `tomcat` user in the container to a different user on the
-host. This user will not have write access to the mounted directory. To avoid
-permission issues change permissions of the shared directory to `0777` as
-follows:
-
-```ShellSession
-$ chmod 0777 /path/to/my/app
-$ podman run --rm -d -v /path/to/my/app:{_CATALINA_HOME}/webapps:z \
-      -p 8080:8080 registry.suse.com/suse/tomcat:{tomcat_major}
-```
-​
-
-## Configuration
-​
-The main Tomcat configuration files (for example
-`/etc/tomcat/logging.properties`) are stored in `/etc/tomcat/`.
-​
-Tomcat's runtime options can be configured using the environment variables
-`JAVA_OPTS` and `CATALINA_OPTS`. `JAVA_OPTS` specifies general options used for
-the JVM, whereas `CATALINA_OPTS` specifies Tomcat's flags. You can pass the
-options to the container runtime using the `-e` flag:
-```ShellSession
-$ podman run -it --rm \
-      -e JAVA_OPTS="-Xmx1024m" \
-      -p 8080:8080 \
-      registry.suse.com/suse/tomcat:{tomcat_major}
-```
-​
-The image ships with `CATALINA_HOME` set to `{_CATALINA_HOME}` and `CATALINA_BASE` set to
-`{_CATALINA_HOME}`.
-​
-​
-## Samples
-​
-By default, the sample applications shipped with Tomcat are not installed in
-the container image. You can obtain them by installing one of the following
-packages:
-- {tomcat_pkg}-webapps
-- {tomcat_pkg}-admin-webapps
-- {tomcat_pkg}-docs-webapp
-"""
-            + (
-                f"""
-
-## Upgrading from Tomcat 9
-​
-Tomcat 9 implements Java EE 8, and Tomcat {tomcat_major} implements Jakarta
-EE 9. Before upgrading from version 9, consult the upstream migration guide:
-https://tomcat.apache.org/migration-10.html
-"""
-                if tomcat_major > 9
-                else ""
-            )
-        },
     )
     for tomcat_major, os_version in product(_TOMCAT_VERSIONS, ALL_BASE_OS_VERSIONS)
 ]

src/bci_build/package/tomcat/README.md.j2

@@ -0,0 +1,81 @@
+# Tomcat {{ image.version }} Container Image
+
+Apache Tomcat (Tomcat for short) is a free and open-source implementation of the
+Jakarta Servlet, Jakarta Expression Language, and WebSocket technologies. It
+provides a pure Java HTTP web server environment that can run Java code. It is a
+Java web application server and not a complete JEE application server.
+
+
+## How to use the image
+
+By default, the image launches Tomcat with the same configuration as the one
+that comes with SUSE Linux Enterprise Server. The difference is that logging is
+sent to stdout, meaning that the `podman logs tomcat` command displays Tomcat
+logs.
+
+For security reasons, the image runs as the **tomcat** user. This means that
+additional packages cannot be installed via `zypper`, unless the user becomes
+`root`.
+
+To deploy an application, copy the `.war` file file into
+`$CATALINA_BASE/webapps` (either during a container build or by bind-mounting
+the directory), and launch the container using the following command:
+```ShellSession
+$ podman run -d --rm -p 8080:8080 {{ image.pretty_reference }}
+```
+
+The deployed webapp is then accessible via `http://localhost:8080/$webapp_name`.
+
+
+### How to use the image with rootless Podman
+
+The container image can be used in rootless mode with Podman. Keep in mind that
+Podman remaps the `tomcat` user in the container to a different user on the
+host. This user will not have write access to the mounted directory. To avoid
+permission issues change permissions of the shared directory to `0777` as
+follows:
+
+```ShellSession
+$ chmod 0777 /path/to/my/app
+$ podman run --rm -d -v /path/to/my/app:{{ image.env['CATALINA_HOME'] }}/webapps:z \
+      -p 8080:8080 {{ image.pretty_reference }}
+```
+
+
+## Configuration
+
+The main Tomcat configuration files (for example
+`/etc/tomcat/logging.properties`) are stored in `/etc/tomcat/`.
+
+Tomcat's runtime options can be configured using the environment variables
+`JAVA_OPTS` and `CATALINA_OPTS`. `JAVA_OPTS` specifies general options used for
+the JVM, whereas `CATALINA_OPTS` specifies Tomcat's flags. You can pass the
+options to the container runtime using the `-e` flag:
+```ShellSession
+$ podman run -it --rm \
+      -e JAVA_OPTS="-Xmx1024m" -p 8080:8080 \
+      {{ image.pretty_reference }}
+```
+
+The image ships with `CATALINA_HOME` set to `{{ image.env['CATALINA_HOME'] }}`
+and `CATALINA_BASE` set to `{{ image.env['CATALINA_BASE'] }}`.
+
+
+## Samples
+
+By default, the sample applications shipped with Tomcat are not installed in
+the container image. Add them by installing one of the following
+packages:
+- {{ image.package_list[0] }}-webapps
+- {{ image.package_list[0] }}-admin-webapps
+- {{ image.package_list[0] }}-docs-webapp
+
+{% if image.env['TOMCAT_MAJOR'] > 9 -%}
+## Upgrading from Tomcat 9
+
+Tomcat 9 implements Java EE 8, and Tomcat {{ image.env['TOMCAT_MAJOR'] }}
+implements Jakarta EE 9. Before upgrading from version 9, consult the
+[upstream migration guide](https://tomcat.apache.org/migration-{{ image.env['TOMCAT_MAJOR'] }}.html).
+{%- endif %}
+
+{% include 'licensing_and_eula.j2' %}