cerberus237/adaptable-teastore-base repository overview

⁠Adaptable TeaStore Base Image Documentation

⁠1. Overview of the Component

⁠Description

The Adaptable TeaStore Base image serves as the foundational Docker image for all Adaptable TeaStore services. It includes essential environmental variable settings and a default context.xml configuration file for Tomcat. This image is intended to streamline the setup of the Tomcat web server in a production environment.

⁠Architecture

This base image is designed to be used by other service images within the Adaptable TeaStore ecosystem. It provides a standardized environment that ensures consistency across various services. By utilizing this base image, developers can easily create and manage multiple service configurations without duplicating setup tasks.

⁠Role in the Adaptable TeaStore

• Utility Image: Provides a baseline for building other Adaptable TeaStore Docker images.
• Tomcat Configuration: Sets up the Tomcat server with necessary configurations for optimal performance.
• Environmental Settings: Contains default environmental variables that can be overridden as needed.

⁠2. Helpful Docker Command

To create a custom image based on the Adaptable TeaStore Base image, you can use the following command in your Dockerfile:

FROM cerberus237/adaptable-teastore-base

⁠Explanation of Command:

• FROM cerberus237/adaptable-teastore-base: Specifies that your image will be built on top of the Adaptable TeaStore Base image.

⁠3. Sample Docker-Compose Code

Here’s a sample docker-compose.yml file to demonstrate how to use the Adaptable TeaStore Base image:

version: '3'
services:
  myservice:
    image: cerberus237/adaptable-teastore-base
    environment:
      SERVICE_PORT: 8080
      HOST_NAME: "myservice"

⁠Explanation of Directives:

• version: '3': Specifies the Docker Compose file format version.
• services: Defines the services to be run.
  • myservice: The name of the service.
    • image: Specifies the Docker image to use for the service.
    • environment: Sets environment variables needed for the service.

⁠4. Overview of the Dockerfile

The Dockerfile for the Adaptable TeaStore Base image is structured to configure the Tomcat server and set necessary parameters. Below is its content:

FROM tomcat:10.0.27-jdk11-temurin
LABEL org.opencontainers.image.authors="Inria R&D engineer <[email protected]>"

RUN rm /usr/local/tomcat/lib/websocket-api.jar
RUN rm /usr/local/tomcat/lib/tomcat-websocket.jar

# Copy config, database connector library and script for environment variables into container
COPY baseContext.xml /usr/local/tomcat/conf/context.xml
COPY mysql-connector-java-5.1.44-bin.jar /usr/local/tomcat/lib/mysql-connector-java-5.1.44-bin.jar
COPY target/jars/dockermemoryconfigurator* /usr/local/tomcat/bin/dockermemoryconfigurator.jar
RUN rm /usr/local/tomcat/conf/server.xml
COPY server.xml /usr/local/tomcat/conf/
COPY ssl/ /usr/local/tomcat/ssl


# Service configuration. SERVICE_PORT is the host port, mapped to the exposed docker port. HOST_NAME
# is the IP address or hostname of the host running the docker container
ENV SERVICE_PORT 8080
ENV HOST_NAME unset
ENV USE_POD_IP false
ENV REGISTRY_HOST 127.0.0.1
ENV REGISTRY_PORT 8080
ENV DB_HOST 127.0.0.1
ENV DB_PORT 3306
ENV RECOMMENDER_RETRAIN_LOOP_TIME 0
ENV RECOMMENDER_ALGORITHM SlopeOne
ENV PROXY_NAME unset
ENV PROXY_PORT unset
ENV TOMCAT_HEAP_MEM_PERCENTAGE 50
ENV LOG_TO_FILE false
ENV RABBITMQ_HOST unset
ENV USE_HTTPS false

# Copy script to replace placeholders in context.xml with the environment variables
COPY start.sh /usr/local/tomcat/bin/start.sh
RUN chmod +x /usr/local/tomcat/bin/start.sh

# Setting secure random number generation to urandom. This increases the startup speed.
# Environment variable no longer needed. Replaced by sed in start.sh
# ENV JAVA_OPTS $JAVA_OPTS -Dsecurerandom.source=file 837:/dev/urandom

RUN mkdir -p /kieker/logs
# Import self-signed certificate for HTTPS teastore into keystore. NOTE: to adapt certificate hostnames, configure and run ssl/generate_cert.sh and rebuild the container!
RUN keytool -import -noprompt -trustcacerts -alias teastoressl -file /usr/local/tomcat/ssl/cert.pem -keystore "/opt/java/openjdk/lib/security/cacerts" -storepass changeit

