Hithomelabs/CFTunnels#150: Add Spring Boot Actuator health check endpoints for portainer-automation

- Add spring-boot-starter-actuator dependency to portainer-automation/build.gradle
- Configure management.server.port=8082 with health,info exposure in application.properties
- Map 5005:8082 in portainer-automation/docker-compose.yaml
- Add MGMT_PORT=5005 to portainer-automation/.env.example
- EXPOSE 8081 8082 in portainer-automation Dockerfile
- No ActuatorSecurityConfig needed: service has no Spring Security/OIDC
- Management port stays LAN-only, NOT added to any tunnel ingress

.env.example

@@ -1,4 +1,5 @@
 CLOUDFLARE_ACCOUNT_ID="<cloudflare account id>"
 CLOUDFLARE_API_KEY="<cloudflare account key>"
 CLOUDFLARE_EMAIL="<cloudflare email>"
-ENV="<deployment env>"
+ENV="<deployment env>"
+MGMT_PORT="5003"

.gitea/workflows/cftunnels_build_push.yml

@@ -0,0 +1,138 @@
+name: Build & Push CFTunnels
+run-name: CF Build started by ${{ gitea.actor }}
+
+on:
+  push:
+    branches:
+      - test      # → PATCH bump, build & tag as test
+      - main      # → MINOR bump, promote test→prod
+  workflow_dispatch:
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    outputs:
+      new_version: ${{ steps.semver.outputs.new_version }}
+      target_env: ${{ steps.env.outputs.target_env }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine environment
+        id: env
+        run: |
+          [[ "${{ github.ref_name }}" == "main" ]] && ENV="prod" || ENV="${{ github.ref_name }}"
+          if [[ "$ENV" != "test" && "$ENV" != "prod" ]]; then
+            echo "→ Invalid environment: $ENV. Must be 'test' or 'prod'."
+            exit 1
+          fi
+          echo "target_env=$ENV" >> $GITHUB_OUTPUT
+
+      - name: Calculate semver bump
+        id: semver
+        run: |
+          VERSION=$(git describe --tags --match "cf-*" --abbrev=0 2>/dev/null || echo "cf-0.0.0")
+          echo "Latest tag: ${VERSION}"
+          # Strip cf- prefix
+          VERSION=${VERSION#cf-}
+          MAJOR=$(echo ${VERSION} | cut -d "." -f 1)
+          MINOR=$(echo ${VERSION} | cut -d "." -f 2)
+          PATCH=$(echo ${VERSION} | cut -d "." -f 3)
+
+          if [[ "${{ steps.env.outputs.target_env }}" == "prod" ]]; then
+            # MINOR bump, reset PATCH
+            NEW_MINOR=$((MINOR + 1))
+            NEW_VERSION="${MAJOR}.${NEW_MINOR}.0"
+            echo "Production → minor bump: ${NEW_VERSION}"
+          else
+            # test → PATCH bump
+            NEW_PATCH=$((PATCH + 1))
+            NEW_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}"
+            echo "Test → patch bump: ${NEW_VERSION}"
+          fi
+          echo "new_version=cf-${NEW_VERSION}" >> $GITHUB_OUTPUT
+
+  build-and-push:
+    runs-on: ubuntu-latest
+    needs: version
+    container:
+      image: 192.168.0.100:8928/hithomelabs/ci-runner:1.0.0
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install JDK (Alpine package)
+        run: |
+          apk add --no-cache openjdk17-jdk
+          echo "JAVA_HOME=/usr/lib/jvm/java-17-openjdk" >> "$GITHUB_ENV"
+
+      - name: Validate Gradle Wrapper (offline checksum)
+        run: |
+          sha256sum --check gradle/wrapper/gradle-wrapper.jar.sha256
+
+      - name: Create and push git tag
+        run: |
+          echo "New version: ${{ needs.version.outputs.new_version }}"
+          git config --global user.name "${{ gitea.actor }}"
+          git config --global user.email "${{ gitea.actor }}@users.noreply.github.com"
+          git tag -a "${{ needs.version.outputs.new_version }}" \
+            -m "Push CF version ${{ needs.version.outputs.new_version }}"
+          git push origin "${{ needs.version.outputs.new_version }}"
+
+      - name: Log in to Gitea Docker Registry
+        uses: docker/login-action@v3
+        with:
+          registry: 'http://192.168.0.100:8928'
+          username: hitanshu
+          password: ${{ secrets.TOKEN }}
+
+      - name: Build image (test) or promote (prod)
+        run: |
+          ENV="${{ needs.version.outputs.target_env }}"
+          VER="${{ needs.version.outputs.new_version }}"
+          REG="192.168.0.100:8928/hithomelabs/cftunnels"
+
+          if [[ "$ENV" == "test" ]]; then
+            echo "→ Building fresh image for test"
+            ./gradlew :cftunnels-service:bootBuildImage --imageName="${REG}:${VER}"
+            docker tag "${REG}:${VER}" "${REG}:test"
+            docker push "${REG}:test"
+            docker push "${REG}:${VER}"
+          else
+            echo "→ Promoting test image to prod"
+            docker pull "${REG}:test"
+            docker tag "${REG}:test" "${REG}:${VER}"
+            docker tag "${REG}:${VER}" "${REG}:prod"
+            docker push "${REG}:prod"
+            docker push "${REG}:${VER}"
+          fi
+
+      - name: Set Portainer deploy variables
+        id: portainer-vars
+        run: |
+          ENV="${{ needs.version.outputs.target_env }}"
+          if [[ "$ENV" == "prod" ]]; then
+            echo "url=http://192.168.0.100:8082" >> $GITHUB_OUTPUT
+            echo "stack=${{ vars.CFTUNNELS_PROD_STACK_ID }}" >> $GITHUB_OUTPUT
+            echo "key=${{ secrets.PORTAINER_SERVICE_API_KEY_PROD }}" >> $GITHUB_OUTPUT
+          else
+            echo "url=http://192.168.0.100:8081" >> $GITHUB_OUTPUT
+            echo "stack=${{ vars.CFTUNNELS_DEV_STACK_ID }}" >> $GITHUB_OUTPUT
+            echo "key=${{ secrets.PORTAINER_SERVICE_API_KEY }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Trigger Portainer Redeploy
+        if: success()
+        env:
+          PORTAINER_AUTOMATION_URL: ${{ steps.portainer-vars.outputs.url }}
+          STACK_ID: ${{ steps.portainer-vars.outputs.stack }}
+          API_KEY: ${{ steps.portainer-vars.outputs.key }}
+        run: |
+          wget -q --no-check-certificate --timeout=30 \
+            --post-data= \
+            --header="X-API-Key: $API_KEY" \
+            -O - \
+            "$PORTAINER_AUTOMATION_URL/api/deploy/$STACK_ID" 2>&1 \
+            || echo "Deploy trigger failed (non-fatal)"

.gitea/workflows/portainer_automation_build_push.yml

@@ -0,0 +1,110 @@
+name: Build & Push Portainer Automation
+run-name: PA Build started by ${{ gitea.actor }}
+
+on:
+  push:
+    branches:
+      - test      # → PATCH bump, build & tag as test
+      - main      # → MINOR bump, promote test→prod
+  workflow_dispatch:
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    outputs:
+      new_version: ${{ steps.semver.outputs.new_version }}
+      target_env: ${{ steps.env.outputs.target_env }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine environment
+        id: env
+        run: |
+          [[ "${{ github.ref_name }}" == "main" ]] && ENV="prod" || ENV="${{ github.ref_name }}"
+          if [[ "$ENV" != "test" && "$ENV" != "prod" ]]; then
+            echo "→ Invalid environment: $ENV. Must be 'test' or 'prod'."
+            exit 1
+          fi
+          echo "target_env=$ENV" >> $GITHUB_OUTPUT
+
+      - name: Calculate semver bump
+        id: semver
+        run: |
+          VERSION=$(git describe --tags --match "pa-*" --abbrev=0 2>/dev/null || echo "pa-0.0.0")
+          echo "Latest tag: ${VERSION}"
+          # Strip pa- prefix
+          VERSION=${VERSION#pa-}
+          MAJOR=$(echo ${VERSION} | cut -d "." -f 1)
+          MINOR=$(echo ${VERSION} | cut -d "." -f 2)
+          PATCH=$(echo ${VERSION} | cut -d "." -f 3)
+
+          if [[ "${{ steps.env.outputs.target_env }}" == "prod" ]]; then
+            # MINOR bump, reset PATCH
+            NEW_MINOR=$((MINOR + 1))
+            NEW_VERSION="${MAJOR}.${NEW_MINOR}.0"
+            echo "Production → minor bump: ${NEW_VERSION}"
+          else
+            # test → PATCH bump
+            NEW_PATCH=$((PATCH + 1))
+            NEW_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}"
+            echo "Test → patch bump: ${NEW_VERSION}"
+          fi
+          echo "new_version=pa-${NEW_VERSION}" >> $GITHUB_OUTPUT
+
+  build-and-push:
+    runs-on: ubuntu-latest
+    needs: version
+    container:
+      image: 192.168.0.100:8928/hithomelabs/ci-runner:1.0.0
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install JDK (Alpine package)
+        run: |
+          apk add --no-cache openjdk17-jdk
+          echo "JAVA_HOME=/usr/lib/jvm/java-17-openjdk" >> "$GITHUB_ENV"
+
+      - name: Validate Gradle Wrapper (offline checksum)
+        run: |
+          sha256sum --check gradle/wrapper/gradle-wrapper.jar.sha256
+
+      - name: Create and push git tag
+        run: |
+          echo "New version: ${{ needs.version.outputs.new_version }}"
+          git config --global user.name "${{ gitea.actor }}"
+          git config --global user.email "${{ gitea.actor }}@users.noreply.github.com"
+          git tag -a "${{ needs.version.outputs.new_version }}" \
+            -m "Push PA version ${{ needs.version.outputs.new_version }}"
+          git push origin "${{ needs.version.outputs.new_version }}"
+
+      - name: Log in to Gitea Docker Registry
+        uses: docker/login-action@v3
+        with:
+          registry: 'http://192.168.0.100:8928'
+          username: hitanshu
+          password: ${{ secrets.TOKEN }}
+
+      - name: Build image (test) or promote (prod)
+        run: |
+          ENV="${{ needs.version.outputs.target_env }}"
+          VER="${{ needs.version.outputs.new_version }}"
+          REG="192.168.0.100:8928/hithomelabs/portainer-automation"
+
+          if [[ "$ENV" == "test" ]]; then
+            echo "→ Building fresh image for test"
+            ./gradlew :portainer-automation:bootBuildImage --imageName="${REG}:${VER}"
+            docker tag "${REG}:${VER}" "${REG}:test"
+            docker push "${REG}:test"
+            docker push "${REG}:${VER}"
+          else
+            echo "→ Promoting test image to prod"
+            docker pull "${REG}:test"
+            docker tag "${REG}:test" "${REG}:${VER}"
+            docker tag "${REG}:${VER}" "${REG}:prod"
+            docker push "${REG}:prod"
+            docker push "${REG}:${VER}"
+          fi

.gitea/workflows/prod_image_tag_promote.yaml

@@ -1,57 +0,0 @@
-name: Promote image with tag test to prod
-run-name: Build started by $ {{gitea.actor}}
-on:
-  push:
-    branches: [main]
-jobs:
-  tag:
-    runs-on: ubuntu-latest
-    outputs:
-      new_version: ${{ steps.new_version.outputs.new_version }}
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Get new version
-        id: new_version
-        run: |
-          VERSION=$(git describe --tags --abbrev=0)
-          echo ${VERSION}
-          MAJOR=$(echo ${VERSION} | cut -d "." -f 1)
-          MINOR=$(echo ${VERSION} | cut -d "." -f 2)
-          PATCH=0
-          NEW_MINOR=$(( ${MINOR} + 1))
-          echo ${NEW_MINOR}
-          echo "new_version=$(echo "${MAJOR}.${NEW_MINOR}.${PATCH}")" >> $GITHUB_OUTPUT
-  build_tag_push:
-    runs-on: ubuntu-latest
-    needs: tag
-    container:
-      image: 192.168.0.100:8928/hithomelabs/ci-runner:1.0.0
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Create and push tag
-        run: |
-          echo "NEW_VERSION=${{ needs.tag.outputs.new_version }}"
-          git config --global user.name "${{gitea.actor}}"
-          git config --global user.email "${{ gitea.actor }}@users.noreply.github.com"
-          git tag -a ${{ needs.tag.outputs.new_version }} -m "Pushing new version ${{ needs.tag.outputs.new_version }}"
-          git push origin ${{ needs.tag.outputs.new_version }}
-      - name: Log in to Gitea Docker Registry
-        uses: docker/login-action@v3
-        with:
-          registry: 'http://192.168.0.100:8928'
-          username: hitanshu
-          password: ${{ secrets.TOKEN }}
-      - name: Tag prod image
-        run: |
-          docker tag 192.168.0.100:8928/hithomelabs/cftunnels:test 192.168.0.100:8928/hithomelabs/cftunnels:${{ needs.tag.outputs.new_version }}
-          docker tag 192.168.0.100:8928/hithomelabs/cftunnels:${{ needs.tag.outputs.new_version }} 192.168.0.100:8928/hithomelabs/cftunnels:prod
-      - name: Push to Gitea Registry
-        run: |
-          docker push 192.168.0.100:8928/hithomelabs/cftunnels:prod
-          docker push 192.168.0.100:8928/hithomelabs/cftunnels:${{ needs.tag.outputs.new_version }}

.gitea/workflows/test_image_build_push.yml

@@ -1,66 +0,0 @@
-name: sample gradle build and test
-run-name: Build started by ${{ gitea.actor }}
-on:
-  push:
-    branches: [test]
-jobs:
-  tag:
-    runs-on: ubuntu-latest
-    outputs:
-      new_version: ${{ steps.new_version.outputs.new_version }}
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Get new version
-        id: new_version
-        run: |
-          VERSION=$(git describe --tags --abbrev=0)
-          echo "Current version: ${VERSION}"
-          MAJOR=$(echo ${VERSION} | cut -d "." -f 1)
-          MINOR=$(echo ${VERSION} | cut -d "." -f 2)
-          PATCH=$(echo ${VERSION} | cut -d "." -f 3)
-          NEW_PATCH=$((PATCH + 1))
-          NEW_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}"
-          echo "New version: ${NEW_VERSION}"
-          echo "new_version=${NEW_VERSION}" >> $GITHUB_OUTPUT
-  build_tag_push:
-    runs-on: ubuntu-latest
-    needs: tag
-    container:
-      image: 192.168.0.100:8928/hithomelabs/ci-runner:1.0.0
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Install JDK (Alpine package)
-        run: |
-          apk add --no-cache openjdk17-jdk
-          echo "JAVA_HOME=/usr/lib/jvm/java-17-openjdk" >> "$GITHUB_ENV"
-      - name: Validate Gradle Wrapper
-        uses: gradle/actions/wrapper-validation@v3
-      - name: Create and push tag
-        run: |
-          echo "New version: ${{ needs.tag.outputs.new_version }}"
-          git config --global user.name "${{ gitea.actor }}"
-          git config --global user.email "${{ gitea.actor }}@users.noreply.github.com"
-          git tag -a "${{ needs.tag.outputs.new_version }}" -m "Pushing new version ${{ needs.tag.outputs.new_version }}"
-          git push origin "${{ needs.tag.outputs.new_version }}"
-      - name: Log in to Gitea Docker Registry
-        uses: docker/login-action@v3
-        with:
-          registry: 'http://192.168.0.100:8928'
-          username: hitanshu
-          password: ${{ secrets.TOKEN }}
-      - name: Gradle build
-        run: ./gradlew :cftunnels-service:bootBuildImage --imageName=192.168.0.100:8928/hithomelabs/cftunnels:${{ needs.tag.outputs.new_version }}
-      - name: Tag image as test
-        run: docker tag 192.168.0.100:8928/hithomelabs/cftunnels:${{ needs.tag.outputs.new_version }} 192.168.0.100:8928/hithomelabs/cftunnels:test
-      - name: Push to Gitea Registry
-        run: |
-          docker push 192.168.0.100:8928/hithomelabs/cftunnels:test
-          docker push 192.168.0.100:8928/hithomelabs/cftunnels:${{ needs.tag.outputs.new_version }}
-  

cftunnels-service/Dockerfile

@@ -9,4 +9,5 @@ RUN ./gradlew :cftunnels-service:bootJar
 
 FROM openjdk:17-jdk-slim
 COPY --from=build /app/cftunnels-service/build/libs/*.jar app.jar
+EXPOSE 8080 8081
 ENTRYPOINT ["java", "-jar", "/app.jar"]

cftunnels-service/build.gradle

@@ -7,6 +7,7 @@ dependencies {
     implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
     implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
     implementation 'org.springframework.boot:spring-boot-starter-security'
+    implementation 'org.springframework.boot:spring-boot-starter-actuator'
     implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5'
     implementation 'org.hibernate.validator:hibernate-validator'
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Config/Security/ActuatorSecurityConfig.java

@@ -0,0 +1,39 @@
+package com.hithomelabs.cftunnels.Config.Security;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
+
+/**
+ * Security configuration for Spring Boot Actuator endpoints.
+ *
+ * This configuration permits unauthenticated access to /actuator/health and /actuator/info
+ * endpoints, enabling health monitoring by Uptime Kuma without requiring OIDC authentication.
+ * All other actuator endpoints remain protected and require authentication.
+ *
+ * Uses @Order(Ordered.HIGHEST_PRECEDENCE) to ensure this filter chain is evaluated BEFORE
+ * any auto-configured management security filter chains (e.g., ManagementWebSecurityAutoConfiguration).
+ * Without this, the catch-all SecurityFilterChain in SecuirtyConfig can intercept actuator
+ * requests on the separate management port (management.server.port=8081) and redirect to OIDC login.
+ */
+@Configuration
+@Order(Ordered.HIGHEST_PRECEDENCE)
+public class ActuatorSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain actuatorSecurityChain(HttpSecurity http) throws Exception {
+        http
+                .securityMatcher(EndpointRequest.toAnyEndpoint())
+                .authorizeHttpRequests(auth -> auth
+                        .requestMatchers("/actuator/health", "/actuator/info").permitAll()
+                        .anyRequest().authenticated()
+                )
+                .csrf(csrf -> csrf.disable());
+
+        return http.build();
+    }
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Config/Security/SecuirtyConfig.java

@@ -29,6 +29,7 @@ public class SecuirtyConfig {
         http
                 .authorizeHttpRequests(auth -> auth
                         //.requestMatchers( "/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html" ).permitAll()
+                        .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                         .anyRequest().authenticated()
                 ).csrf(csrf -> csrf.disable())
                 .with(new OAuth2LoginConfigurer<>(),

cftunnels-service/src/main/resources/application-ci.properties

@@ -4,4 +4,8 @@ spring.datasource.url=jdbc:h2:mem:testdb
 spring.datasource.driver-class-name=org.h2.Driver
 spring.datasource.username=sa
 spring.datasource.password=
-spring.jpa.hibernate.ddl-auto=none
+spring.jpa.hibernate.ddl-auto=none
+
+# Actuator configuration for CI
+management.endpoints.web.exposure.include=health,info
+management.endpoint.health.show-details=never

cftunnels-service/src/main/resources/application-local.properties

@@ -1,8 +1,10 @@
 api.baseUrl=http://localhost:8080
 
-management.health.db.enabled=true
-management.endpoints.web.exposure.include=health
+# Actuator configuration for local development
+management.server.port=8081
+management.endpoints.web.exposure.include=health,info
 management.endpoint.health.show-details=always
+management.health.db.enabled=true
 
 logging.level.org.hibernate.SQL=DEBUG
 debug=true

cftunnels-service/src/main/resources/application-prod.properties

@@ -9,4 +9,8 @@ spring.datasource.driver-class-name=org.postgresql.Driver
 # JPA Configuration
 spring.jpa.hibernate.ddl-auto=create-drop
 spring.jpa.show-sql=false
-spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
+spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
+
+# Actuator configuration
+management.endpoints.web.exposure.include=health,info
+management.endpoint.health.show-details=when-authorized

cftunnels-service/src/main/resources/application-test.properties

@@ -10,3 +10,7 @@ spring.datasource.driver-class-name=org.postgresql.Driver
 spring.jpa.hibernate.ddl-auto=update
 spring.jpa.show-sql=true
 spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
+
+# Actuator configuration
+management.endpoints.web.exposure.include=health,info
+management.endpoint.health.show-details=when-authorized

cftunnels-service/src/main/resources/application.properties

@@ -35,4 +35,9 @@ spring.jpa.hibernate.ddl-auto=update
 spring.jpa.show-sql=true
 spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
 
-spring.jpa.open-in-view=false
+spring.jpa.open-in-view=false
+
+# Actuator configuration - management port and exposed endpoints
+management.server.port=8081
+management.endpoints.web.exposure.include=health,info
+management.endpoint.health.show-details=when-authorized

common/build.gradle

@@ -8,4 +8,6 @@ dependencies {
     annotationProcessor 'org.projectlombok:lombok'
 
     testImplementation 'org.junit.jupiter:junit-jupiter'
+    testImplementation 'org.mockito:mockito-core'
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
 }

common/src/main/java/com/hithomelabs/common/config/RestTemplateConfig.java

@@ -5,17 +5,29 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
 import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
 import org.springframework.web.client.RestTemplate;
 
+import java.time.Duration;
+
 @Configuration
 public class RestTemplateConfig {
 
+    private static final Duration CONNECT_TIMEOUT = Duration.ofSeconds(10);
+    private static final Duration READ_TIMEOUT = Duration.ofSeconds(30);
+
     @Bean
     public RestTemplate restTemplate() {
-        RestTemplate restTemplate = new RestTemplate();
+        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory();
+        factory.setConnectTimeout(Math.toIntExact(CONNECT_TIMEOUT.toMillis()));
+        factory.setReadTimeout(Math.toIntExact(READ_TIMEOUT.toMillis()));
+
+        RestTemplate restTemplate = new RestTemplate(factory);
         MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
-        converter.setObjectMapper(new ObjectMapper().enable(SerializationFeature.WRAP_ROOT_VALUE).setSerializationInclusion(JsonInclude.Include.NON_NULL));
+        converter.setObjectMapper(new ObjectMapper()
+                .enable(SerializationFeature.WRAP_ROOT_VALUE)
+                .setSerializationInclusion(JsonInclude.Include.NON_NULL));
         restTemplate.getMessageConverters().add(0, converter);
         return restTemplate;
     }

common/src/main/java/com/hithomelabs/common/portainer/client/PortainerApiClient.java

@@ -0,0 +1,302 @@
+package com.hithomelabs.common.portainer.client;
+
+import com.hithomelabs.common.portainer.client.exception.PortainerAuthenticationException;
+import com.hithomelabs.common.portainer.client.exception.PortainerConnectionException;
+import com.hithomelabs.common.portainer.client.exception.PortainerDeploymentException;
+import com.hithomelabs.common.portainer.client.exception.PortainerResourceNotFoundException;
+import com.hithomelabs.common.portainer.model.EnvVariable;
+import com.hithomelabs.common.portainer.model.PortainerAuthRequest;
+import com.hithomelabs.common.portainer.model.PortainerAuthResponse;
+import com.hithomelabs.common.portainer.model.PortainerRedeployRequest;
+import com.hithomelabs.common.portainer.model.PortainerStack;
+
+import org.springframework.core.ParameterizedTypeReference;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.client.HttpClientErrorException;
+import org.springframework.web.client.ResourceAccessException;
+import org.springframework.web.client.RestClientException;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+
+public class PortainerApiClient {
+
+    private static final String API_AUTH = "/api/auth";
+    private static final String API_STACKS = "/api/stacks";
+
+    private final RestTemplate restTemplate;
+    private final String baseUrl;
+    private String jwtToken;
+    private String apiKey;
+
+    public PortainerApiClient(RestTemplate restTemplate, String baseUrl) {
+        this.restTemplate = restTemplate;
+        // Strip trailing slash if present
+        this.baseUrl = baseUrl != null ? baseUrl.replaceAll("/+$", "") : "";
+    }
+
+    // -----------------------------------------------------------
+    // Authentication
+    // -----------------------------------------------------------
+
+    /**
+     * Authenticate using a Portainer API key (recommended).
+     * The API key is sent as a Bearer token in the Authorization header
+     * for all subsequent requests.
+     */
+    public void authenticateWithApiKey(String apiKey) {
+        if (apiKey == null || apiKey.isBlank()) {
+            throw new PortainerAuthenticationException("API key must not be null or blank");
+        }
+        this.apiKey = apiKey;
+        // No JWT token needed when using API key auth
+        this.jwtToken = null;
+    }
+
+    /**
+     * Authenticate with username/password credentials (fallback).
+     * Sends a POST to {@code /api/auth} and stores the returned JWT.
+     */
+    public PortainerAuthResponse authenticateWithPassword(String username, String password) {
+        if (username == null || username.isBlank()) {
+            throw new PortainerAuthenticationException("Username must not be null or blank");
+        }
+        if (password == null || password.isBlank()) {
+            throw new PortainerAuthenticationException("Password must not be null or blank");
+        }
+
+        PortainerAuthRequest request = new PortainerAuthRequest(username, password);
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        HttpEntity<PortainerAuthRequest> entity = new HttpEntity<>(request, headers);
+
+        try {
+            ResponseEntity<PortainerAuthResponse> response = restTemplate.exchange(
+                    baseUrl + API_AUTH,
+                    HttpMethod.POST,
+                    entity,
+                    PortainerAuthResponse.class);
+
+            if (response.getStatusCode() != HttpStatus.OK || response.getBody() == null) {
+                throw new PortainerAuthenticationException(
+                        "Authentication failed with status: " + response.getStatusCode());
+            }
+
+            this.jwtToken = response.getBody().getJwt();
+            // Clear any previously set API key
+            this.apiKey = null;
+            return response.getBody();
+        } catch (HttpClientErrorException e) {
+            throw new PortainerAuthenticationException(
+                    "Authentication failed: " + e.getStatusCode() + " - " + e.getResponseBodyAsString(), e);
+        } catch (ResourceAccessException e) {
+            throw new PortainerConnectionException(
+                    "Unable to connect to Portainer at " + baseUrl + ": " + e.getMessage(), e);
+        }
+    }
+
+    // -----------------------------------------------------------
+    // Stack operations
+    // -----------------------------------------------------------
+
+    /**
+     * List all stacks managed by Portainer.
+     */
+    public List<PortainerStack> listStacks() {
+        HttpEntity<Void> entity = buildAuthEntity();
+
+        try {
+            ResponseEntity<List<PortainerStack>> response = restTemplate.exchange(
+                    baseUrl + API_STACKS,
+                    HttpMethod.GET,
+                    entity,
+                    new ParameterizedTypeReference<>() {});
+
+            if (response.getStatusCode() != HttpStatus.OK || response.getBody() == null) {
+                return Collections.emptyList();
+            }
+            return response.getBody();
+        } catch (HttpClientErrorException e) {
+            if (e.getStatusCode() == HttpStatus.UNAUTHORIZED) {
+                throw new PortainerAuthenticationException(
+                        "Not authenticated. Please authenticate before listing stacks.", e);
+            }
+            throw new PortainerDeploymentException(
+                    "Failed to list stacks: " + e.getStatusCode() + " - " + e.getResponseBodyAsString(), e);
+        } catch (ResourceAccessException e) {
+            throw new PortainerConnectionException(
+                    "Unable to connect to Portainer at " + baseUrl + ": " + e.getMessage(), e);
+        }
+    }
+
+    /**
+     * Find a stack by its exact name.
+     */
+    public Optional<PortainerStack> findStackByName(String name) {
+        if (name == null || name.isBlank()) {
+            return Optional.empty();
+        }
+
+        List<PortainerStack> stacks = listStacks();
+        return stacks.stream()
+                .filter(stack -> name.equals(stack.getName()))
+                .findFirst();
+    }
+
+    /**
+     * Redeploy a standard (non-git) stack.
+     * Sends a PUT to {@code /api/stacks/{stackId}?endpointId={endpointId}}.
+     */
+    public void redeployStack(Long stackId, Long endpointId, boolean pullImage) {
+        if (stackId == null) {
+            throw new PortainerDeploymentException("Stack ID must not be null");
+        }
+        if (endpointId == null) {
+            throw new PortainerDeploymentException("Endpoint ID must not be null");
+        }
+
+        PortainerRedeployRequest body = new PortainerRedeployRequest(pullImage, true);
+        HttpEntity<PortainerRedeployRequest> entity = new HttpEntity<>(body, buildAuthHeaders());
+
+        try {
+            ResponseEntity<Void> response = restTemplate.exchange(
+                    baseUrl + API_STACKS + "/{stackId}?endpointId={endpointId}",
+                    HttpMethod.PUT,
+                    entity,
+                    Void.class,
+                    stackId,
+                    endpointId);
+
+            if (!response.getStatusCode().is2xxSuccessful()) {
+                throw new PortainerDeploymentException(
+                        "Redeploy failed with status: " + response.getStatusCode());
+            }
+        } catch (HttpClientErrorException e) {
+            if (e.getStatusCode() == HttpStatus.UNAUTHORIZED) {
+                throw new PortainerAuthenticationException(
+                        "Not authenticated. Please authenticate before redeploying.", e);
+            }
+            if (e.getStatusCode() == HttpStatus.NOT_FOUND) {
+                throw new PortainerResourceNotFoundException(
+                        "Stack with ID " + stackId + " not found on endpoint " + endpointId, e);
+            }
+            throw new PortainerDeploymentException(
+                    "Failed to redeploy stack " + stackId + ": " + e.getStatusCode()
+                            + " - " + e.getResponseBodyAsString(), e);
+        } catch (ResourceAccessException e) {
+            throw new PortainerConnectionException(
+                    "Unable to connect to Portainer at " + baseUrl + ": " + e.getMessage(), e);
+        }
+    }
+
+    /**
+     * Fetch a single stack by its ID.
+     */
+    public PortainerStack getStack(Long stackId) {
+        if (stackId == null) {
+            throw new PortainerDeploymentException("Stack ID must not be null");
+        }
+        HttpEntity<Void> entity = buildAuthEntity();
+        try {
+            ResponseEntity<PortainerStack> response = restTemplate.exchange(
+                    baseUrl + API_STACKS + "/{stackId}",
+                    HttpMethod.GET,
+                    entity,
+                    PortainerStack.class,
+                    stackId);
+            if (response.getStatusCode() != HttpStatus.OK || response.getBody() == null) {
+                throw new PortainerResourceNotFoundException(
+                        "Stack with ID " + stackId + " not found");
+            }
+            return response.getBody();
+        } catch (HttpClientErrorException e) {
+            if (e.getStatusCode() == HttpStatus.UNAUTHORIZED) {
+                throw new PortainerAuthenticationException(
+                        "Not authenticated. Please authenticate before fetching stack.", e);
+            }
+            if (e.getStatusCode() == HttpStatus.NOT_FOUND) {
+                throw new PortainerResourceNotFoundException(
+                        "Stack with ID " + stackId + " not found", e);
+            }
+            throw new PortainerDeploymentException(
+                    "Failed to fetch stack " + stackId + ": " + e.getStatusCode(), e);
+        } catch (ResourceAccessException e) {
+            throw new PortainerConnectionException(
+                    "Unable to connect to Portainer at " + baseUrl + ": " + e.getMessage(), e);
+        }
+    }
+
+    /**
+     * Redeploy a git-based stack.
+     * Sends a PUT to {@code /api/stacks/{stackId}/git/redeploy?endpointId={endpointId}}.
+     *
+     * @param env optional list of environment variables to pass for compose variable substitution
+     */
+    public void redeployGitStack(Long stackId, Long endpointId, boolean pullImage, List<EnvVariable> env) {
+        if (stackId == null) {
+            throw new PortainerDeploymentException("Stack ID must not be null");
+        }
+        if (endpointId == null) {
+            throw new PortainerDeploymentException("Endpoint ID must not be null");
+        }
+
+        PortainerRedeployRequest body = new PortainerRedeployRequest(pullImage, false, env);
+        HttpEntity<PortainerRedeployRequest> entity = new HttpEntity<>(body, buildAuthHeaders());
+
+        try {
+            ResponseEntity<Void> response = restTemplate.exchange(
+                    baseUrl + API_STACKS + "/{stackId}/git/redeploy?endpointId={endpointId}",
+                    HttpMethod.PUT,
+                    entity,
+                    Void.class,
+                    stackId,
+                    endpointId);
+
+            if (!response.getStatusCode().is2xxSuccessful()) {
+                throw new PortainerDeploymentException(
+                        "Git redeploy failed with status: " + response.getStatusCode());
+            }
+        } catch (HttpClientErrorException e) {
+            if (e.getStatusCode() == HttpStatus.UNAUTHORIZED) {
+                throw new PortainerAuthenticationException(
+                        "Not authenticated. Please authenticate before redeploying.", e);
+            }
+            if (e.getStatusCode() == HttpStatus.NOT_FOUND) {
+                throw new PortainerResourceNotFoundException(
+                        "Git stack with ID " + stackId + " not found on endpoint " + endpointId, e);
+            }
+            throw new PortainerDeploymentException(
+                    "Failed to git-redeploy stack " + stackId + ": " + e.getStatusCode()
+                            + " - " + e.getResponseBodyAsString(), e);
+        } catch (ResourceAccessException e) {
+            throw new PortainerConnectionException(
+                    "Unable to connect to Portainer at " + baseUrl + ": " + e.getMessage(), e);
+        }
+    }
+
+    // -----------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------
+
+    private HttpHeaders buildAuthHeaders() {
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        if (apiKey != null && !apiKey.isBlank()) {
+            headers.set("X-API-Key", apiKey);
+        } else if (jwtToken != null && !jwtToken.isBlank()) {
+            headers.setBearerAuth(jwtToken);
+        }
+        return headers;
+    }
+
+    private <T> HttpEntity<T> buildAuthEntity() {
+        return new HttpEntity<>(buildAuthHeaders());
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/client/exception/PortainerAuthenticationException.java

@@ -0,0 +1,12 @@
+package com.hithomelabs.common.portainer.client.exception;
+
+public class PortainerAuthenticationException extends RuntimeException {
+
+    public PortainerAuthenticationException(String message) {
+        super(message);
+    }
+
+    public PortainerAuthenticationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/client/exception/PortainerConnectionException.java

@@ -0,0 +1,12 @@
+package com.hithomelabs.common.portainer.client.exception;
+
+public class PortainerConnectionException extends RuntimeException {
+
+    public PortainerConnectionException(String message) {
+        super(message);
+    }
+
+    public PortainerConnectionException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/client/exception/PortainerDeploymentException.java

@@ -0,0 +1,12 @@
+package com.hithomelabs.common.portainer.client.exception;
+
+public class PortainerDeploymentException extends RuntimeException {
+
+    public PortainerDeploymentException(String message) {
+        super(message);
+    }
+
+    public PortainerDeploymentException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/client/exception/PortainerResourceNotFoundException.java

@@ -0,0 +1,12 @@
+package com.hithomelabs.common.portainer.client.exception;
+
+public class PortainerResourceNotFoundException extends RuntimeException {
+
+    public PortainerResourceNotFoundException(String message) {
+        super(message);
+    }
+
+    public PortainerResourceNotFoundException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/model/EnvVariable.java

@@ -0,0 +1,24 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class EnvVariable {
+
+    @JsonProperty("name")
+    private String name;
+
+    @JsonProperty("value")
+    private String value;
+
+    public EnvVariable() {}
+
+    public EnvVariable(String name, String value) {
+        this.name = name;
+        this.value = value;
+    }
+
+    public String getName() { return name; }
+    public void setName(String name) { this.name = name; }
+    public String getValue() { return value; }
+    public void setValue(String value) { this.value = value; }
+}

common/src/main/java/com/hithomelabs/common/portainer/model/PortainerAuthRequest.java

@@ -0,0 +1,35 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class PortainerAuthRequest {
+
+    @JsonProperty("Username")
+    private String username;
+
+    @JsonProperty("Password")
+    private String password;
+
+    public PortainerAuthRequest() {}
+
+    public PortainerAuthRequest(String username, String password) {
+        this.username = username;
+        this.password = password;
+    }
+
+    public String getUsername() {
+        return username;
+    }
+
+    public void setUsername(String username) {
+        this.username = username;
+    }
+
+    public String getPassword() {
+        return password;
+    }
+
+    public void setPassword(String password) {
+        this.password = password;
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/model/PortainerAuthResponse.java

@@ -0,0 +1,19 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class PortainerAuthResponse {
+
+    @JsonProperty("jwt")
+    private String jwt;
+
+    public PortainerAuthResponse() {}
+
+    public String getJwt() {
+        return jwt;
+    }
+
+    public void setJwt(String jwt) {
+        this.jwt = jwt;
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/model/PortainerRedeployRequest.java

@@ -0,0 +1,54 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public class PortainerRedeployRequest {
+
+    @JsonProperty("PullImage")
+    private boolean pullImage;
+
+    @JsonProperty("Prune")
+    private boolean prune;
+
+    @JsonProperty("Env")
+    private List<EnvVariable> env;
+
+    public PortainerRedeployRequest() {}
+
+    public PortainerRedeployRequest(boolean pullImage, boolean prune) {
+        this.pullImage = pullImage;
+        this.prune = prune;
+    }
+
+    public PortainerRedeployRequest(boolean pullImage, boolean prune, List<EnvVariable> env) {
+        this.pullImage = pullImage;
+        this.prune = prune;
+        this.env = env;
+    }
+
+    public boolean isPullImage() {
+        return pullImage;
+    }
+
+    public void setPullImage(boolean pullImage) {
+        this.pullImage = pullImage;
+    }
+
+    public boolean isPrune() {
+        return prune;
+    }
+
+    public void setPrune(boolean prune) {
+        this.prune = prune;
+    }
+
+    public List<EnvVariable> getEnv() {
+        return env;
+    }
+
+    public void setEnv(List<EnvVariable> env) {
+        this.env = env;
+    }
+}

common/src/main/java/com/hithomelabs/common/portainer/model/PortainerStack.java

@@ -0,0 +1,77 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+import java.util.Map;
+
+public class PortainerStack {
+
+    @JsonProperty("Id")
+    private Long id;
+
+    @JsonProperty("Name")
+    private String name;
+
+    @JsonProperty("EndpointId")
+    private Long endpointId;
+
+    @JsonProperty("Status")
+    private int status;
+
+    @JsonProperty("ResourceControl")
+    private Map<String, Object> resourceControl;
+
+    @JsonProperty("Env")
+    private List<EnvVariable> env;
+
+    public PortainerStack() {}
+
+    public Long getId() {
+        return id;
+    }
+
+    public void setId(Long id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public Long getEndpointId() {
+        return endpointId;
+    }
+
+    public void setEndpointId(Long endpointId) {
+        this.endpointId = endpointId;
+    }
+
+    public int getStatus() {
+        return status;
+    }
+
+    public void setStatus(int status) {
+        this.status = status;
+    }
+
+    public Map<String, Object> getResourceControl() {
+        return resourceControl;
+    }
+
+    public void setResourceControl(Map<String, Object> resourceControl) {
+        this.resourceControl = resourceControl;
+    }
+
+    public List<EnvVariable> getEnv() {
+        return env;
+    }
+
+    public void setEnv(List<EnvVariable> env) {
+        this.env = env;
+    }
+}

common/src/main/java/com/hithomelabs/common/registry/model/ImageReference.java

@@ -0,0 +1,65 @@
+package com.hithomelabs.common.registry.model;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public class ImageReference {
+
+    private static final Pattern IMAGE_PATTERN =
+            Pattern.compile("^(?<registry>[^/]+)/(?<repository>[^:]+):(?<tag>.+)$");
+
+    private final String registry;
+    private final String repository;
+    private final String tag;
+    private final String fullImage;
+
+    private ImageReference(String registry, String repository, String tag, String fullImage) {
+        this.registry = registry;
+        this.repository = repository;
+        this.tag = tag;
+        this.fullImage = fullImage;
+    }
+
+    /**
+     * Parses a container image reference string of the form:
+     * {@code registry/repository:tag}
+     * e.g. {@code 192.168.0.100:8928/hithomelabs/cftunnels:1.2.3}
+     *
+     * @param image the full image reference string
+     * @return a parsed {@code ImageReference}
+     * @throws IllegalArgumentException if the string cannot be parsed
+     */
+    public static ImageReference parse(String image) {
+        if (image == null || image.isBlank()) {
+            throw new IllegalArgumentException("Image reference must not be null or blank");
+        }
+
+        Matcher matcher = IMAGE_PATTERN.matcher(image);
+        if (!matcher.matches()) {
+            throw new IllegalArgumentException(
+                    "Invalid image reference format. Expected '<registry>/<repository>:<tag>', got: " + image);
+        }
+
+        String registry = matcher.group("registry");
+        String repository = matcher.group("repository");
+        String tag = matcher.group("tag");
+
+        return new ImageReference(registry, repository, tag, image);
+    }
+
+    public String getRegistry() {
+        return registry;
+    }
+
+    public String getRepository() {
+        return repository;
+    }
+
+    public String getTag() {
+        return tag;
+    }
+
+    public String getFullImage() {
+        return fullImage;
+    }
+}

common/src/test/java/com/hithomelabs/common/portainer/client/PortainerApiClientTest.java

@@ -0,0 +1,505 @@
+package com.hithomelabs.common.portainer.client;
+
+import com.hithomelabs.common.portainer.client.exception.PortainerAuthenticationException;
+import com.hithomelabs.common.portainer.client.exception.PortainerConnectionException;
+import com.hithomelabs.common.portainer.client.exception.PortainerDeploymentException;
+import com.hithomelabs.common.portainer.client.exception.PortainerResourceNotFoundException;
+import com.hithomelabs.common.portainer.model.EnvVariable;
+import com.hithomelabs.common.portainer.model.PortainerAuthRequest;
+import com.hithomelabs.common.portainer.model.PortainerAuthResponse;
+import com.hithomelabs.common.portainer.model.PortainerRedeployRequest;
+import com.hithomelabs.common.portainer.model.PortainerStack;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.*;
+import org.springframework.web.client.HttpClientErrorException;
+import org.springframework.web.client.ResourceAccessException;
+import org.springframework.web.client.RestTemplate;
+
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class PortainerApiClientTest {
+
+    @Mock
+    private RestTemplate restTemplate;
+
+    private PortainerApiClient client;
+
+    private static final String BASE_URL = "http://portainer.local:9000";
+
+    @BeforeEach
+    void setUp() {
+        client = new PortainerApiClient(restTemplate, BASE_URL);
+    }
+
+    // -- authenticateWithPassword: success path --
+
+    @Test
+    void authenticateWithPassword_validCredentials_returnsAuthResponse() {
+        PortainerAuthResponse authResponse = new PortainerAuthResponse();
+        authResponse.setJwt("test-jwt-token");
+
+        ResponseEntity<PortainerAuthResponse> responseEntity = new ResponseEntity<>(
+                authResponse, HttpStatus.OK);
+
+        when(restTemplate.exchange(
+                eq(BASE_URL + "/api/auth"),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class)))
+                .thenReturn(responseEntity);
+
+        PortainerAuthResponse result = client.authenticateWithPassword("admin", "password123");
+
+        assertNotNull(result);
+        assertEquals("test-jwt-token", result.getJwt());
+        verify(restTemplate).exchange(
+                eq(BASE_URL + "/api/auth"),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class));
+    }
+
+    // -- authenticateWithPassword: input validation --
+
+    @Test
+    void authenticateWithPassword_nullUsername_throwsException() {
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword(null, "password"));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void authenticateWithPassword_blankUsername_throwsException() {
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword("  ", "password"));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void authenticateWithPassword_nullPassword_throwsException() {
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword("admin", null));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void authenticateWithPassword_blankPassword_throwsException() {
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword("admin", "  "));
+        verifyNoInteractions(restTemplate);
+    }
+
+    // -- authenticateWithPassword: HTTP error handling --
+
+    @Test
+    void authenticateWithPassword_http401_throwsAuthenticationException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class)))
+                .thenThrow(HttpClientErrorException.create(
+                        HttpStatus.UNAUTHORIZED,
+                        "Unauthorized",
+                        HttpHeaders.EMPTY,
+                        "Bad credentials".getBytes(StandardCharsets.UTF_8),
+                        StandardCharsets.UTF_8));
+
+        PortainerAuthenticationException ex = assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword("admin", "wrong"));
+        assertTrue(ex.getMessage().contains("401"));
+    }
+
+    @Test
+    void authenticateWithPassword_http403_throwsAuthenticationException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class)))
+                .thenThrow(HttpClientErrorException.create(
+                        HttpStatus.FORBIDDEN,
+                        "Forbidden",
+                        HttpHeaders.EMPTY,
+                        "Forbidden".getBytes(StandardCharsets.UTF_8),
+                        StandardCharsets.UTF_8));
+
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword("admin", "wrong"));
+    }
+
+    @Test
+    void authenticateWithPassword_connectionError_throwsConnectionException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class)))
+                .thenThrow(new ResourceAccessException("Connection refused"));
+
+        PortainerConnectionException ex = assertThrows(PortainerConnectionException.class,
+                () -> client.authenticateWithPassword("admin", "password"));
+        assertTrue(ex.getMessage().contains(BASE_URL));
+        assertTrue(ex.getMessage().contains("Connection refused"));
+    }
+
+    @Test
+    void authenticateWithPassword_nonOkStatus_throwsAuthenticationException() {
+        PortainerAuthResponse authResponse = new PortainerAuthResponse();
+        authResponse.setJwt("token");
+        // Return a non-OK status with null body to trigger the status check path
+        ResponseEntity<PortainerAuthResponse> responseEntity = new ResponseEntity<>(
+                null, HttpStatus.INTERNAL_SERVER_ERROR);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class)))
+                .thenReturn(responseEntity);
+
+        PortainerAuthenticationException ex = assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithPassword("admin", "password"));
+        assertTrue(ex.getMessage().contains("500"));
+    }
+
+    // -- authenticateWithApiKey: input validation --
+
+    @Test
+    void authenticateWithApiKey_nullKey_throwsException() {
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithApiKey(null));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void authenticateWithApiKey_blankKey_throwsException() {
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.authenticateWithApiKey("  "));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void authenticateWithApiKey_validKey_setsApiKey() {
+        client.authenticateWithApiKey("ptr_abc123def456");
+        // No exception expected; we verify it doesn't throw
+        // We can test this by calling a subsequent method that uses the API key
+        assertDoesNotThrow(() -> client.authenticateWithApiKey("ptr_abc123def456"));
+    }
+
+    // -- Constructor: trailing slash handling --
+
+    @Test
+    void constructor_withTrailingSlash_stripsIt() {
+        PortainerApiClient clientWithSlash = new PortainerApiClient(restTemplate, "http://portainer.local:9000/");
+        // authenticateWithPassword should use the stripped URL
+        PortainerAuthResponse authResponse = new PortainerAuthResponse();
+        authResponse.setJwt("token");
+        ResponseEntity<PortainerAuthResponse> responseEntity = new ResponseEntity<>(
+                authResponse, HttpStatus.OK);
+
+        when(restTemplate.exchange(
+                eq("http://portainer.local:9000/api/auth"),
+                eq(HttpMethod.POST),
+                any(HttpEntity.class),
+                eq(PortainerAuthResponse.class)))
+                .thenReturn(responseEntity);
+
+        PortainerAuthResponse result = clientWithSlash.authenticateWithPassword("admin", "pass");
+        assertNotNull(result);
+        assertEquals("token", result.getJwt());
+    }
+
+    @Test
+    void constructor_withNullBaseUrl_usesEmptyString() {
+        PortainerApiClient clientNullUrl = new PortainerApiClient(restTemplate, null);
+        // Should not throw; the client is created with an empty base URL
+        assertDoesNotThrow(() -> clientNullUrl.authenticateWithApiKey("key"));
+    }
+
+    // -----------------------------------------------------------
+    //  getStack
+    // -----------------------------------------------------------
+
+    @Test
+    void getStack_success_returnsPortainerStack() {
+        PortainerStack expected = new PortainerStack();
+        expected.setId(1L);
+        expected.setName("test-stack");
+        ResponseEntity<PortainerStack> responseEntity = new ResponseEntity<>(expected, HttpStatus.OK);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.GET),
+                any(HttpEntity.class),
+                eq(PortainerStack.class),
+                anyLong()))
+                .thenReturn(responseEntity);
+
+        PortainerStack result = client.getStack(1L);
+        assertNotNull(result);
+        assertEquals(1L, result.getId());
+        assertEquals("test-stack", result.getName());
+    }
+
+    @Test
+    void getStack_nullId_throwsException() {
+        assertThrows(PortainerDeploymentException.class,
+                () -> client.getStack(null));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void getStack_http404_throwsResourceNotFoundException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.GET),
+                any(HttpEntity.class),
+                eq(PortainerStack.class),
+                anyLong()))
+                .thenThrow(HttpClientErrorException.create(
+                        HttpStatus.NOT_FOUND,
+                        "Not Found",
+                        HttpHeaders.EMPTY,
+                        "Stack not found".getBytes(StandardCharsets.UTF_8),
+                        StandardCharsets.UTF_8));
+
+        assertThrows(PortainerResourceNotFoundException.class,
+                () -> client.getStack(1L));
+    }
+
+    @Test
+    void getStack_http401_throwsAuthenticationException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.GET),
+                any(HttpEntity.class),
+                eq(PortainerStack.class),
+                anyLong()))
+                .thenThrow(HttpClientErrorException.create(
+                        HttpStatus.UNAUTHORIZED,
+                        "Unauthorized",
+                        HttpHeaders.EMPTY,
+                        "Not authenticated".getBytes(StandardCharsets.UTF_8),
+                        StandardCharsets.UTF_8));
+
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.getStack(1L));
+    }
+
+    @Test
+    void getStack_connectionError_throwsConnectionException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.GET),
+                any(HttpEntity.class),
+                eq(PortainerStack.class),
+                anyLong()))
+                .thenThrow(new ResourceAccessException("Connection refused"));
+
+        PortainerConnectionException ex = assertThrows(PortainerConnectionException.class,
+                () -> client.getStack(1L));
+        assertTrue(ex.getMessage().contains(BASE_URL));
+    }
+
+    @Test
+    void getStack_nonOkStatus_throwsResourceNotFoundException() {
+        ResponseEntity<PortainerStack> responseEntity = new ResponseEntity<>(null, HttpStatus.NO_CONTENT);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.GET),
+                any(HttpEntity.class),
+                eq(PortainerStack.class),
+                anyLong()))
+                .thenReturn(responseEntity);
+
+        assertThrows(PortainerResourceNotFoundException.class,
+                () -> client.getStack(1L));
+    }
+
+    // -----------------------------------------------------------
+    //  redeployGitStack
+    // -----------------------------------------------------------
+
+    @Test
+    void redeployGitStack_success_returnsNormally() {
+        ResponseEntity<Void> responseEntity = new ResponseEntity<>(HttpStatus.OK);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenReturn(responseEntity);
+
+        assertDoesNotThrow(() -> client.redeployGitStack(1L, 2L, true, null));
+    }
+
+    @Test
+    void redeployGitStack_withEnvList_containsEnvInRequestBody() {
+        List<EnvVariable> envList = List.of(new EnvVariable("DB_HOST", "postgres"));
+        ResponseEntity<Void> responseEntity = new ResponseEntity<>(HttpStatus.OK);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenReturn(responseEntity);
+
+        client.redeployGitStack(1L, 2L, true, envList);
+
+        // Capture the request body to verify Env is included
+        ArgumentCaptor<HttpEntity<PortainerRedeployRequest>> captor = ArgumentCaptor.forClass(HttpEntity.class);
+        verify(restTemplate).exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                captor.capture(),
+                eq(Void.class),
+                anyLong(),
+                anyLong());
+
+        PortainerRedeployRequest capturedBody = captor.getValue().getBody();
+        assertNotNull(capturedBody);
+        assertTrue(capturedBody.isPullImage());
+        assertFalse(capturedBody.isPrune());
+        assertNotNull(capturedBody.getEnv());
+        assertEquals(1, capturedBody.getEnv().size());
+        assertEquals("DB_HOST", capturedBody.getEnv().get(0).getName());
+        assertEquals("postgres", capturedBody.getEnv().get(0).getValue());
+    }
+
+    @Test
+    void redeployGitStack_withNullEnv_requestBodyHasNullEnv() {
+        ResponseEntity<Void> responseEntity = new ResponseEntity<>(HttpStatus.OK);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenReturn(responseEntity);
+
+        client.redeployGitStack(1L, 2L, false, null);
+
+        ArgumentCaptor<HttpEntity<PortainerRedeployRequest>> captor = ArgumentCaptor.forClass(HttpEntity.class);
+        verify(restTemplate).exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                captor.capture(),
+                eq(Void.class),
+                anyLong(),
+                anyLong());
+
+        PortainerRedeployRequest capturedBody = captor.getValue().getBody();
+        assertNotNull(capturedBody);
+        assertFalse(capturedBody.isPullImage());
+        assertFalse(capturedBody.isPrune());
+        assertNull(capturedBody.getEnv());
+    }
+
+    @Test
+    void redeployGitStack_nullId_throwsException() {
+        assertThrows(PortainerDeploymentException.class,
+                () -> client.redeployGitStack(null, 2L, true, null));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void redeployGitStack_nullEndpointId_throwsException() {
+        assertThrows(PortainerDeploymentException.class,
+                () -> client.redeployGitStack(1L, null, true, null));
+        verifyNoInteractions(restTemplate);
+    }
+
+    @Test
+    void redeployGitStack_http404_throwsResourceNotFoundException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenThrow(HttpClientErrorException.create(
+                        HttpStatus.NOT_FOUND,
+                        "Not Found",
+                        HttpHeaders.EMPTY,
+                        "Stack not found".getBytes(StandardCharsets.UTF_8),
+                        StandardCharsets.UTF_8));
+
+        assertThrows(PortainerResourceNotFoundException.class,
+                () -> client.redeployGitStack(1L, 2L, true, null));
+    }
+
+    @Test
+    void redeployGitStack_http401_throwsAuthenticationException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenThrow(HttpClientErrorException.create(
+                        HttpStatus.UNAUTHORIZED,
+                        "Unauthorized",
+                        HttpHeaders.EMPTY,
+                        "Not authenticated".getBytes(StandardCharsets.UTF_8),
+                        StandardCharsets.UTF_8));
+
+        assertThrows(PortainerAuthenticationException.class,
+                () -> client.redeployGitStack(1L, 2L, true, null));
+    }
+
+    @Test
+    void redeployGitStack_connectionError_throwsConnectionException() {
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenThrow(new ResourceAccessException("Connection refused"));
+
+        PortainerConnectionException ex = assertThrows(PortainerConnectionException.class,
+                () -> client.redeployGitStack(1L, 2L, true, null));
+        assertTrue(ex.getMessage().contains(BASE_URL));
+    }
+
+    @Test
+    void redeployGitStack_nonOkStatus_throwsDeploymentException() {
+        ResponseEntity<Void> responseEntity = new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
+
+        when(restTemplate.exchange(
+                anyString(),
+                eq(HttpMethod.PUT),
+                any(HttpEntity.class),
+                eq(Void.class),
+                anyLong(),
+                anyLong()))
+                .thenReturn(responseEntity);
+
+        assertThrows(PortainerDeploymentException.class,
+                () -> client.redeployGitStack(1L, 2L, true, null));
+    }
+}

