Package com.cloudforge.core.interfaces

Interface ApplicationSpec

All Known Implementing Classes:
DroneApplicationSpec, GiteaApplicationSpec, GitLabApplicationSpec, GrafanaApplicationSpec, HarborApplicationSpec, JenkinsApplicationSpec, MattermostApplicationSpec, MattermostTeamApplicationSpec, MetabaseApplicationSpec, NexusApplicationSpec, PostgreSQLApplicationSpec, PrometheusApplicationSpec, RedisApplicationSpec, SupersetApplicationSpec, VaultApplicationSpec
public interface ApplicationSpec
Application specification interface defining application-specific configuration. This enables CloudForge to deploy any application (Jenkins, GitLab, Vault, etc.) using the same infrastructure patterns.

Implementations provide configuration for both container (Fargate) and EC2 deployments, supporting both EFS and EBS storage strategies.

CloudForge 3.0.0: Universal Application Support

Example implementations:

  • JenkinsApplicationSpec: Jenkins CI/CD automation server
  • GitLabApplicationSpec: GitLab DevOps platform
  • GrafanaApplicationSpec: Grafana metrics visualization
  • PostgreSQLApplicationSpec: PostgreSQL database
  • VaultApplicationSpec: HashiCorp Vault secrets management
  • + 9 more built-in applications

Plugin Metadata:

