Embedded Servers

// => Traditional Spring MVC: extends WebApplicationInitializer
public class ZakatWebAppInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext servletContext) throws ServletException {
        // => Manual DispatcherServlet registration
        AnnotationConfigWebApplicationContext context =
            new AnnotationConfigWebApplicationContext();
        context.register(WebConfig.class);  // => Load Spring config

        // => Register DispatcherServlet manually
        DispatcherServlet servlet = new DispatcherServlet(context);
        ServletRegistration.Dynamic registration =
            servletContext.addServlet("dispatcher", servlet);
        // => Map servlet to /* (all requests)
        registration.setLoadOnStartup(1);
        registration.addMapping("/");
    }
}

// => Package as WAR file
// => mvn clean package produces zakat-app.war

// => Deploy to external Tomcat
// => 1. Install Tomcat 9.x
// => 2. Copy zakat-app.war to $TOMCAT_HOME/webapps/
// => 3. Start Tomcat with startup.sh
// => 4. Application available at http://localhost:8080/zakat-app/

# => Install Tomcat (external dependency)
wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.80/bin/apache-tomcat-9.0.80.tar.gz
tar xzf apache-tomcat-9.0.80.tar.gz
cd apache-tomcat-9.0.80

# => Deploy WAR
cp /path/to/zakat-app.war webapps/

# => Start server
./bin/startup.sh
# => Tomcat starts, unpacks WAR, deploys application
# => Application accessible at http://localhost:8080/zakat-app/

package com.zakatfoundation.app;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication  // => Includes spring-boot-starter-web
// => spring-boot-starter-web transitively includes spring-boot-starter-tomcat
public class ZakatApplication {

    public static void main(String[] args) {
        SpringApplication.run(ZakatApplication.class, args);
        // => Starts embedded Tomcat automatically
        // => Server listens on port 8080 by default
    }
}

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <!-- Transitively includes spring-boot-starter-tomcat -->
    <!-- No explicit Tomcat dependency needed -->
</dependency>

# => Package as executable JAR
mvn clean package
# => Produces target/zakat-app-1.0.0.jar (fat JAR with embedded Tomcat)

# => Run application (single command)
java -jar target/zakat-app-1.0.0.jar
# => Spring Boot starts embedded Tomcat on port 8080
# => Application accessible at http://localhost:8080/ (no context path)

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <!-- Exclude default Tomcat -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Add Jetty -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

@SpringBootApplication
public class ZakatApplication {
    public static void main(String[] args) {
        SpringApplication.run(ZakatApplication.class, args);
        // => Now starts embedded Jetty instead of Tomcat
        // => No code changes required
    }
}

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Add Undertow (non-blocking, high-performance) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

# => Server configuration: port, context path, timeouts
server:
  port: 8443 # => Listen on port 8443 (default: 8080)
  # => Production: use 8080 (HTTP) or 8443 (HTTPS)

  servlet:
    context-path: /zakat-api
    # => All endpoints under /zakat-api/*
    # => GET /zakat-api/donations (not GET /donations)
    # => Useful for versioning: /v1/donations

  # => Connection timeouts (important for production)
  tomcat:
    connection-timeout: 20s # => 20 seconds for request
    threads:
      max: 200 # => Maximum concurrent requests
      min-spare: 10 # => Minimum threads always running
    # => Thread pool configuration affects throughput

  # => SSL/TLS configuration
  ssl:
    enabled: true # => Enable HTTPS
    key-store: classpath:keystore.p12
    # => PKCS12 keystore with certificate
    key-store-password: ${SSL_KEYSTORE_PASSWORD}
    # => Password from environment variable
    key-store-type: PKCS12
    key-alias: zakat-api

  # => Compression (reduce bandwidth)
  compression:
    enabled: true # => Enable gzip compression
    mime-types: text/html,text/xml,text/plain,application/json
    # => Compress JSON responses (API responses)
    min-response-size: 1024 # => Only compress responses >1KB

package com.zakatfoundation.config;

import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ServerConfig {

    @Bean
    public WebServerFactoryCustomizer<TomcatServletWebServerFactory>
            servletContainerCustomizer() {
        // => Customize Tomcat server factory
        return factory -> {
            // => Add custom Tomcat connector
            factory.addConnectorCustomizers(connector -> {
                // => HTTP/2 support
                connector.addUpgradeProtocol(
                    new org.apache.coyote.http2.Http2Protocol());
                // => Enables HTTP/2 for better performance
            });

            // => Add error pages
            factory.addErrorPages(
                new ErrorPage(HttpStatus.NOT_FOUND, "/404.html"),
                new ErrorPage(HttpStatus.INTERNAL_SERVER_ERROR, "/500.html")
            );
        };
    }
}

# => Enable Tomcat access logs (production requirement)
server:
  tomcat:
    accesslog:
      enabled: true # => Enable access logging
      directory: /var/log/zakat-api
      # => Log directory (ensure writable)
      prefix: access_log
      suffix: .txt
      pattern: '%h %l %u %t "%r" %s %b %D'
      # => %h: client IP, %r: request line, %s: status, %D: time in ms
      # => Example: 192.168.1.100 - - [06/Feb/2026:10:30:00 +0700] "GET /donations HTTP/1.1" 200 1234 150
      rotate: true # => Daily rotation

# => application.yml (default: dev)
server:
  port: 8080

---
# => application-prod.yml (production)
server:
  port: ${PORT:8080}
  # => Use $PORT environment variable (Cloud Foundry, Heroku)
  # => Fallback to 8080 if not set

# => Graceful shutdown (complete in-flight requests)
server:
  shutdown: graceful # => Don't cut connections immediately
  # => Waits for requests to complete before shutdown

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s
    # => Maximum 30 seconds to complete requests
    # => After timeout, forceful shutdown

FROM eclipse-temurin:17-jre-alpine
# => JRE only (no JDK), Alpine for smaller image

WORKDIR /app
COPY target/zakat-app-1.0.0.jar app.jar
# => Copy JAR with embedded Tomcat

# => Run as non-root user (security best practice)
RUN addgroup -S spring && adduser -S spring -G spring
USER spring:spring

EXPOSE 8080
# => Expose port (informational)

# => Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s \
  CMD wget -q --spider http://localhost:8080/actuator/health || exit 1

# => Run application
ENTRYPOINT ["java", "-jar", "app.jar"]
# => Single command: no Tomcat installation needed