common/src/test/java/com/hithomelabs/common/portainer/model/EnvVariableTest.java

@@ -0,0 +1,66 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class EnvVariableTest {
+
+    private final ObjectMapper mapper = new ObjectMapper();
+
+    @Test
+    void serialize() throws JsonProcessingException {
+        EnvVariable env = new EnvVariable("FOO", "bar");
+        String json = mapper.writeValueAsString(env);
+        assertEquals("{\"name\":\"FOO\",\"value\":\"bar\"}", json);
+    }
+
+    @Test
+    void deserialize() throws JsonProcessingException {
+        String json = "{\"name\":\"FOO\",\"value\":\"bar\"}";
+        EnvVariable env = mapper.readValue(json, EnvVariable.class);
+        assertEquals("FOO", env.getName());
+        assertEquals("bar", env.getValue());
+    }
+
+    @Test
+    void nullName() throws JsonProcessingException {
+        EnvVariable env = new EnvVariable(null, "value");
+        String json = mapper.writeValueAsString(env);
+        assertEquals("{\"name\":null,\"value\":\"value\"}", json);
+    }
+
+    @Test
+    void nullValue() throws JsonProcessingException {
+        EnvVariable env = new EnvVariable("name", null);
+        String json = mapper.writeValueAsString(env);
+        assertEquals("{\"name\":\"name\",\"value\":null}", json);
+    }
+
+    @Test
+    void roundTripWithNulls() throws JsonProcessingException {
+        EnvVariable env = new EnvVariable(null, null);
+        String json = mapper.writeValueAsString(env);
+        EnvVariable deserialized = mapper.readValue(json, EnvVariable.class);
+        assertNull(deserialized.getName());
+        assertNull(deserialized.getValue());
+    }
+
+    @Test
+    void constructorAndGetters() {
+        EnvVariable env = new EnvVariable("KEY", "val");
+        assertEquals("KEY", env.getName());
+        assertEquals("val", env.getValue());
+    }
+
+    @Test
+    void setters() {
+        EnvVariable env = new EnvVariable();
+        env.setName("A");
+        env.setValue("B");
+        assertEquals("A", env.getName());
+        assertEquals("B", env.getValue());
+    }
+}