Implementations should be annotated with ApplicationPlugin for auto-discovery and metadata support:


 @ApplicationPlugin(
     value = "jenkins",
     category = "cicd",
     displayName = "Jenkins",
     description = "Open-source automation server for CI/CD"
 )
 public class JenkinsApplicationSpec implements ApplicationSpec {
     // ...
 }

  • Method Details

    • applicationId

      String applicationId()
      Returns a unique identifier for this application. Used for logging, metrics, and resource naming.
      Returns:
      application identifier (e.g., "jenkins", "gitlab", "vault")

    • defaultContainerImage

      String defaultContainerImage()
      Returns the default container image for this application. Can be overridden by deployment context configuration.
      Returns:
      container image string (e.g., "jenkins/jenkins:lts")

    • applicationPort

      int applicationPort()
      Returns the primary application port. This is the port the application listens on inside the container.
      Returns:
      application port (e.g., 8080 for Jenkins)

    • containerDataPath

      String containerDataPath()
      Returns the container path where application data is stored. This is where the volume will be mounted inside the container.
      Returns:
      container mount path (e.g., "/var/jenkins_home")

    • efsDataPath

      String efsDataPath()
      Returns the EFS path for this application's data. This is the path within the EFS filesystem.
      Returns:
      EFS path (e.g., "/jenkins")

    • volumeName

      String volumeName()
      Returns the volume name for this application. Used to reference the volume in task definitions.
      Returns:
      volume name (e.g., "jenkinsHome")

    • containerUser

      String containerUser()
      Returns the container user (UID:GID) to run as. Important for file permissions when using EFS.
      Returns:
      user in format "UID:GID" (e.g., "1000:1000")

    • efsPermissions

      String efsPermissions()
      Returns the EFS permissions for the access point.
      Returns:
      permissions string (e.g., "750")

    • containerEnvironmentVariables

      default Map<String,String> containerEnvironmentVariables(String fqdn, boolean sslEnabled, String authMode)
      Configures application-specific environment variables for the container.

      Applications can override this to provide custom environment variables based on deployment configuration (FQDN, SSL, authMode, etc.). The infrastructure passes the FQDN, SSL settings, and authentication mode for applications that need reverse proxy configuration or authentication-specific setup.

      Example use cases:

      • Jenkins: JAVA_OPTS, JENKINS_OPTS for reverse proxy configuration, skip setup wizard for application-oidc
      • GitLab: GITLAB_OMNIBUS_CONFIG for external URL configuration and OIDC setup
      • Vault: VAULT_ADDR for API endpoint configuration
      Parameters:
      fqdn - The fully qualified domain name (may be null)
      sslEnabled - Whether SSL is enabled
      authMode - The authentication mode (may be null, e.g., "none", "alb-oidc", "application-oidc")
      Returns:
      Map of environment variable key-value pairs (never null, may be empty)

    • healthCheckPath

      default String healthCheckPath()
      Returns the health check path for ALB/ELB health checks.

      Different applications expose health endpoints at different paths:

      • Jenkins: /login
      • GitLab: /users/sign_in
      • Grafana: /api/health
      • Metabase: /api/health
      Returns:
      health check path (e.g., "/login", "/api/health")

    • ebsDeviceName

      String ebsDeviceName()
      Returns the EBS device name for EC2 instances when not using EFS. This is the device that will be formatted and mounted for application data.
      Returns:
      EBS device path (e.g., "/dev/xvdh")

    • ec2DataPath

      String ec2DataPath()
      Returns the EC2 data path where application stores persistent data. This may differ from containerDataPath depending on application packaging.
      Returns:
      EC2 mount path (e.g., "/var/lib/jenkins")

    • ec2LogPaths

      List<String> ec2LogPaths()
      Returns CloudWatch log file paths for EC2 monitoring. These files will be streamed to CloudWatch Logs for centralized logging.
      Returns:
      list of absolute log file paths (e.g., ["/var/log/jenkins/jenkins.log"])

    • configureUserData

      void configureUserData(UserDataBuilder builder, Ec2Context context)
      Configure EC2 UserData script for application installation and setup.

      The implementation should use the UserDataBuilder to add application-specific installation commands while leveraging infrastructure helpers for storage mounting and CloudWatch configuration.

      The infrastructure handles:

      • System updates
      • EFS vs EBS storage mounting (based on availability)
      • CloudWatch Agent installation and configuration
      • File permissions and ownership

      The application provides:

      • Application installation commands (yum/dnf install, etc.)
      • Application configuration
      • Service startup commands
      Parameters:
      builder - The UserDataBuilder providing infrastructure helpers
      context - The Ec2Context providing runtime information

    • supportsOidcIntegration

      default boolean supportsOidcIntegration()
      Returns whether this application supports OIDC integration.

      Applications with built-in OIDC support (GitLab, Grafana, SonarQube) or plugin support (Jenkins) should return true.

      Returns:
      true if application can integrate with OIDC providers

    • getOidcIntegration

      default OidcIntegration getOidcIntegration()
      Returns the OIDC integration handler for this application.

      This provides application-specific configuration for integrating with Cognito or IAM Identity Center OIDC.

      Returns:
      OIDC integration handler, or null if not supported

    • getSupportedAuthModes

      default List<String> getSupportedAuthModes()
      Returns the list of supported authentication modes for this application.

      CloudForge supports three authentication modes:

      • application-oidc: OIDC authentication integrated within the application (requires getOidcIntegration() != null)
      • alb-oidc: OIDC authentication at ALB level (works for all applications)
      • none: No authentication (public access or manually configured)

      The list is ordered by preference. The first mode is the recommended default.

      Default behavior:

      • If application has OIDC integration → ["application-oidc", "alb-oidc", "none"]
      • If application claims OIDC support but lacks integration → ["alb-oidc", "none"]
      • If application doesn't support OIDC → ["none"]
      Returns:
      List of supported auth modes in order of preference (never null, never empty)

    • getRecommendedAuthMode

      default String getRecommendedAuthMode()
      Returns the recommended (default) authentication mode for this application.

      This is the first mode from getSupportedAuthModes().

      Returns:
      the recommended auth mode (e.g., "application-oidc", "alb-oidc", "none")

    • protectedPaths

      default List<String> protectedPaths()
      Returns paths that require authentication when using ALB-level OIDC.

      When this list is non-empty and authMode is "alb-oidc", the ALB will:

      • Require OIDC authentication for requests matching these paths
      • Allow unauthenticated access to all other paths

      When this list is empty (default), ALL paths require authentication.

      Path patterns support ALB path-pattern syntax:

      • Exact: "/admin"
      • Prefix wildcard: "/admin/*"
      • Extension: "*.php"

      Example for phpBB (protect admin and installer):

      
 @Override
 public List<String> protectedPaths() {
     return List.of("/adm/*", "/install/*");
 }

      Example for WordPress (protect wp-admin):

      
 @Override
 public List<String> protectedPaths() {
     return List.of("/wp-admin/*", "/wp-login.php");
 }

      Users can override these defaults via DeploymentContext:

      • protectedPaths: Override/replace the application defaults
      • additionalProtectedPaths: Add to the application defaults
      • publicPaths: Explicitly mark paths as public (overrides protected)
      Returns:
      list of path patterns requiring authentication (empty = protect everything)
      See Also:

    • publicPaths

      default List<String> publicPaths()
      Returns paths that should always be public (no authentication required).

      These paths are excluded from authentication even when they would otherwise be protected. Useful for health checks, public APIs, etc.

      Common use cases:

      • Health check endpoints: "/health", "/api/health"
      • Public API endpoints: "/api/public/*"
      • Static assets: "/static/*", "/assets/*"
      Returns:
      list of path patterns that should be public (empty by default)

    • optionalPorts

      default List<ApplicationSpec.OptionalPort> optionalPorts()
      Returns optional ports that can be enabled via deployment configuration.

      These ports are NOT exposed by default. Users must set the corresponding configKey to true in their deployment configuration to enable each port.

      Example implementation for Mattermost:

      
 @Override
 public List<OptionalPort> optionalPorts() {
     return List.of(
         OptionalPort.outboundTcp(587, "enableSmtp", "SMTP Email"),
         OptionalPort.inboundTcp(8074, "enableClustering", "Cluster Gossip")
     );
 }

      User enables in deployment-context.json:

      
 {
   "enableSmtp": true,
   "enableClustering": true
 }
      Returns:
      list of optional ports (empty by default - most apps only need primary port)

    • category

      default String category()
      Get the application category from the ApplicationPlugin annotation.
      Returns:
      the category (e.g., "cicd", "monitoring", "database")

    • displayName

      default String displayName()
      Get the human-readable display name for this application.
      Returns:
      the display name, defaulting to capitalized applicationId() if not specified

    • description

      default String description()
      Get the application description.
      Returns:
      the application description

    • defaultCpu

      default int defaultCpu()
      Get the default Fargate CPU units.
      Returns:
      the default CPU units (256, 512, 1024, 2048, 4096)

    • defaultMemory

      default int defaultMemory()
      Get the default Fargate memory in MB.
      Returns:
      the default memory in MB

    • defaultInstanceType

      default String defaultInstanceType()
      Get the default EC2 instance type.
      Returns:
      the default instance type (e.g., "t3.small")

    • supportsFargate

      default boolean supportsFargate()
      Check if this application supports Fargate deployment.
      Returns:
      true if Fargate is supported

    • supportsEc2

      default boolean supportsEc2()
      Check if this application supports EC2 deployment.
      Returns:
      true if EC2 is supported

    • defaultHealthCheckGracePeriod

      default int defaultHealthCheckGracePeriod()
      Get the recommended health check grace period for this application.

      The grace period is how long ECS/ALB waits before starting health checks after a container starts. Applications with longer initialization times (like GitLab) need longer grace periods.

      Default values:

      • Most applications: 300 seconds (5 minutes)
      • GitLab: 600 seconds (10 minutes) - due to database migrations and initialization
      • Other database-heavy apps may also need longer periods
      Returns:
      recommended health check grace period in seconds