COPY kieker.monitoring.properties 							/kieker/config/kieker.monitoring.properties
COPY aop.xml 												            /usr/local/tomcat/lib/aop.xml
COPY kieker-2.0.0-aspectj.jar 					/kieker/agent/agent.jar
COPY slf4j-simple-2.0.0.jar 					/usr/local/slf4j-simple-2.0.0.jar

EXPOSE 8080

# Fix for tomcat + java 10+ (see: https://jira.atlassian.com/browse/BAM-20428)
RUN sed -i "/JDK_JAVA_OPTIONS.*/d" /usr/local/tomcat/bin/catalina.sh

CMD java -jar /usr/local/tomcat/bin/dockermemoryconfigurator.jar ${TOMCAT_HEAP_MEM_PERCENTAGE}; /usr/local/tomcat/bin/start.sh && /usr/local/tomcat/bin/catalina.sh run

⁠Explanation of Dockerfile Components:

• Base Image: Uses Tomcat 10.0.27 with JDK 11 as the foundation.
• Configuration Files: Copies necessary configuration files and libraries into the container.
• Environmental Variables: Sets default values for service configuration.
• Startup Command: Specifies the command to run Tomcat with the memory configurator.

⁠5. Configuration Files

⁠5.1 baseContext.xml

The baseContext.xml file defines the context configuration for the Tomcat server. It specifies how the web application interacts with the server and includes environment variables for service configuration.

⁠Detailed Purpose:

• Environment Variables: Contains placeholders for critical settings such as servicePort, hostName, and databaseHost, allowing these values to be dynamically set during container initialization.
• Service Registration: Configures context parameters required for service registration and communication within the ecosystem.
• Performance: Includes settings like disabling session persistence to improve startup times and manage resources more efficiently.

⁠5.2 server.xml

The server.xml file is the main configuration file for the Tomcat server. It defines server-level settings, including connectors for HTTP and AJP protocols.

⁠Detailed Purpose:

• Connector Configuration: Specifies how the server handles incoming requests, including ports and protocols for HTTP and AJP.
• Resource Management: Sets up global resources, such as user databases, which can be accessed by applications deployed on the server.
• Security Settings: Configures secure connections and SSL settings for HTTPS, ensuring that data transmitted over the network is encrypted.

⁠5.3 start.sh

The start.sh script is responsible for initializing the Tomcat server with the correct environment variable configurations.

⁠Detailed Purpose:

• Placeholder Replacement: Uses sed to replace placeholders in context.xml with actual environment variable values, ensuring that the application is configured correctly for its environment.
• HTTPS Configuration: Modifies the server configuration based on whether HTTPS is enabled, allowing for secure communications.
• Dynamic Configuration: Handles various settings dynamically, such as database host and port, recommender settings, and logging preferences.

⁠5.4 kieker.monitoring.properties

The kieker.monitoring.properties file configures the Kieker monitoring framework, which is used for performance monitoring and logging in the application.

⁠Detailed Purpose:

• Monitoring Configuration: Specifies settings for monitoring, including the name of the Kieker instance, logging options, and data collection preferences.
• Writer Configuration: Defines the output method for monitoring data, such as file system or AMQP (Advanced Message Queuing Protocol).
• Performance Metrics: Configures timers and other settings to collect performance metrics effectively, enabling performance analysis and optimization.

⁠5.5 aop.xml

The aop.xml file is used for Aspect-Oriented Programming (AOP) with AspectJ, allowing the application to apply cross-cutting concerns like logging and monitoring.

⁠Detailed Purpose:

• Aspect Management: Defines aspects that intercept method calls for monitoring purposes, enhancing observability without modifying business logic.
• Pointcut Definitions: Specifies which methods or classes to monitor, allowing developers to exclude certain packages or methods from monitoring to reduce overhead.
• Dynamic Weaving: Facilitates the dynamic application of aspects at runtime, enabling flexible and modular configuration of cross-cutting concerns.

⁠6. Adaptation Actions and Collectors

The Adaptable TeaStore Base image does not implement any adaptation actions or collectors, as it serves as a utility image focused solely on setting up the Tomcat web server.

⁠7. Summary

The Adaptable TeaStore Base image is essential for establishing a consistent environment for all Adaptable TeaStore services. It simplifies the process of creating service images while ensuring that the Tomcat server is configured correctly for production use. The configuration files play a critical role in customizing the server and application behavior. For further details, refer to the Getting Started documentation⁠.