common/src/test/java/com/hithomelabs/common/portainer/model/ModelSerializationTest.java

@@ -0,0 +1,121 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Full round-trip contract test for Portainer model serialization.
+ * <p>
+ * Takes a realistic Portainer API JSON response, deserializes into
+ * {@link PortainerStack}, extracts the env list, creates a
+ * {@link PortainerRedeployRequest} with it, serializes back to JSON,
+ * and asserts the correct structure and values.
+ */
+class ModelSerializationTest {
+
+    private final ObjectMapper mapper = new ObjectMapper();
+
+    @Test
+    void fullEnvRoundTrip() throws JsonProcessingException {
+        // Step 1: Realistic Portainer API JSON response with Env array and ResourceControl
+        String portainerJson = """
+                {
+                    "Id": 42,
+                    "Name": "my-app-stack",
+                    "EndpointId": 2,
+                    "Status": 1,
+                    "Env": [
+                        {"name":"DB_HOST","value":"postgres.internal"},
+                        {"name":"DB_PORT","value":"5432"},
+                        {"name":"REDIS_URL","value":"redis://cache:6379"}
+                    ],
+                    "ResourceControl": {
+                        "Id": 1,
+                        "Type": 2,
+                        "Owner": "admin"
+                    }
+                }
+                """;
+
+        // Step 2: Deserialize into PortainerStack
+        PortainerStack stack = mapper.readValue(portainerJson, PortainerStack.class);
+        assertNotNull(stack, "Deserialized stack must not be null");
+        assertEquals(42L, stack.getId().longValue());
+        assertEquals("my-app-stack", stack.getName());
+        assertNotNull(stack.getResourceControl());
+        assertEquals(1, stack.getResourceControl().get("Id"));
+
+        // Step 3: Extract the env list
+        List<EnvVariable> envList = stack.getEnv();
+        assertNotNull(envList, "Env list must not be null");
+        assertEquals(3, envList.size());
+        assertEquals("DB_HOST", envList.get(0).getName());
+        assertEquals("postgres.internal", envList.get(0).getValue());
+        assertEquals("DB_PORT", envList.get(1).getName());
+        assertEquals("5432", envList.get(1).getValue());
+        assertEquals("REDIS_URL", envList.get(2).getName());
+        assertEquals("redis://cache:6379", envList.get(2).getValue());
+
+        // Step 4: Create a PortainerRedeployRequest with that env list (3-arg constructor)
+        PortainerRedeployRequest redeployRequest = new PortainerRedeployRequest(true, false, envList);
+
+        // Step 5: Serialize it back to JSON
+        String requestJson = mapper.writeValueAsString(redeployRequest);
+
+        // Step 6: Assert JSON contains correct key/value pairs
+        // Assert top-level fields
+        assertTrue(requestJson.contains("\"PullImage\":true"),
+                "JSON must contain PullImage:true");
+        assertTrue(requestJson.contains("\"Prune\":false"),
+                "JSON must contain Prune:false");
+
+        // Assert the Env array is present
+        assertTrue(requestJson.contains("\"Env\""),
+                "JSON must contain Env field");
+
+        // Assert correct name/value casing (JsonProperty annotations)
+        assertTrue(requestJson.contains("\"name\":\"DB_HOST\""),
+                "JSON must contain name:DB_HOST");
+        assertTrue(requestJson.contains("\"value\":\"postgres.internal\""),
+                "JSON must contain value:postgres.internal");
+        assertTrue(requestJson.contains("\"name\":\"DB_PORT\""),
+                "JSON must contain name:DB_PORT");
+        assertTrue(requestJson.contains("\"value\":\"5432\""),
+                "JSON must contain value:5432");
+        assertTrue(requestJson.contains("\"name\":\"REDIS_URL\""),
+                "JSON must contain name:REDIS_URL");
+        assertTrue(requestJson.contains("\"value\":\"redis://cache:6379\""),
+                "JSON must contain value:redis://cache:6379");
+    }
+
+    @Test
+    void redeployRequestWithNullEnv() throws JsonProcessingException {
+        // Verify that a PortainerRedeployRequest with null env serializes without NPE
+        PortainerRedeployRequest request = new PortainerRedeployRequest(false, true, null);
+        String json = mapper.writeValueAsString(request);
+        assertTrue(json.contains("\"PullImage\":false"));
+        assertTrue(json.contains("\"Prune\":true"));
+        // Env may be serialized as null or omitted
+    }
+
+    @Test
+    void redeployRequestRoundTrip() throws JsonProcessingException {
+        // Full round-trip: serialize PortainerRedeployRequest and deserialize back
+        List<EnvVariable> envList = List.of(new EnvVariable("KEY", "VALUE"));
+        PortainerRedeployRequest original = new PortainerRedeployRequest(true, true, envList);
+        String json = mapper.writeValueAsString(original);
+        PortainerRedeployRequest deserialized = mapper.readValue(json, PortainerRedeployRequest.class);
+
+        assertTrue(deserialized.isPullImage());
+        assertTrue(deserialized.isPrune());
+        assertNotNull(deserialized.getEnv());
+        assertEquals(1, deserialized.getEnv().size());
+        assertEquals("KEY", deserialized.getEnv().get(0).getName());
+        assertEquals("VALUE", deserialized.getEnv().get(0).getValue());
+    }
+}

