Skip to content

Environment parameters

/apps/conf/runtime.cfg

/apps/opt/activemq/conf/activemq.xml

/apps/opt/activemq/bin/env

/apps/setup/setup.sh

Comprehensive Functional Description: Tomcat Configuration Blueprint

This Markdown document serves as a comprehensive, declarative configuration file for a Tomcat application server instance, specifically defining the operational parameters for the "standard" Tomcat profile. It is meticulously structured to be both easily human-readable and robustly parseable by automated systems (e.g., shell scripts, configuration management tools, deployment pipelines) to ensure consistent, reproducible, and efficient setup of Tomcat environments.

Core Purpose:

The primary function of this .md file is to act as the single source of truth for the Tomcat server's runtime environment, defining its resource allocation, network exposure, security settings, and, most critically, its persistent connections to backend database systems. It enables automated deployments by centralizing all configuration parameters in a clear, version-controllable format.

Structure and Format:

The configuration is organized hierarchically using key-value pairs. Inline comments (//) provide contextual explanations for individual parameters and blocks, enhancing readability and maintainability.

Detailed Breakdown of Configuration Sections:

1. Tomcat Instance Identification (tomcat.standard block)

  • tomcat { standard { ... } }: This top-level block defines a specific configuration profile named "standard". This nomenclature suggests the potential for managing multiple distinct Tomcat configurations (e.g., "standard", "lightweight", "heavy-duty") within a larger configuration management system, allowing for flexible deployment scenarios.

2. JVM Resource Management & Performance Tuning

This section dictates how the Java Virtual Machine (JVM) that runs Tomcat will consume system resources, directly impacting application performance, stability, and capacity.

  • maxHeap / minHeap: (4096m, 512m)
    • maxHeap: Specifies the maximum amount of memory the JVM can allocate for the Java heap. A larger heap allows for more objects in memory, reducing garbage collection frequency but consuming more RAM.
    • minHeap: Sets the initial amount of memory the JVM allocates for the heap. Starting with a larger initial heap can reduce initial garbage collection cycles but ties up memory immediately.
  • maxPermSize: (226m)
    • Purpose: (Primarily relevant for JVMs prior to Java 8, where it was replaced by Metaspace). Defines the maximum size of the Permanent Generation, an area of memory used to store class metadata, interned strings, and other static data. Setting this correctly helps prevent OutOfMemoryError: PermGen space in older environments.
  • maxHttpHeaderSize: (8192)
    • Purpose: Limits the maximum size in bytes of HTTP request and response headers. This prevents potential denial-of-service attacks using extremely large headers and ensures compatibility with various client/server configurations.

3. JMX Monitoring & Management

This section controls Java Management Extensions (JMX), which allows for external monitoring, management, and control of the running Tomcat instance.

  • usejmx: (false)
    • Purpose: A boolean flag that globally enables or disables JMX functionality for the Tomcat server. When true, it allows external tools to connect and monitor JVM metrics, thread usage, memory, etc.
  • jmxremote block: (e.g., ip="localhost", port=10999, ssl=false)
    • Purpose: If usejmx is true, this sub-block specifies the configuration for remote JMX access, including the IP address to bind to, the listener port, and whether SSL encryption is required for the connection.

4. Network Connectivity & Ports

This section defines how the Tomcat server will listen for and respond to network requests, enabling communication with web browsers, other applications, and proxies.

  • port block: This sub-block centralizes all network port definitions:
    • shutdown: (8005) The port used to send a command to gracefully shut down the Tomcat instance. This should typically be configured to accept connections only from localhost for security.
    • web: (8080) The primary HTTP connector port, used for standard unencrypted web traffic.
    • webRedirect: (8443, optional) Specifies the port to which HTTP requests should be redirected, typically used to redirect HTTP (8080) traffic to HTTPS (8443) for secure communication.
    • ajp: (8009) The Apache JServ Protocol (AJP) connector port, commonly used when Tomcat is integrated with and fronted by a web server like Apache HTTP Server or Nginx. AJP is a binary protocol more efficient than HTTP for this proxying scenario.
    • ajpRedirect: (8443, optional) Similar to webRedirect, but for AJP connections, redirecting to a secure port.
    • ssl: (8443, optional) The HTTPS connector port. The SSL HTTP connector will only be configured if this value is set, and typically requires additional SSL certificate configuration outside of this file.
  • connector.http.address: (optional)
    • Purpose: For servers with multiple IP addresses, this attribute specifies which particular address the HTTP connector will bind to. If not set, it binds to all available interfaces.
  • connector.http.maxThreads: (optional)
    • Purpose: Defines the maximum number of simultaneous request processing threads that the HTTP connector can create. Increasing this allows the server to handle more concurrent requests but consumes more system resources.

5. Application Environment & System Metadata

This section provides contextual information about the Tomcat instance's role, customer, and deployment environment, aiding in management, logging, and environment-specific behavior.

  • customer.code: ("lh")
    • Purpose: A unique identifier for the specific customer or client associated with this installation. Useful in multi-tenancy scenarios or for client-specific reporting.
  • company.type: ("airline")
    • Purpose: Categorizes the type of business or industry the customer operates in, potentially influencing business logic or specific application features.
  • environmentType: ("qcdev")
    • Purpose: Labels the type of deployment environment (e.g., qcdev for Quality Control Development, qctest, qcref, test, stage, prod, demo). This is crucial for distinguishing configurations, applying environment-specific policies, and managing software lifecycles.
  • qc.test: (true)
    • Purpose: A dedicated boolean flag explicitly indicating whether this instance is part of a quality control or test environment, allowing applications or scripts to react accordingly (e.g., enable debug logging, disable certain integrations).
  • LANG: (optional, e.g., "en_US.UTF-8")
    • Purpose: Sets the default language and encoding for the system where Tomcat is running. This ensures correct localization and character handling within the application and logs.

6. File System Paths & Locations

This section defines the crucial directory structures for the Tomcat installation, logs, and application deployments, relative to a presumed $APPS_HOME base directory.

  • tomcatHome.dir: ("opt/tomcat")
    • Purpose: Specifies the relative path to the root directory of the Tomcat installation.
  • log.dir: ("log/tomcat")
    • Purpose: Defines the relative path where Tomcat's server logs and potentially application-specific logs will be stored.
  • tomcatUsers.pathname: ("conf/tomcat-users.xml")
    • Purpose: Specifies the relative path to the XML file that contains user accounts, roles, and authentication information for Tomcat's internal security realm.
  • appBase: ("../../qcapps")
    • Purpose: Defines the relative path to the directory where web application (WAR) files are deployed. Tomcat scans this directory for applications to automatically deploy and manage.

7. Database Connectivity Strategy

This section sets the overall approach to database interaction for the Tomcat instance.

  • usejdbc: (true)
    • Purpose: A boolean flag to indicate whether standard JDBC (Java Database Connectivity) mechanisms will be used. If false, it implies an alternative data access strategy (e.g., JPA with a different provider) might be preferred, though for HSQL/MySQL the JDBC connection is implicit.
  • checkPassword: (true)
    • Purpose: Controls whether password authentication is enforced for database connections originating from Tomcat.
  • database.type: ("MySQL")
    • Purpose: Sets the default database management system (DBMS) type for this Tomcat instance (Oracle, HSQL, or MySQL). This global setting influences the expected parameters within the datasource definitions below and might trigger specific driver loading or connection logic.

8. Detailed Database Datasource Definitions (ds block)

This is the most granular and critical section, defining multiple JDBC connection pools that applications running on this Tomcat server will use to connect to various backend databases. Each named block within ds represents a distinct datasource.

  • Overall Purpose: Connection pools are vital for efficient database access, as they manage a set of pre-initialized and open connections to a database, reducing the overhead of opening and closing connections for every transaction and improving application performance and scalability.

  • Common Datasource Properties (for each named datasource like asgard, midgard, archiver):

    • name: (e.g., "jdbc/asgardDS") The JNDI (Java Naming and Directory Interface) name under which this datasource will be exposed to applications deployed on Tomcat. Applications look up the datasource using this name.
    • username: (e.g., "asglhdev") The database user account used to authenticate and establish connections to the database.
    • password: (e.g., "bettylh") The password associated with the specified database user.
    • dbType: (optional) Allows overriding the global database.type for a specific datasource if it needs to connect to a different type of database than the default.

  • Database-Specific Connection Parameters (examples provided for different DBMS types):

    • Oracle-Specific: (host, port, sid, or url)
      • Used to construct the JDBC connection URL for Oracle databases.
    • HSQL-Specific: (dbfile or url)
      • Used for HSQLDB, particularly for embedded file-based databases where dbfile points to the database file.
    • MySQL-Specific: (host, port, database, properties, or url)
      • host: The hostname or IP address of the MySQL server.
      • port: The listener port of the MySQL server (default 3306).
      • database: The specific database schema to connect to on the MySQL server.
      • properties: (e.g., "autoReconnect=true&serverTimezone=Europe/Berlin") A string of key-value pairs representing additional JDBC driver-specific connection properties. These are crucial for fine-tuning driver behavior, character sets, timezones, and other advanced options.

  • Connection Pool Tuning Parameters: These parameters are vital for optimizing the performance, resilience, and resource consumption of the connection pools.

    • minEvictableIdleTimeMillis: (e.g., 60000)
      • Purpose: The minimum amount of time (in milliseconds) a connection may sit idle in the pool before it becomes eligible for eviction by the idle connection evictor. Ensures old, unused connections are eventually closed.
    • timeBetweenEvictionRunsMillis: (e.g., 3000)
      • Purpose: The frequency (in milliseconds) at which the connection pool's internal thread runs to validate connections, evict idle ones, and reclaim abandoned ones. This dictates how quickly the pool reacts to changes in connection state.
    • numTestsPerEvictionRun: (e.g., 3)
      • Purpose: The number of connections to examine during each run of the idle connection evictor thread. (Note: The comment states "Property not used in tomcat-jdbc-pool", indicating this might be a legacy or ignored parameter in the current implementation).
    • validationInterval: (e.g., 3000)
      • Purpose: A minimum interval (in milliseconds) between successive connection validations. If a connection needs validation but was validated within this interval, it won't be validated again, reducing overhead.
    • validationQueryTimeout: (e.g., -1)
      • Purpose: The timeout (in seconds) for the SQL query used to validate connections (e.g., SELECT 1). A value of -1 usually means no timeout.
    • maxActive: (e.g., 100)
      • Purpose: The maximum number of active connections that can be allocated from the pool at any given time. This prevents the database from being overwhelmed and caps resource usage.
    • maxIdle: (e.g., 30)
      • Purpose: The maximum number of idle connections that the pool will maintain. If the number of idle connections exceeds this, excess connections are closed.
    • maxWait: (e.g., 10000)
      • Purpose: The maximum number of milliseconds that the connection pool manager will wait for a database connection to become available when the pool is exhausted. If a connection is not available within this time, an exception is thrown.
    • removeAbandonedTimeout: (e.g., 180)
      • Purpose: (Seen in asgard example) The time in seconds after which an abandoned connection (a connection checked out from the pool but not returned by the application) will be forcibly reclaimed by the pool. This helps prevent connection leaks.

Conclusion:

This .md configuration file is thus a critical artifact in the deployment pipeline. It serves as the definitive, version-controlled source for consistently, reproducibly, and fine-tuned Tomcat configurations, enabling robust automation and clear documentation of the server's operational parameters and its essential connections to backend services.