common/src/test/java/com/hithomelabs/common/portainer/model/PortainerStackTest.java

@@ -0,0 +1,101 @@
+package com.hithomelabs.common.portainer.model;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class PortainerStackTest {
+
+    private final ObjectMapper mapper = new ObjectMapper();
+
+    @Test
+    void deserializeWithEnv() throws JsonProcessingException {
+        String json = """
+                {
+                    "Id": 1,
+                    "Name": "test-stack",
+                    "Env": [{"name":"DB_HOST","value":"postgres"}]
+                }
+                """;
+        PortainerStack stack = mapper.readValue(json, PortainerStack.class);
+        assertEquals(1L, stack.getId());
+        assertEquals("test-stack", stack.getName());
+        assertNotNull(stack.getEnv());
+        assertEquals(1, stack.getEnv().size());
+        assertEquals("DB_HOST", stack.getEnv().get(0).getName());
+        assertEquals("postgres", stack.getEnv().get(0).getValue());
+    }
+
+    @Test
+    void deserializeWithResourceControl() throws JsonProcessingException {
+        String json = """
+                {
+                    "Id": 1,
+                    "ResourceControl": {"Id":1,"Type":2}
+                }
+                """;
+        PortainerStack stack = mapper.readValue(json, PortainerStack.class);
+        assertNotNull(stack.getResourceControl());
+        assertEquals(1, stack.getResourceControl().get("Id"));
+        assertEquals(2, stack.getResourceControl().get("Type"));
+    }
+
+    @Test
+    void deserializeWithNullResourceControl() throws JsonProcessingException {
+        String json = """
+                {
+                    "Id": 1,
+                    "ResourceControl": null
+                }
+                """;
+        PortainerStack stack = mapper.readValue(json, PortainerStack.class);
+        assertNull(stack.getResourceControl());
+    }
+
+    @Test
+    void deserializeWithoutEnv() throws JsonProcessingException {
+        String json = """
+                {
+                    "Id": 1,
+                    "Name": "test-stack"
+                }
+                """;
+        PortainerStack stack = mapper.readValue(json, PortainerStack.class);
+        // When no "Env" field is present in JSON, the field should remain null
+        assertNull(stack.getEnv());
+    }
+
+    @Test
+    void deserializeWithMultipleEnvVars() throws JsonProcessingException {
+        String json = """
+                {
+                    "Id": 2,
+                    "Env": [
+                        {"name":"DB_HOST","value":"postgres"},
+                        {"name":"DB_PORT","value":"5432"},
+                        {"name":"REDIS_URL","value":"redis://cache:6379"}
+                    ]
+                }
+                """;
+        PortainerStack stack = mapper.readValue(json, PortainerStack.class);
+        assertNotNull(stack.getEnv());
+        assertEquals(3, stack.getEnv().size());
+        assertEquals("DB_PORT", stack.getEnv().get(1).getName());
+        assertEquals("redis://cache:6379", stack.getEnv().get(2).getValue());
+    }
+
+    @Test
+    void deserializeWithEmptyEnv() throws JsonProcessingException {
+        String json = """
+                {
+                    "Id": 3,
+                    "Env": []
+                }
+                """;
+        PortainerStack stack = mapper.readValue(json, PortainerStack.class);
+        assertNotNull(stack.getEnv());
+        assertTrue(stack.getEnv().isEmpty());
+    }
+}

common/src/test/java/com/hithomelabs/common/registry/model/ImageReferenceTest.java

@@ -0,0 +1,107 @@
+package com.hithomelabs.common.registry.model;
+
+import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.*;
+
+class ImageReferenceTest {
+
+    @Test
+    void parse_withValidImage_returnsImageReference() {
+        ImageReference ref = ImageReference.parse("192.168.0.100:8928/hithomelabs/cftunnels:1.2.3");
+
+        assertNotNull(ref);
+        assertEquals("192.168.0.100:8928", ref.getRegistry());
+        assertEquals("hithomelabs/cftunnels", ref.getRepository());
+        assertEquals("1.2.3", ref.getTag());
+        assertEquals("192.168.0.100:8928/hithomelabs/cftunnels:1.2.3", ref.getFullImage());
+    }
+
+    @Test
+    void parse_withRegistryPortAndMultiLevelRepository_returnsImageReference() {
+        ImageReference ref = ImageReference.parse("registry.example.com:5000/namespace/sub/image:latest");
+
+        assertNotNull(ref);
+        assertEquals("registry.example.com:5000", ref.getRegistry());
+        assertEquals("namespace/sub/image", ref.getRepository());
+        assertEquals("latest", ref.getTag());
+    }
+
+    @Test
+    void parse_withSimpleRegistryPath_returnsImageReference() {
+        ImageReference ref = ImageReference.parse("docker.io/library/nginx:1.25");
+
+        assertNotNull(ref);
+        assertEquals("docker.io", ref.getRegistry());
+        assertEquals("library/nginx", ref.getRepository());
+        assertEquals("1.25", ref.getTag());
+    }
+
+    @Test
+    void parse_withNumericTag_returnsImageReference() {
+        ImageReference ref = ImageReference.parse("myregistry.com/myapp:1");
+
+        assertNotNull(ref);
+        assertEquals("myregistry.com", ref.getRegistry());
+        assertEquals("myapp", ref.getRepository());
+        assertEquals("1", ref.getTag());
+    }
+
+    @Test
+    void parse_withTagContainingHyphenAndDot_returnsImageReference() {
+        ImageReference ref = ImageReference.parse("private.reg.io/team-app:3.2.1-rc1");
+
+        assertNotNull(ref);
+        assertEquals("private.reg.io", ref.getRegistry());
+        assertEquals("team-app", ref.getRepository());
+        assertEquals("3.2.1-rc1", ref.getTag());
+    }
+
+    @Test
+    void parse_withNullImage_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse(null));
+        assertTrue(ex.getMessage().contains("null") || ex.getMessage().contains("blank"));
+    }
+
+    @Test
+    void parse_withBlankImage_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse("   "));
+        assertTrue(ex.getMessage().contains("null") || ex.getMessage().contains("blank"));
+    }
+
+    @Test
+    void parse_withEmptyImage_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse(""));
+        assertTrue(ex.getMessage().contains("null") || ex.getMessage().contains("blank"));
+    }
+
+    @Test
+    void parse_withMissingRegistry_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse("nginx:latest"));
+        assertTrue(ex.getMessage().contains("Invalid"));
+    }
+
+    @Test
+    void parse_withMissingTag_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse("registry.com/repo"));
+        assertTrue(ex.getMessage().contains("Invalid"));
+    }
+
+    @Test
+    void parse_withMissingColonSeparator_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse("registry.com/repo:"));
+        assertTrue(ex.getMessage().contains("Invalid"));
+    }
+
+    @Test
+    void parse_withOnlyRegistry_throwsIllegalArgumentException() {
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> ImageReference.parse("registry.com"));
+        assertTrue(ex.getMessage().contains("Invalid"));
+    }
+}

docker-compose.yaml

@@ -4,6 +4,7 @@ services:
     container_name: cftunnels_${ENV}
     ports:
       - ${HOST_PORT}:8080
+      - ${MGMT_PORT:-5003}:8081
     environment:
       - CLOUDFLARE_ACCOUNT_ID=${CLOUDFLARE_ACCOUNT_ID}
       - CLOUDFLARE_API_KEY=${CLOUDFLARE_API_KEY}
@@ -29,4 +30,4 @@ services:
     ports:
       - "${DB_PORT}:5432"
     volumes:
-      - ${DB_PATH}:/var/lib/postgresql/data
+      - ${DB_PATH}:/var/lib/postgresql/data

portainer-automation/.env.example

@@ -0,0 +1,41 @@
+# ============================================
+# Portainer Automation Service — Environment Variables
+# ============================================
+# Copy this file to .env and fill in your values.
+# This service is NOT exposed via Cloudflare Tunnel (internal-only).
+
+# --- Portainer Connection ---
+
+# Portainer API Key for the target Portainer instance
+# Create via Portainer UI: Settings → Authentication → Access tokens
+# Dev: https://devdocker.hithomelabs.com  →  ptk_xxxx_dev_xxxx
+# Prod: https://192.168.0.100:9443        →  ptk_xxxx_prod_xxxx
+PORTAINER_API_KEY=ptr_your_portainer_api_key_here
+
+# Portainer endpoint ID (1 = primary Docker endpoint, 2 = remote)
+PORTAINER_ENDPOINT_ID=2
+
+# --- Service Auth ---
+
+# API key that CI workflows send in the X-API-Key header
+# to authenticate against this service's /api/deploy endpoint
+PORTAINER_SERVICE_API_KEY=change-me
+
+# --- Spring Profile ---
+
+# Active Spring profile (local | ci | prod)
+#   local — uses devdocker.hithomelabs.com via Cloudflare Tunnel (default)
+#   ci    — uses test/stub endpoints
+#   prod  — uses production Portainer on internal network
+SPRING_PROFILES_ACTIVE=local
+
+# --- Deployment ---
+
+# Deployment environment label (dev | test | prod)
+ENV=dev
+
+# Host port to map to container port 8081
+HOST_PORT=8081
+
+# Host port to map to actuator management port 8082 (health checks, LAN only)
+MGMT_PORT=5005

portainer-automation/Dockerfile

@@ -0,0 +1,13 @@
+FROM openjdk:17-jdk as build
+WORKDIR /app
+COPY gradlew settings.gradle build.gradle ./
+COPY gradle ./gradle
+COPY common ./common
+COPY cftunnels-service ./cftunnels-service
+COPY portainer-automation ./portainer-automation
+RUN ./gradlew :portainer-automation:bootJar
+
+FROM openjdk:17-jdk-slim
+COPY --from=build /app/portainer-automation/build/libs/*.jar app.jar
+EXPOSE 8081 8082
+ENTRYPOINT ["java", "-jar", "/app.jar"]

portainer-automation/PORTAINER_STACK.md

@@ -0,0 +1,224 @@
+# Portainer Automation Service — Portainer Stack Guide
+
+## Overview
+
+The Portainer Automation service exposes a single endpoint (`POST /api/deploy/{stackId}`)
+that triggers a redeploy of a Portainer stack. CI workflows call this endpoint after
+pushing new container images.
+
+The service is deployed as a **separate Portainer stack** (Option B) — independent from
+the CFTunnels stacks — so it can be reused by other projects.
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────┐     push tag     ┌──────────────────┐
+│  Gitea Runner   │ ──────────────►  │  Docker Registry  │
+│ (CI workflow)   │                  │  :8928            │
+└────────┬────────┘                  └──────────────────┘
+         │
+         │ POST /api/deploy/{stackId}
+         │ X-API-Key: <service-api-key>
+         ▼
+┌─────────────────────────────────────┐
+│  Portainer Automation Service      │
+│  (portainer-automation_${ENV})     │
+│  port: 8081                         │
+└──────────┬──────────────────────────┘
+           │ PUT /api/stacks/{id}/git/redeploy
+           │ X-API-Key: <portainer-api-key>
+           ▼
+┌─────────────────────────────────────┐
+│  Portainer CE                       │
+│  Dev: :9442 / Prod: :9443          │
+└──────────┬──────────────────────────┘
+           │ git pull + stack redeploy
+           ▼
+┌─────────────────────────────────────┐
+│  Target Stack (e.g. CFTunnels)     │
+│  Docker Compose from Git           │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Portainer Stack Configuration
+
+### Create a New Stack in Portainer
+
+1. **Navigate**: Portainer UI → Stacks → **Add stack**
+2. **Name**: `portainer-automation-{env}` (e.g. `portainer-automation-dev`)
+3. **Build method**: **Git repository**
+4. **Repository URL**: `https://gitea.hithomelabs.com/Hithomelabs/CFTunnels.git`
+5. **Repository reference**: `refs/heads/test` (dev) or `refs/heads/main` (prod)
+6. **Compose path**: `portainer-automation/docker-compose.yaml`
+7. **Environment variables**: See table below
+
+### Environment Variables — Dev
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `ENV` | `dev` | Environment label |
+| `HOST_PORT` | `8081` | Host port mapping |
+| `SPRING_PROFILES_ACTIVE` | `local` | Spring profile (uses `devdocker.hithomelabs.com`) |
+| `PORTAINER_API_KEY` | `ptk_xxxx_dev_xxxx` | Portainer Dev API access token |
+| `PORTAINER_SERVICE_API_KEY` | *(generate a random key)* | CI → Service auth key |
+
+Portainer Dev endpoint: `https://devdocker.hithomelabs.com` (port 9442 behind Cloudflare Tunnel)
+
+### Environment Variables — Prod
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `ENV` | `prod` | Environment label |
+| `HOST_PORT` | `8082` | Host port mapping |
+| `SPRING_PROFILES_ACTIVE` | `prod` | Spring profile (uses `192.168.0.100:9443`) |
+| `PORTAINER_API_KEY` | `ptk_xxxx_prod_xxxx` | Portainer Prod API access token |
+| `PORTAINER_SERVICE_API_KEY` | *(generate a different random key)* | CI → Service auth key |
+
+Portainer Prod endpoint: `https://192.168.0.100:9443` (internal network)
+
+---
+
+## Deployment Steps
+
+### Prerequisites
+
+1. Portainer Automation Docker image is built and pushed (see CI workflow)
+2. Portainer API access tokens created (Portainer UI → My access tokens)
+3. Gitea secrets configured:
+   - `PORTAINER_SERVICE_API_KEY` — shared secret for dev
+   - `PORTAINER_SERVICE_API_KEY_PROD` — shared secret for prod
+
+### Step 1: Build and Push Image
+
+The CI workflow `.gitea/workflows/portainer_automation_build_push.yml` handles this
+automatically on push to the `test` branch.
+
+To build manually:
+```bash
+./gradlew :portainer-automation:bootBuildImage \
+  --imageName=192.168.0.100:8928/hithomelabs/portainer-automation:<version>
+```
+
+### Step 2: Create Stack in Portainer (Dev)
+
+1. Log in to Portainer Dev (`https://devdocker.hithomelabs.com`)
+2. Stacks → Add stack
+3. Name: `portainer-automation-dev`
+4. Build method: Git repository
+5. Repository: `https://gitea.hithomelabs.com/Hithomelabs/CFTunnels.git`
+6. Reference: `refs/heads/test`
+7. Compose path: `portainer-automation/docker-compose.yaml`
+8. Add env vars from the **Dev** table above
+9. Click **Deploy the stack**
+
+### Step 3: Verify Dev Deployment
+
+```bash
+# Redeploy a stack via the automation service
+curl -X POST \
+  -H "X-API-Key: <service-api-key>" \
+  http://portainer-automation-dev:8081/api/deploy/<stack-id>
+
+# Expected: "Deployment initiated for stack <stack-id>"
+```
+
+### Step 4: Create Stack in Portainer (Prod)
+
+1. Log in to Portainer Prod (`https://192.168.0.100:9443`)
+2. Follow the same steps as Step 2, with:
+   - Name: `portainer-automation-prod`
+   - Reference: `refs/heads/main`
+   - Env vars from the **Prod** table above
+
+### Step 5: Wire CI Triggers
+
+Ensure CI workflows call the automation endpoint:
+
+**Dev** (in `test_image_build_push.yml`):
+```yaml
+- name: Trigger Portainer Redeploy (Dev)
+  if: success()
+  env:
+    PORTAINER_AUTOMATION_URL: "http://portainer-automation-dev:8081"
+    STACK_ID: ${{ vars.PORTAINER_AUTOMATION_DEV_STACK_ID }}
+    API_KEY: ${{ secrets.PORTAINER_SERVICE_API_KEY }}
+  run: |
+    wget -q --no-check-certificate --timeout=30 \
+      --header="X-API-Key: $API_KEY" \
+      -O - \
+      "$PORTAINER_AUTOMATION_URL/api/deploy/$STACK_ID" 2>&1 \
+      || echo "Deploy trigger failed (non-fatal)"
+```
+
+**Prod** (in `prod_image_tag_promote.yaml`):
+```yaml
+- name: Trigger Portainer Redeploy (Prod)
+  if: success()
+  env:
+    PORTAINER_AUTOMATION_URL: "http://portainer-automation-prod:8082"
+    STACK_ID: ${{ vars.PORTAINER_AUTOMATION_PROD_STACK_ID }}
+    API_KEY: ${{ secrets.PORTAINER_SERVICE_API_KEY_PROD }}
+  run: |
+    wget -q --no-check-certificate --timeout=30 \
+      --header="X-API-Key: $API_KEY" \
+      -O - \
+      "$PORTAINER_AUTOMATION_URL/api/deploy/$STACK_ID" 2>&1 \
+      || echo "Deploy trigger failed (non-fatal)"
+```
+
+---
+
+## Configuration Reference
+
+### Profile Resolution Order
+
+The service resolves configuration in this order (later overrides earlier):
+
+1. `application.properties` — default: `https://192.168.0.100:9442`
+2. `application-{profile}.properties` — profile-specific overrides
+3. Environment variables — highest priority
+
+### Profile Purposes
+
+| Profile | File | Portainer Target | Use Case |
+|---------|------|-----------------|----------|
+| default | `application.properties` | `192.168.0.100:9442` (Dev) | CI/CD, Docker compose |
+| `local` | `application-local.properties` | `devdocker.hithomelabs.com` | Local dev via Cloudflare Tunnel |
+| `ci` | `application-ci.properties` | `portainer-test:9000` | CI pipeline testing |
+| `prod` | `application-prod.properties` | `192.168.0.100:9443` (Prod) | Production deployment |
+
+### Environment Variable Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SPRING_PROFILES_ACTIVE` | No | *(none)* | Active Spring profile |
+| `PORTAINER_API_KEY` | Yes | — | Portainer API access token |
+| `PORTAINER_SERVICE_API_KEY` | Yes | — | Shared secret for CI → service auth |
+| `ENV` | No | `test` | Deployment environment label |
+| `HOST_PORT` | No | `8081` | External port mapping |
+
+---
+
+## Health Checks
+
+The service exposes no dedicated health endpoint yet. Verify availability by:
+
+```bash
+# Check that the service responds (expects 401 Unauthorized without API key)
+curl -X POST http://portainer-automation-dev:8081/api/deploy/1
+# Expected: {"timestamp":"...","status":401,"error":"Unauthorized",...}
+# A 401 response means the service is running.
+```
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| `Connection refused` | Service not running | Check stack status in Portainer |
+| `Invalid API key` | Wrong `PORTAINER_SERVICE_API_KEY` | Verify env var matches CI secret |
+| `Portainer error: Unauthorized` | Wrong `PORTAINER_API_KEY` | Regenerate token in Portainer UI |
+| `Stack not found` | Wrong stack ID | Verify stack ID in Portainer URL |

portainer-automation/build.gradle

@@ -5,6 +5,8 @@ dependencies {
 
     implementation 'org.springframework.boot:spring-boot-starter-web'
     implementation 'org.springframework.boot:spring-boot-starter-validation'
+    implementation 'org.springframework.boot:spring-boot-starter-actuator'
+    implementation 'org.apache.httpcomponents.client5:httpclient5'
 
     compileOnly 'org.projectlombok:lombok'
     annotationProcessor 'org.projectlombok:lombok'

portainer-automation/docker-compose.yaml

@@ -0,0 +1,14 @@
+services:
+  portainer-automation:
+    image: gitea.hithomelabs.com/hithomelabs/portainer-automation:${ENV:-test}
+    container_name: portainer-automation_${ENV:-test}
+    ports:
+      - "${HOST_PORT:-8081}:8081"   # Application port (internal service)
+      - "${MGMT_PORT:-5005}:8082"   # Health management port (LAN only)
+    environment:
+      - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES_ACTIVE:-local}
+      - PORTAINER_API_KEY=${PORTAINER_API_KEY}
+      - PORTAINER_SERVICE_API_KEY=${PORTAINER_SERVICE_API_KEY}
+    env_file:
+      - ../stack.env
+    restart: unless-stopped

portainer-automation/src/main/java/com/hithomelabs/portainer/PortainerAutomationApplication.java

@@ -2,8 +2,12 @@ package com.hithomelabs.portainer;
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
 
-@SpringBootApplication
+import com.hithomelabs.portainer.config.PortainerAutomationProperties;
+
+@SpringBootApplication(scanBasePackages = {"com.hithomelabs.portainer", "com.hithomelabs.common"})
+@EnableConfigurationProperties(PortainerAutomationProperties.class)
 public class PortainerAutomationApplication {
 
     public static void main(String[] args) {

portainer-automation/src/main/java/com/hithomelabs/portainer/config/PortainerAutomationProperties.java

@@ -0,0 +1,55 @@
+package com.hithomelabs.portainer.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = "portainer")
+public class PortainerAutomationProperties {
+    private String baseUrl;
+    private String apiKey;
+    private Long endpointId;
+    private Service service = new Service();
+
+    public String getBaseUrl() {
+        return baseUrl;
+    }
+
+    public void setBaseUrl(String baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+
+    public String getApiKey() {
+        return apiKey;
+    }
+
+    public void setApiKey(String apiKey) {
+        this.apiKey = apiKey;
+    }
+
+    public Long getEndpointId() {
+        return endpointId;
+    }
+
+    public void setEndpointId(Long endpointId) {
+        this.endpointId = endpointId;
+    }
+
+    public Service getService() {
+        return service;
+    }
+
+    public void setService(Service service) {
+        this.service = service;
+    }
+
+    public static class Service {
+        private String apiKey;
+
+        public String getApiKey() {
+            return apiKey;
+        }
+
+        public void setApiKey(String apiKey) {
+            this.apiKey = apiKey;
+        }
+    }
+}

portainer-automation/src/main/java/com/hithomelabs/portainer/config/PortainerClientConfig.java

@@ -0,0 +1,85 @@
+package com.hithomelabs.portainer.config;
+
+import org.apache.hc.client5.http.impl.classic.HttpClients;
+import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder;
+import org.apache.hc.client5.http.io.HttpClientConnectionManager;
+import org.apache.hc.client5.http.ssl.NoopHostnameVerifier;
+import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactory;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
+import org.springframework.web.client.RestTemplate;
+
+import com.hithomelabs.common.portainer.client.PortainerApiClient;
+
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.TrustManager;
+import javax.net.ssl.X509TrustManager;
+import java.security.cert.X509Certificate;
+
+@Configuration
+public class PortainerClientConfig {
+
+    /**
+     * Builds a RestTemplate that trusts all SSL certificates.
+     * Used when connecting via Cloudflare Tunnel (self-signed certs)
+     * or to the prod Portainer instance (also self-signed).
+     */
+    private static RestTemplate buildTrustAllRestTemplate() throws Exception {
+        TrustManager[] trustAllCerts = new TrustManager[]{
+                new X509TrustManager() {
+                    public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; }
+                    public void checkClientTrusted(X509Certificate[] certs, String authType) {}
+                    public void checkServerTrusted(X509Certificate[] certs, String authType) {}
+                }
+        };
+        SSLContext sslContext = SSLContext.getInstance("TLS");
+        sslContext.init(null, trustAllCerts, new java.security.SecureRandom());
+        SSLConnectionSocketFactory sslSocketFactory =
+                new SSLConnectionSocketFactory(sslContext, NoopHostnameVerifier.INSTANCE);
+        HttpClientConnectionManager cm = PoolingHttpClientConnectionManagerBuilder.create()
+                .setSSLSocketFactory(sslSocketFactory)
+                .build();
+        return new RestTemplate(new HttpComponentsClientHttpRequestFactory(
+                HttpClients.custom().setConnectionManager(cm).build()));
+    }
+
+    /**
+     * Trust-all SSL RestTemplate for the "local" profile.
+     * Used when connecting via Cloudflare Tunnel (self-signed certs).
+     */
+    @Profile("local")
+    @Bean(name = "portainerRestTemplate")
+    public RestTemplate portainerRestTemplateLocal() throws Exception {
+        return buildTrustAllRestTemplate();
+    }
+
+    /**
+     * Trust-all SSL RestTemplate for the "prod" profile.
+     * Prod Portainer at https://192.168.0.100:9443 uses a self-signed certificate.
+     */
+    @Profile("prod")
+    @Bean(name = "portainerRestTemplate")
+    public RestTemplate portainerRestTemplateProd() throws Exception {
+        return buildTrustAllRestTemplate();
+    }
+
+    /**
+     * Standard validating SSL RestTemplate for profiles other than local and prod
+     * (CI, test — internal Docker network with valid certs).
+     */
+    @Profile("!local & !prod")
+    @Bean(name = "portainerRestTemplate")
+    public RestTemplate portainerRestTemplateDefault() {
+        return new RestTemplate();
+    }
+
+    @Bean
+    public PortainerApiClient portainerApiClient(PortainerAutomationProperties props,
+                                                  RestTemplate portainerRestTemplate) {
+        PortainerApiClient client = new PortainerApiClient(portainerRestTemplate, props.getBaseUrl());
+        client.authenticateWithApiKey(props.getApiKey());
+        return client;
+    }
+}

portainer-automation/src/main/java/com/hithomelabs/portainer/controller/DeployController.java

@@ -0,0 +1,75 @@
+package com.hithomelabs.portainer.controller;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.hithomelabs.common.portainer.client.exception.PortainerAuthenticationException;
+import com.hithomelabs.common.portainer.client.exception.PortainerConnectionException;
+import com.hithomelabs.common.portainer.client.exception.PortainerDeploymentException;
+import com.hithomelabs.common.portainer.client.exception.PortainerResourceNotFoundException;
+import com.hithomelabs.portainer.config.PortainerAutomationProperties;
+import com.hithomelabs.portainer.service.DeployService;
+
+@RestController
+@RequestMapping("/api")
+public class DeployController {
+
+    private static final Logger log = LoggerFactory.getLogger(DeployController.class);
+
+    private final DeployService deployService;
+    private final PortainerAutomationProperties props;
+
+    public DeployController(DeployService deployService, PortainerAutomationProperties props) {
+        this.deployService = deployService;
+        this.props = props;
+    }
+
+    @GetMapping("/health")
+    public ResponseEntity<String> health() {
+        return ResponseEntity.ok("{\"status\":\"UP\"}");
+    }
+
+    @PostMapping("/deploy/{stackId}")
+    public ResponseEntity<String> deploy(@PathVariable Long stackId,
+                                          @RequestHeader(value = "X-API-Key", required = false) String apiKey) {
+        String expectedApiKey = props.getService().getApiKey();
+        if (expectedApiKey == null || !expectedApiKey.equals(apiKey)) {
+            log.warn("Deploy auth failed for stack {}: invalid API key", stackId);
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Invalid API key");
+        }
+        log.info("Deployment requested for stack {}", stackId);
+        try {
+            deployService.redeploy(stackId);
+            log.info("Deployment initiated for stack {}", stackId);
+            return ResponseEntity.ok("Deployment initiated for stack " + stackId);
+        } catch (PortainerConnectionException e) {
+            log.error("Portainer connection error for stack {}: {}", stackId, e.getMessage());
+            return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+                    .body("Portainer connection failed: " + e.getMessage());
+        } catch (PortainerResourceNotFoundException e) {
+            log.error("Stack {} not found: {}", stackId, e.getMessage());
+            return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                    .body("Stack not found: " + e.getMessage());
+        } catch (PortainerAuthenticationException e) {
+            log.error("Portainer auth error for stack {}: {}", stackId, e.getMessage());
+            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
+                    .body("Portainer authentication failed: " + e.getMessage());
+        } catch (PortainerDeploymentException e) {
+            log.error("Portainer deployment error for stack {}: {}", stackId, e.getMessage());
+            return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
+                    .body("Deployment failed: " + e.getMessage());
+        } catch (RuntimeException e) {
+            log.error("Unexpected error deploying stack {}: {}", stackId, e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                    .body("Deployment failed: " + e.getMessage());
+        }
+    }
+}

portainer-automation/src/main/java/com/hithomelabs/portainer/service/DeployService.java

@@ -0,0 +1,46 @@
+package com.hithomelabs.portainer.service;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+
+import com.hithomelabs.common.portainer.client.PortainerApiClient;
+import com.hithomelabs.common.portainer.client.exception.PortainerConnectionException;
+import com.hithomelabs.common.portainer.client.exception.PortainerDeploymentException;
+import com.hithomelabs.common.portainer.client.exception.PortainerResourceNotFoundException;
+import com.hithomelabs.common.portainer.model.EnvVariable;
+import com.hithomelabs.common.portainer.model.PortainerStack;
+import com.hithomelabs.portainer.config.PortainerAutomationProperties;
+
+import java.util.List;
+
+@Service
+public class DeployService {
+
+    private static final Logger log = LoggerFactory.getLogger(DeployService.class);
+
+    private final PortainerApiClient portainerApiClient;
+    private final PortainerAutomationProperties props;
+
+    public DeployService(PortainerApiClient portainerApiClient,
+                         PortainerAutomationProperties props) {
+        this.portainerApiClient = portainerApiClient;
+        this.props = props;
+    }
+
+    public void redeploy(Long stackId) {
+        log.info("Redeploying stack {}", stackId);
+        try {
+            PortainerStack stack = portainerApiClient.getStack(stackId);
+            List<EnvVariable> env = stack.getEnv() != null ? stack.getEnv() : List.of();
+            portainerApiClient.redeployGitStack(stackId, props.getEndpointId(), true, env);
+            log.info("Stack {} redeployed successfully", stackId);
+        } catch (PortainerResourceNotFoundException | PortainerConnectionException | PortainerDeploymentException e) {
+            log.error("Deploy failed for stack {}: {}", stackId, e.getMessage());
+            throw e;
+        } catch (RuntimeException e) {
+            log.error("Unexpected error during deploy of stack {}: {}", stackId, e.getMessage(), e);
+            throw e;
+        }
+    }
+}

portainer-automation/src/main/resources/application-ci.properties

@@ -0,0 +1,6 @@
+# CI-specific Portainer Configuration
+# Uses test/stub endpoints during CI pipeline testing
+portainer.base-url=http://portainer-test:9000
+portainer.api-key=${PORTAINER_API_KEY:ci-test-key}
+portainer.endpoint-id=1
+portainer.service.api-key=${PORTAINER_SERVICE_API_KEY:ci-test-key}

portainer-automation/src/main/resources/application-local.properties

@@ -0,0 +1,4 @@
+portainer.base-url=https://devdocker.hithomelabs.com
+portainer.api-key=${PORTAINER_API_KEY:dev-test-key}
+portainer.endpoint-id=2
+portainer.service.api-key=dev-test-key

portainer-automation/src/main/resources/application-prod.properties

@@ -0,0 +1,6 @@
+# Production Portainer Configuration
+# Targets the production Portainer instance on the internal network (port 9443)
+portainer.base-url=https://192.168.0.100:9443
+portainer.api-key=${PORTAINER_API_KEY}
+portainer.endpoint-id=2
+portainer.service.api-key=${PORTAINER_SERVICE_API_KEY}

portainer-automation/src/main/resources/application.properties

@@ -1 +1,11 @@
 server.port=8081
+portainer.base-url=https://192.168.0.100:9442
+portainer.api-key=${PORTAINER_API_KEY:}
+portainer.endpoint-id=1
+portainer.service.api-key=${PORTAINER_SERVICE_API_KEY:change-me}
+
+# Actuator configuration - management port and exposed endpoints
+# App runs on server.port=8081, so management port must differ (8082)
+management.server.port=8082
+management.endpoints.web.exposure.include=health,info
+management.endpoint.health.show-details=when-authorized

portainer-automation/src/test/java/com/hithomelabs/portainer/controller/DeployControllerTest.java

@@ -0,0 +1,73 @@
+package com.hithomelabs.portainer.controller;
+
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import com.hithomelabs.portainer.config.PortainerAutomationProperties;
+import com.hithomelabs.portainer.service.DeployService;
+
+@WebMvcTest(DeployController.class)
+class DeployControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockitoBean
+    private DeployService deployService;
+
+    @MockitoBean
+    private PortainerAutomationProperties props;
+
+    @MockitoBean
+    private PortainerAutomationProperties.Service service;
+
+    @BeforeEach
+    void setUp() {
+        when(props.getService()).thenReturn(service);
+        when(service.getApiKey()).thenReturn("valid-key");
+    }
+
+    @Test
+    void deployWithValidKeyReturnsOk() throws Exception {
+        mockMvc.perform(post("/api/deploy/1")
+                        .header("X-API-Key", "valid-key"))
+                .andExpect(status().isOk())
+                .andExpect(content().string("Deployment initiated for stack 1"));
+    }
+
+    @Test
+    void deployWithInvalidKeyReturnsUnauthorized() throws Exception {
+        mockMvc.perform(post("/api/deploy/1")
+                        .header("X-API-Key", "wrong-key"))
+                .andExpect(status().isUnauthorized())
+                .andExpect(content().string("Invalid API key"));
+    }
+
+    @Test
+    void deployWithMissingKeyReturnsUnauthorized() throws Exception {
+        mockMvc.perform(post("/api/deploy/1"))
+                .andExpect(status().isUnauthorized())
+                .andExpect(content().string("Invalid API key"));
+    }
+
+    @Test
+    void deployWhenServiceFailsReturnsServerError() throws Exception {
+        doThrow(new RuntimeException("Portainer error"))
+                .when(deployService).redeploy(anyLong());
+        mockMvc.perform(post("/api/deploy/1")
+                        .header("X-API-Key", "valid-key"))
+                .andExpect(status().isInternalServerError())
+                .andExpect(content().string("Deployment failed: Portainer error"));
+    }
+}

portainer-automation/src/test/java/com/hithomelabs/portainer/service/DeployServiceTest.java

@@ -0,0 +1,97 @@
+package com.hithomelabs.portainer.service;
+
+import com.hithomelabs.common.portainer.client.PortainerApiClient;
+import com.hithomelabs.common.portainer.client.exception.PortainerConnectionException;
+import com.hithomelabs.common.portainer.client.exception.PortainerResourceNotFoundException;
+import com.hithomelabs.common.portainer.model.EnvVariable;
+import com.hithomelabs.common.portainer.model.PortainerStack;
+import com.hithomelabs.portainer.config.PortainerAutomationProperties;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class DeployServiceTest {
+
+    @Mock
+    private PortainerApiClient portainerApiClient;
+
+    @Mock
+    private PortainerAutomationProperties props;
+
+    private DeployService deployService;
+
+    private static final Long STACK_ID = 1L;
+    private static final Long ENDPOINT_ID = 2L;
+
+    @BeforeEach
+    void setUp() {
+        when(props.getEndpointId()).thenReturn(ENDPOINT_ID);
+        deployService = new DeployService(portainerApiClient, props);
+    }
+
+    @Test
+    void redeploy_withEnv_callsRedeployGitStackWithSameEnv() {
+        List<EnvVariable> envList = List.of(new EnvVariable("DB_HOST", "postgres"));
+        PortainerStack stack = new PortainerStack();
+        stack.setEnv(envList);
+
+        when(portainerApiClient.getStack(STACK_ID)).thenReturn(stack);
+
+        deployService.redeploy(STACK_ID);
+
+        verify(portainerApiClient).getStack(STACK_ID);
+        verify(portainerApiClient).redeployGitStack(STACK_ID, ENDPOINT_ID, true, envList);
+    }
+
+    @Test
+    void redeploy_withNullEnv_callsRedeployGitStackWithNull() {
+        PortainerStack stack = new PortainerStack();
+        stack.setEnv(null);
+
+        when(portainerApiClient.getStack(STACK_ID)).thenReturn(stack);
+
+        deployService.redeploy(STACK_ID);
+
+        verify(portainerApiClient).getStack(STACK_ID);
+        // When getEnv() returns null, an empty list is passed to redeployGitStack
+        verify(portainerApiClient).redeployGitStack(STACK_ID, ENDPOINT_ID, true, List.of());
+    }
+
+    @Test
+    void redeploy_whenGetStackThrowsResourceNotFound_propagatesException() {
+        when(portainerApiClient.getStack(STACK_ID))
+                .thenThrow(new PortainerResourceNotFoundException("Stack not found"));
+
+        assertThrows(PortainerResourceNotFoundException.class,
+                () -> deployService.redeploy(STACK_ID));
+    }
+
+    @Test
+    void redeploy_whenGetStackThrowsConnectionError_propagatesException() {
+        when(portainerApiClient.getStack(STACK_ID))
+                .thenThrow(new PortainerConnectionException("Connection refused"));
+
+        assertThrows(PortainerConnectionException.class,
+                () -> deployService.redeploy(STACK_ID));
+    }
+
+    @Test
+    void redeploy_whenRedeployThrows_propagatesException() {
+        PortainerStack stack = new PortainerStack();
+        stack.setEnv(List.of(new EnvVariable("A", "B")));
+        when(portainerApiClient.getStack(STACK_ID)).thenReturn(stack);
+        doThrow(new PortainerConnectionException("Connection refused"))
+                .when(portainerApiClient).redeployGitStack(STACK_ID, ENDPOINT_ID, true, stack.getEnv());
+
+        assertThrows(PortainerConnectionException.class,
+                () -> deployService.redeploy(STACK_ID));
+    }
+}