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

.dockerignore

@@ -1,28 +0,0 @@
-# Frontend
-frontend/
-node_modules/
-dist/
-.angular/
-
-# IDE
-.idea/
-.vscode/
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-npm-debug.log*
-
-# Build
-build/
-.gradle/
-
-# Test
-coverage/
-
-# Environment
-.env
-*.env

.env.example

@@ -2,3 +2,4 @@ CLOUDFLARE_ACCOUNT_ID="<cloudflare account id>"
 CLOUDFLARE_API_KEY="<cloudflare account key>"
 CLOUDFLARE_EMAIL="<cloudflare email>"
 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: catthehacker/ubuntu:act-latest
-    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_build.yml

@@ -14,7 +14,8 @@ jobs:
         with:
           distribution: 'zulu'
           java-version: '17'
-      - name: Validate Gradle Wrapper
+      - name: Validate Gradle Wrapper (offline checksum)
-        uses: gradle/actions/wrapper-validation@v3
+        run: |
+          sha256sum --check gradle/wrapper/gradle-wrapper.jar.sha256
       - name: Gradle build
         run: ./gradlew build --info

.gitea/workflows/test_image_build_push.yml

@@ -1,67 +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: catthehacker/ubuntu:act-latest
-    steps:
-      - name: Check out repository code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: JDK setup
-        uses: actions/setup-java@v4
-        with:
-          distribution: 'zulu'
-          java-version: '17'
-      - 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 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 }}
-  

.gitignore

@@ -6,6 +6,7 @@ build/
 !gradle/wrapper/gradle-wrapper.jar
 !**/src/main/**/build/
 !**/src/test/**/build/
+CFTunnels/
 
 ### STS ###
 .apt_generated

Dockerfile

@@ -1,4 +0,0 @@
-FROM openjdk:17-jdk
-ARG JAR_FILE=target/*.jar
-COPY ${JAR_FILE} app.jar
-ENTRYPOINT ["java","-jar","/app.jar"]

README.md

@@ -0,0 +1,186 @@
+# CFTunnels - Cloudflare Tunnels Management API
+
+> **Note**: All pull requests should be raised against the `test` branch.
+
+A Spring Boot REST API for managing Cloudflare Tunnels with ingress mappings and an approval workflow.
+
+## Overview
+
+CFTunnels provides a programmatic way to manage Cloudflare Tunnel configurations, allowing teams to:
+
+- View and manage Cloudflare Tunnels
+- Add, modify, and delete ingress mappings
+- Request mapping changes through an approval workflow
+- Track tunnel configurations locally
+
+## Features
+
+- **Tunnel Management**: Create, update, and delete Cloudflare tunnels
+- **Ingress Mappings**: Add custom ingress rules to tunnel configurations
+- **Approval Workflow**: Request/approve/reject mapping changes
+- **Security**: OIDC-based authentication with role-based access
+- **API Documentation**: OpenAPI/Swagger documentation
+
+## Technology Stack
+
+- Java 17
+- Spring Boot 3.x
+- Spring Data JPA
+- Spring Security with OIDC
+- H2 Database (configurable for PostgreSQL)
+- Cloudflare API v4
+
+## Prerequisites
+
+- Java 17 or higher
+- Cloudflare account with API key
+- OIDC provider (e.g., Google, Okta, Auth0)
+
+## Configuration
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+```
+
+### Required Environment Variables
+
+| Variable | Description |
+|---------|-------------|
+| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Account ID |
+| `CLOUDFLARE_API_KEY` | Cloudflare API Key |
+| `CLOUDFLARE_EMAIL` | Cloudflare account email |
+| `SPRING_PROFILES_ACTIVE` | Environment (local, dev, prod) |
+
+### Security Configuration
+
+OIDC settings in `application.properties`:
+
+```properties
+spring.security.oauth2.client.registration.<provider>.client-id=your-client-id
+spring.security.oauth2.client.registration.<provider>.client-secret=your-client-secret
+spring.security.oauth2.client.provider.<provider>.issuer-uri=https://your-oidc-provider
+```
+
+## Running Locally
+
+### Using Gradle
+
+```bash
+./gradlew bootRun
+```
+
+### Using Docker
+
+```bash
+docker-compose up --build
+```
+
+The API will be available at `http://localhost:8080`
+
+## API Documentation
+
+Once running, access:
+
+- **Swagger UI**: `http://localhost:8080/swagger-ui.html`
+- **OpenAPI JSON**: `http://localhost:8080/v3/api-docs`
+
+## API Endpoints
+
+### Base URL: `/cloudflare`
+
+| Method | Endpoint | Description | Required Role |
+|--------|----------|-------------|---------------|
+| GET | `/whoami` | Get current user info | USER |
+| GET | `/tunnels` | List all Cloudflare tunnels | USER |
+| GET | `/configured/tunnels` | List locally configured tunnels | USER |
+| GET | `/requests` | List all mapping requests | USER |
+| GET | `/tunnels/{tunnelId}/mappings` | Get tunnel configuration | DEVELOPER |
+| POST | `/tunnels/{tunnelId}/mappings` | Add ingress mapping | ADMIN |
+| DELETE | `/tunnels/{tunnelId}/mappings` | Delete ingress mapping | DEVELOPER |
+| POST | `/tunnels/configure/{tunnelId}/requests` | Create mapping request | DEVELOPER |
+| PUT | `/requests/{requestId}/approve` | Approve mapping request | APPROVER |
+| PUT | `/requests/{requestId}/reject` | Reject mapping request | APPROVER |
+| PUT | `/tunnels/configure/{tunnelId}` | Configure tunnel for environment | ADMIN |
+
+## Role-Based Access
+
+| Role | Permissions |
+|------|-------------|
+| USER | View tunnels and requests |
+| DEVELOPER | Create/modify/delete mappings, create requests |
+| APPROVER | Approve/reject requests |
+| ADMIN | Full access including tunnel configuration |
+
+## Example Usage
+
+### List all tunnels
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8080/cloudflare/tunnels
+```
+
+### Add an ingress mapping
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "hostname": "api.example.com",
+    "service": "http://localhost:8080",
+    "originRequest": {"noTLSVerify": true}
+  }' \
+  http://localhost:8080/cloudflare/tunnels/{tunnelId}/mappings
+```
+
+## Project Structure
+
+```
+CFTunnels/
+├── src/main/java/com/hithomelabs/CFTunnels/
+│   ├── CfTunnelsApplication.java     # Main application
+│   ├── Config/                      # Configuration classes
+│   ├── Controllers/                # REST controllers
+│   │   └── TunnelController.java     # Main API controller
+│   ├── Entity/                     # JPA entities
+│   │   ├── Mapping.java            # Ingress mapping
+│   │   ├── Protocol.java         # Protocol enum
+│   │   ├── Request.java         # Mapping request
+│   │   ├── Tunnel.java          # Tunnel entity
+│   │   └── User.java            # User entity
+│   ├── Models/                     # DTOs
+│   ├── Repositories/              # JPA repositories
+│   └── Services/                 # Business logic
+│       ├── CloudflareAPIService.java   # Cloudflare API
+│       └── MappingRequestService.java  # Request workflow
+└── src/main/resources/
+    ├── application.properties    # Main config
+    └── schema.sql              # Database schema
+```
+
+## Testing
+
+Run tests with:
+
+```bash
+./gradlew test
+```
+
+Run integration tests:
+
+```bash
+./gradlew integrationTest
+```
+
+## License
+
+Private - All rights reserved
+
+## References
+
+- [Cloudflare Tunnel Documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
+- [Cloudflare API v4](https://api.cloudflare.com/)
+- [Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/current/reference/)

build.gradle

@@ -1,62 +1,29 @@
 plugins {
-	id 'java'
+    id 'java'
-	id 'org.springframework.boot' version '3.4.5'
+    id 'org.springframework.boot' version '3.4.5' apply false
-	id 'io.spring.dependency-management' version '1.1.7'
+    id 'io.spring.dependency-management' version '1.1.7' apply false
 }
 
-group = 'com.hithomelabs'
+subprojects {
-version = '0.0.1-SNAPSHOT'
+    apply plugin: 'java'
+    apply plugin: 'io.spring.dependency-management'
 
-java {
+    group = 'com.hithomelabs'
-	toolchain {
+    version = '0.0.1-SNAPSHOT'
-		languageVersion = JavaLanguageVersion.of(17)
-	}
-}
 
-test {
+    java {
-	systemProperty 'spring.profiles.active', 'ci'
+        toolchain {
-	useJUnitPlatform {
+            languageVersion = JavaLanguageVersion.of(17)
-		excludeTags 'integration'
+        }
-	}
+    }
-	testLogging {
-		events "passed", "skipped", "failed", "standardOut", "standardError"
-		exceptionFormat "full" // shows full stack trace
-		showStandardStreams = true // shows println/log output
-	}
-}
 
-tasks.register('integrationTestOnly', Test) {
+    repositories {
-	useJUnitPlatform {
+        mavenCentral()
-		includeTags 'integration'
+    }
-	}
-	description = 'Runs only integration tests tagged with @Tag("integration")'
-	group = 'verification'
-	testLogging {
-		events "passed", "skipped", "failed"
-		exceptionFormat "full"
-		showStandardStreams = true
-	}
-}
 
-repositories {
+    dependencyManagement {
-	mavenCentral()
+        imports {
-}
+            mavenBom "org.springframework.boot:spring-boot-dependencies:3.4.5"
-
+        }
-dependencies {
+    }
-	implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.8.5'
-	implementation group: 'org.springframework.boot', name:'spring-boot-starter-oauth2-client', version: '3.5.5'
-	compileOnly 'org.projectlombok:lombok:1.18.30'
-	annotationProcessor 'org.projectlombok:lombok:1.18.30'
-	implementation 'org.springframework.boot:spring-boot-starter-web'
-	testImplementation 'org.springframework.boot:spring-boot-starter-test'
-	testImplementation 'org.springframework.security:spring-security-test'
-	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
-	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
-	runtimeOnly 'org.postgresql:postgresql'
-	implementation 'org.hibernate.validator:hibernate-validator'
-    runtimeOnly 'com.h2database:h2'
-}
-
-tasks.named('test') {
-	useJUnitPlatform()
 }

cftunnels-service/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 :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

@@ -0,0 +1,47 @@
+apply plugin: 'org.springframework.boot'
+
+dependencies {
+    implementation project(':common')
+
+    implementation 'org.springframework.boot:spring-boot-starter-web'
+    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'
+
+    runtimeOnly 'org.postgresql:postgresql'
+    runtimeOnly 'com.h2database:h2'
+
+    compileOnly 'org.projectlombok:lombok'
+    annotationProcessor 'org.projectlombok:lombok'
+
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
+    testImplementation 'org.springframework.security:spring-security-test'
+}
+
+test {
+    systemProperty 'spring.profiles.active', 'ci'
+    useJUnitPlatform {
+        excludeTags 'integration'
+    }
+    testLogging {
+        events "passed", "skipped", "failed", "standardOut", "standardError"
+        exceptionFormat "full"
+        showStandardStreams = true
+    }
+}
+
+tasks.register('integrationTestOnly', Test) {
+    useJUnitPlatform {
+        includeTags 'integration'
+    }
+    description = 'Runs only integration tests tagged with @Tag("integration")'
+    group = 'verification'
+    testLogging {
+        events "passed", "skipped", "failed"
+        exceptionFormat "full"
+        showStandardStreams = true
+    }
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/CfTunnelsApplication.java

@@ -0,0 +1,47 @@
+package com.hithomelabs.cftunnels;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+/**
+ * Main Spring Boot application class for Cloudflare Tunnels API.
+ *
+ * <p>This application provides a RESTful API for managing Cloudflare Tunnels,
+ * allowing users to create tunnel mappings to services with an approval workflow.</p>
+ *
+ * <p><b>Features:</b></p>
+ * <ul>
+ *   <li>Create, update, and delete Cloudflare tunnels</li>
+ *   <li>Add ingress mappings to tunnels</li>
+ *   <li>Request/approval workflow for mapping changes</li>
+ *   <li>OIDC-based authentication with role-based access</li>
+ * </ul>
+ *
+ * <p><b>Technology Stack:</b></p>
+ * <ul>
+ *   <li>Java 17</li>
+ *   <li>Spring Boot 3.x</li>
+ *   <li>Spring Data JPA</li>
+ *   <li>Spring Security with OIDC</li>
+ *   <li>H2 Database (configurable for PostgreSQL)</li>
+ *   <li>Cloudflare API</li>
+ * </ul>
+ *
+ * <p>Access the API documentation at:
+ * {@code /swagger-ui.html} for the Swagger/OpenAPI UI</p>
+ *
+ * @see <a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-negative">Cloudflare Tunnel Documentation</a>
+ * @since 1.0.0
+ */
+@SpringBootApplication(scanBasePackages = "com.hithomelabs")
+public class CfTunnelsApplication {
+
+    /**
+     * Main entry point for the application.
+     * 
+     * @param args command line arguments passed to the application
+     */
+    public static void main(String[] args) {
+        SpringApplication.run(CfTunnelsApplication.class, args);
+    }
+
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Config/AuthoritiesToGroupMapping.java

@@ -1,7 +1,7 @@
-package com.hithomelabs.CFTunnels.Config;
+package com.hithomelabs.cftunnels.Config;
 
-import com.hithomelabs.CFTunnels.Models.Authorities;
+import com.hithomelabs.cftunnels.Models.Authorities;
-import com.hithomelabs.CFTunnels.Models.Groups;
+import com.hithomelabs.cftunnels.Models.Groups;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Config/CloudflareConfig.java

@@ -0,0 +1,58 @@
+package com.hithomelabs.cftunnels.Config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Configuration class for Cloudflare API credentials.
+ * 
+ * <p>Loads Cloudflare configuration from application properties
+ * using the {@code cloudflare.*} prefix.</p>
+ * 
+ * <p><b>Example configuration in application.properties:</b></p>
+ * <pre>
+ * cloudflare.account-id=your-account-id
+ * cloudflare.api-key=your-api-key
+ * cloudflare.email=your@email.com
+ * </pre>
+ * 
+ * @see <a href="https://api.cloudflare.com/">Cloudflare API Documentation</a>
+ */
+@Configuration
+@ConfigurationProperties(prefix = "cloudflare")
+public class CloudflareConfig {
+
+    /**
+     * Cloudflare account ID.
+     * 
+     * <p>Found in the Cloudflare Dashboard under
+     * Overview > Account ID</p>
+     */
+    private String accountId;
+
+    /**
+     * Cloudflare API Key.
+     * 
+     * <p>Generated in Cloudflare Dashboard under
+     * Profile > API Tokens > Global API Key</p>
+     */
+    private String apiKey;
+
+    /**
+     * Cloudflare account email.
+     * 
+     * <p>The email address associated with your
+     * Cloudflare account.</p>
+     */
+    private String email;
+
+    // Getters and Setters
+    public String getAccountId() { return accountId; }
+    public void setAccountId(String accountId) { this.accountId = accountId; }
+
+    public String getApiKey() { return apiKey; }
+    public void setApiKey(String apiKey) { this.apiKey = apiKey; }
+
+    public String getEmail() { return email; }
+    public void setEmail(String email) { this.email = email; }
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Config/CustomOidcUserConfiguration.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Config;
+package com.hithomelabs.cftunnels.Config;
 
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.context.annotation.Configuration;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Config/OpenApiConfig.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Config;
+package com.hithomelabs.cftunnels.Config;
 
 import io.swagger.v3.oas.models.Components;
 import io.swagger.v3.oas.models.OpenAPI;

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

@@ -1,6 +1,6 @@
-package com.hithomelabs.CFTunnels.Config.Security;
+package com.hithomelabs.cftunnels.Config.Security;
 
-import com.hithomelabs.CFTunnels.Config.CustomOidcUserConfiguration;
+import com.hithomelabs.cftunnels.Config.CustomOidcUserConfiguration;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -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/java/com/hithomelabs/cftunnels/Controllers/TunnelController.java

@@ -1,20 +1,20 @@
-package com.hithomelabs.CFTunnels.Controllers;
+package com.hithomelabs.cftunnels.Controllers;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
-import com.hithomelabs.CFTunnels.Config.AuthoritiesToGroupMapping;
+import com.hithomelabs.cftunnels.Config.AuthoritiesToGroupMapping;
-import com.hithomelabs.CFTunnels.Config.CloudflareConfig;
+import com.hithomelabs.cftunnels.Config.CloudflareConfig;
-import com.hithomelabs.CFTunnels.Config.RestTemplateConfig;
+import com.hithomelabs.common.config.RestTemplateConfig;
-import com.hithomelabs.CFTunnels.Entity.Request;
+import com.hithomelabs.cftunnels.Entity.Request;
-import com.hithomelabs.CFTunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
-import com.hithomelabs.CFTunnels.Entity.User;
+import com.hithomelabs.cftunnels.Entity.User;
-import com.hithomelabs.CFTunnels.Headers.AuthKeyEmailHeader;
+import com.hithomelabs.cftunnels.Headers.AuthKeyEmailHeader;
-import com.hithomelabs.CFTunnels.Models.Config;
+import com.hithomelabs.cftunnels.Models.Config;
-import com.hithomelabs.CFTunnels.Models.Ingress;
+import com.hithomelabs.cftunnels.Models.Ingress;
-import com.hithomelabs.CFTunnels.Models.TunnelResponse;
+import com.hithomelabs.cftunnels.Models.TunnelResponse;
-import com.hithomelabs.CFTunnels.Models.TunnelsResponse;
+import com.hithomelabs.cftunnels.Models.TunnelsResponse;
-import com.hithomelabs.CFTunnels.Repositories.UserRepository;
+import com.hithomelabs.cftunnels.Repositories.UserRepository;
-import com.hithomelabs.CFTunnels.Services.CloudflareAPIService;
+import com.hithomelabs.cftunnels.Services.CloudflareAPIService;
-import com.hithomelabs.CFTunnels.Services.MappingRequestService;
+import com.hithomelabs.cftunnels.Services.MappingRequestService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -22,7 +22,6 @@ import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.web.servlet.error.ErrorController;
 import org.springframework.dao.DataAccessException;
 import org.springframework.http.*;
-import org.springframework.http.*;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
@@ -36,6 +35,41 @@ import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.UUID;
 
+/**
+ * REST Controller for managing Cloudflare Tunnels.
+ * 
+ * <p>This controller provides the public API for managing Cloudflare Tunnels
+ * and their ingress mappings. All endpoints require authentication via OIDC
+ * and are protected by role-based access control.</p>
+ * 
+ * <p><b>Base URL:</b> {@code /cloudflare}</p>
+ * 
+ * <p><b>Authentication:</b> OIDC-based with role-based access</p>
+ * 
+ * <p><b>Available Roles:</b></p>
+ * <ul>
+ *   <li>USER - View tunnels and requests</li>
+ *   <li>DEVELOPER - Create/modify/delete mappings</li>
+ *   <li>APPROVER - Approve/reject requests</li>
+ *   <li>ADMIN - Full tunnel configuration access</li>
+ * </ul>
+ * 
+ * <p><b>Example Usage:</b></p>
+ * <pre>
+ * # Get all tunnels (requires USER role)
+ * curl -H "Authorization: Bearer &lt;token&gt;" \
+ *   https://api.example.com/cloudflare/tunnels
+ * 
+ * # Add a mapping (requires ADMIN role)
+ * curl -X POST -H "Authorization: Bearer &lt;token&gt;" \
+ *   -H "Content-Type: application/json" \
+ *   -d '{"hostname":"api.example.com","service":"http://localhost:8080"}' \
+ *   https://api.example.com/cloudflare/tunnels/{tunnelId}/mappings
+ * </pre>
+ * 
+ * @see CloudflareAPIService
+ * @see MappingRequestService
+ */
 @RestController
 @RequestMapping("/cloudflare")
 public class TunnelController implements ErrorController {
@@ -63,9 +97,21 @@ public class TunnelController implements ErrorController {
     @Autowired
     private UserRepository userRepository;
 
+    /**
+     * Current environment (loaded from spring.profiles.active).
+     */
     @Value("${spring.profiles.active}")
     private String environment;
 
+    /**
+     * Get current user information.
+     * 
+     * <p>Returns the authenticated user's username and roles.</p>
+     * 
+     * @param oidcUser The authenticated OIDC user
+     * @return Map containing username and roles
+     * @throws SecurityException if authentication fails
+     */
     @PreAuthorize("hasAnyRole('USER')")
     @GetMapping("/whoami")
     public Map<String,Object> whoAmI(@AuthenticationPrincipal OidcUser oidcUser) {
@@ -79,6 +125,16 @@ public class TunnelController implements ErrorController {
         );
     }
 
+    /**
+     * Get all tunnels from Cloudflare API.
+     * 
+     * <p>Fetches the complete list of tunnels from Cloudflare,
+     * including their status and configuration from the Cloudflare API.</p>
+     * 
+     * @return Map containing list of all tunnels
+     * @throws SecurityException if user lacks required role
+     * @see <a href="https://api.cloudflare.com/#cfd_tunnel-get-tunnels">Cloudflare API</a>
+     */
     @PreAuthorize("hasAnyRole('USER')")
     @GetMapping("/tunnels")
     @Operation( security = { @SecurityRequirement(name = "oidcAuth") } )
@@ -92,6 +148,16 @@ public class TunnelController implements ErrorController {
         return ResponseEntity.ok(jsonResponse);
     }
 
+    /**
+     * Get locally configured tunnels.
+     * 
+     * <p>Returns the tunnels that have been configured locally
+     * with environment associations.</p>
+     * 
+     * @return Map containing list of configured tunnels
+     * @throws SecurityException if user lacks required role
+     * @see CloudflareAPIService#getAllConfiguredTunnels()
+     */
     @PreAuthorize("hasAnyRole('USER')")
     @GetMapping("/configured/tunnels")
     public ResponseEntity<Map<String,Object>> getConfiguredTunnels(){
@@ -106,6 +172,14 @@ public class TunnelController implements ErrorController {
         }
     }
 
+    /**
+     * Get all mapping requests.
+     * 
+     * <p>Returns all pending, approved, and rejected mapping requests.</p>
+     * 
+     * @return Map containing list of all requests
+     * @throws SecurityException if user lacks required role
+     */
     @PreAuthorize("hasAnyRole('USER')")
     @GetMapping("/requests")
     public ResponseEntity<Map<String,Object>> getAllRequests() {
@@ -120,6 +194,17 @@ public class TunnelController implements ErrorController {
         }
     }
 
+    /**
+     * Get tunnel configuration from Cloudflare.
+     * 
+     * <p>Fetches the complete configuration for a specific tunnel,
+     * including all ingress rules.</p>
+     * 
+     * @param tunnelId The Cloudflare tunnel ID (UUID)
+     * @return Map containing tunnel configuration
+     * @throws SecurityException if user lacks required role
+     * @see <a href="https://api.cloudflare.com/#cfd_tunnel-get-tunnel-config">Cloudflare API</a>
+     */
     @PreAuthorize("hasAnyRole('DEVELOPER')")
     @GetMapping("/tunnels/{tunnelId}/mappings")
     public ResponseEntity<Map<String,Object>> getTunnelConfigurations(@PathVariable String tunnelId) {
@@ -132,22 +217,41 @@ public class TunnelController implements ErrorController {
         return ResponseEntity.ok(jsonResponse);
     }
 
-    // 50df9101-f625-4618-b7c5-100338a57124
+    /**
+     * Add an ingress mapping to a tunnel.
+     * 
+     * <p>Adds a new ingress rule to the tunnel configuration.
+     * The new rule is inserted at the second-to-last position,
+     * before any catch-all rule.</p>
+     * 
+     * @param tunnelId The Cloudflare tunnel ID (UUID)
+     * @param ingress The ingress rule to add
+     * @return Map containing the updated configuration
+     * @throws SecurityException if user lacks required role
+     * @throws JsonProcessingException if JSON processing fails
+     * 
+     * @example
+     * {
+     *   "hostname": "api.example.com",
+     *   "service": "http://localhost:8080",
+     *   "originRequest": {"noTLSVerify": true}
+     * }
+     */
     @PreAuthorize("hasAnyRole('ADMIN')")
     @PostMapping("/tunnels/{tunnelId}/mappings")
     public ResponseEntity<Map<String, Object>> addTunnelconfiguration(@PathVariable String tunnelId, @RequestBody Ingress ingress) throws JsonProcessingException {
 
         ResponseEntity<TunnelResponse> responseEntity = cloudflareAPIService.getCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class);
 
-        // * * Inserting new ingress value at second-to last position in list
+        // Inserting new ingress value at second-to last position in list
         Config config = responseEntity.getBody().getResult().getConfig();
         List<Ingress> response_ingress = config.getIngress();
         response_ingress.add(response_ingress.size()-1, ingress);
 
-        // * * Hitting put endpoint
+        // Hitting put endpoint
         ResponseEntity<TunnelResponse> response = cloudflareAPIService.putCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class, config);
 
-        // * * Displaying response
+        // Displaying response
         Map<String, Object> jsonResponse = new HashMap<>();
         jsonResponse.put("status", response.getStatusCode().toString());
         jsonResponse.put("data", response.getBody());
@@ -155,21 +259,32 @@ public class TunnelController implements ErrorController {
         return ResponseEntity.ok(jsonResponse);
     }
 
+    /**
+     * Delete an ingress mapping from a tunnel.
+     * 
+     * <p>Removes an ingress rule by hostname from the tunnel configuration.</p>
+     * 
+     * @param tunnelId The Cloudflare tunnel ID (UUID)
+     * @param ingress Ingress containing hostname to delete (only hostname field is used)
+     * @return Map containing the result
+     * @throws SecurityException if user lacks required role
+     * @throws JsonProcessingException if JSON processing fails
+     */
     @PreAuthorize("hasAnyRole('DEVELOPER')")
     @DeleteMapping("/tunnels/{tunnelId}/mappings")
     public ResponseEntity<Map<String, Object>> deleteTunnelConfiguration(@PathVariable String tunnelId, @RequestBody Ingress ingress) throws JsonProcessingException {
 
         ResponseEntity<TunnelResponse> responseEntity = cloudflareAPIService.getCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class);
 
-        // * * Deleting the selected ingress value
+        // Deleting the selected ingress value
         Config config = responseEntity.getBody().getResult().getConfig();
         List<Ingress> response_ingress = config.getIngress();
         Boolean result = Ingress.deleteByHostName(response_ingress, ingress.getHostname());
 
-        // * * Hitting put endpoint
+        // Hitting put endpoint
         ResponseEntity<TunnelResponse> response = cloudflareAPIService.putCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class, config);
 
-        // * * Displaying response
+        // Displaying response
         Map<String, Object> jsonResponse = new HashMap<>();
 
         if (result){
@@ -184,6 +299,20 @@ public class TunnelController implements ErrorController {
         return ResponseEntity.ok(jsonResponse);
     }
 
+    /**
+     * Create a mapping change request.
+     * 
+     * <p>Creates a new request for changing tunnel ingress mappings.
+     * The request starts in PENDING status and must be approved
+     * before the changes are applied.</p>
+     * 
+     * @param tunnelId  The Cloudflare tunnel ID (UUID)
+     * @param oidcUser  The authenticated user
+     * @param ingess   The ingress configuration to request
+     * @return The created request with PENDING status
+     * @throws SecurityException if user lacks required role
+     * @see MappingRequestService#createMappingRequest(String, Ingress, OidcUser)
+     */
     @PreAuthorize("hasAnyRole('DEVELOPER')")
     @PostMapping("/tunnels/configure/{tunnelId}/requests")
     public ResponseEntity<Request> createTunnelMappingRequest(@PathVariable String tunnelId, @AuthenticationPrincipal OidcUser oidcUser, @RequestBody Ingress ingess){
@@ -193,6 +322,17 @@ public class TunnelController implements ErrorController {
         return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
     }
 
+    /**
+     * Approve a mapping request.
+     * 
+     * <p>Approves a pending mapping request. If approved, the
+     * mapping will be applied to the Cloudflare tunnel.</p>
+     * 
+     * @param requestId The ID of the request to approve
+     * @param oidcUser  The approver (must have APPROVER role)
+     * @return The updated request with APPROVED status
+     * @throws SecurityException if user lacks required role
+     */
     @PreAuthorize("hasAnyRole('APPROVER')")
     @PutMapping("/requests/{requestId}/approve")
     public ResponseEntity<Request> approveMappingRequest(@PathVariable UUID requestId, @AuthenticationPrincipal OidcUser oidcUser) {
@@ -210,6 +350,17 @@ public class TunnelController implements ErrorController {
         }
     }
 
+    /**
+     * Reject a mapping request.
+     * 
+     * <p>Rejects a pending mapping request. No changes
+     * will be made to the tunnel.</p>
+     * 
+     * @param requestId The ID of the request to reject
+     * @param oidcUser  The rejecter (must have APPROVER role)
+     * @return The updated request with REJECTED status
+     * @throws SecurityException if user lacks required role
+     */
     @PreAuthorize("hasAnyRole('APPROVER')")
     @PutMapping("/requests/{requestId}/reject")
     public ResponseEntity<Request> rejectMappingRequest(@PathVariable UUID requestId, @AuthenticationPrincipal OidcUser oidcUser) {
@@ -227,13 +378,31 @@ public class TunnelController implements ErrorController {
         }
     }
 
+    /**
+     * Configure a tunnel for the current environment.
+     * 
+     * <p>Creates a local configuration entry for a tunnel,
+     * associating it with the current environment (from spring.profiles.active).</p>
+     * 
+     * <p><b>Response Codes:</b></p>
+     * <ul>
+     *   <li>200 - Created/updated with new tunnel</li>
+     *   <li>204 - No changes needed</li>
+     *   <li>404 - Tunnel not found in Cloudflare</li>
+     * </ul>
+     * 
+     * @param tunnelId The Cloudflare tunnel ID (UUID)
+     * @param user    The authenticated user
+     * @return The tunnel configuration
+     * @throws SecurityException if user lacks required role
+     */
     @PreAuthorize("hasAnyRole('ADMIN')")
     @PutMapping("/tunnels/configure/{tunnelId}")
     public ResponseEntity<Tunnel> configureTunnelForEnvironment(@PathVariable String tunnelId, @AuthenticationPrincipal OidcUser user) {
         /*
-         *  * Returns 200 if an object is created or updated with a new representation of the object
+         * Returns 200 if an object is created or updated with a new representation of the object
-         *  * Returns 204 if the object state did not need any changing.
+         * Returns 204 if the object state did not need any changing.
-         *  * Returns 404 if the tunnelId is not valid
+         * Returns 404 if the tunnelId is not valid
          */
 
         try {

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Entity/Mapping.java

@@ -0,0 +1,86 @@
+package com.hithomelabs.cftunnels.Entity;
+
+import jakarta.persistence.*;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.util.UUID;
+
+/**
+ * JPA Entity representing an ingress mapping configuration for a Cloudflare Tunnel.
+ * 
+ * <p>A mapping defines how incoming traffic should be routed through the tunnel
+ * to your internal services. It specifies the protocol, port, and subdomain
+ * where the service will be accessible.</p>
+ * 
+ * <p>Database Table: {@code mappings}</p>
+ * 
+ * <p><b>Example Usage:</b></p>
+ * <pre>
+ * Mapping mapping = new Mapping();
+ * mapping.setPort(8080);
+ * mapping.setProtocol(Protocol.HTTP);
+ * mapping.setSubdomain("api");
+ * </pre>
+ * 
+ * @see Tunnel
+ * @see Protocol
+ * @see Request
+ */
+@Entity
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "mappings")
+public class Mapping {
+
+    /**
+     * Unique identifier for this mapping (auto-generated UUID).
+     */
+    @Id
+    @GeneratedValue
+    @Column(columnDefinition = "uuid", nullable = false, unique = true)
+    private UUID id;
+
+    /**
+     * Port number where the internal service is running.
+     * 
+     * <p>Example: 8080 for a Spring Boot application's default port.</p>
+     */
+    @Column(nullable = false)
+    private int port;
+
+    /**
+     * Protocol used for the connection.
+     * 
+     * <p>Supported values: HTTP, HTTPS, TCP, SSH</p>
+     * @see Protocol
+     */
+    @Enumerated(EnumType.STRING)
+    @Column(length = 10, nullable = false)
+    private Protocol protocol;
+
+    /**
+     * Subdomain prefix for accessing this service.
+     * 
+     * <p>Example: "api" would make the service available at
+     * {@code api.yourdomain.com}</p>
+     */
+    @Column(length = 50, nullable = false)
+    private String subdomain;
+
+    /**
+     * The tunnel this mapping is associated with.
+     * 
+     * <p>Each mapping belongs to exactly one tunnel.
+     * This is a lazy-loaded relationship to optimize performance.</p>
+     * 
+     * @see Tunnel
+     */
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "tunnel_id", nullable = false)
+    private Tunnel tunnel;
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Entity/Protocol.java

@@ -0,0 +1,43 @@
+package com.hithomelabs.cftunnels.Entity;
+
+/**
+ * Enum representing supported protocols for Cloudflare Tunnel ingress mappings.
+ * 
+ * <p>Cloudflare Tunnel supports multiple protocols for routing traffic
+ * to your internal services. This enum defines the available options.</p>
+ * 
+ * <p><b>Supported Protocols:</b></p>
+ * <ul>
+ *   <li>{@link #HTTP} - Standard HTTP protocol (port 80)</li>
+ *   <li>{@link #HTTPS} - Secure HTTP protocol (port 443)</li>
+ *   <li>{@link #TCP} - Raw TCP connections</li>
+ *   <li>{@link #SSH} - SSH protocol for remote access</li>
+ * </ul>
+ * 
+ * @see Mapping
+ */
+public enum Protocol {
+    /**
+     * HTTP protocol for web services.
+     * Typically used with internal services running on port 80.
+     */
+    HTTP,
+
+    /**
+     * HTTPS protocol for secure web services.
+     * Use this for services with TLS/SSL certificates.
+     */
+    HTTPS,
+
+    /**
+     * Raw TCP protocol for non-HTTP services.
+     * Useful for databases, message queues, or custom protocols.
+     */
+    TCP,
+
+    /**
+     * SSH protocol for secure shell access.
+     * Enables secure remote access to servers.
+     */
+    SSH
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Entity/Request.java

@@ -0,0 +1,120 @@
+package com.hithomelabs.cftunnels.Entity;
+
+import jakarta.persistence.*;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.util.UUID;
+
+/**
+ * JPA Entity representing a mapping change request in the approval workflow.
+ * 
+ * <p>This entity tracks requests to add or modify tunnel ingress mappings.
+ * It implements an approval workflow where:</p>
+ * <ul>
+ *   <li>Users create requests (status: PENDING)</li>
+ *   <li>Approvers review and approve/reject (status: APPROVED/REJECTED)</li>
+ * </ul>
+ * 
+ * <p><b>Database Table:</b> {@code requests}</p>
+ * 
+ * <p><b>Workflow:</b></p>
+ * <pre>
+ * 1. User submits mapping request via REST API
+ * 2. Request is created with PENDING status
+ * 3. APPROVER role reviews the request
+ * 4. If approved: mapping is applied to Cloudflare tunnel
+ * 5. If rejected: request is marked REJECTED
+ * </pre>
+ * 
+ * @see Mapping
+ * @see User
+ * @see RequestStatus
+ */
+@Entity
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "requests")
+public class Request {
+
+    /**
+     * Unique identifier for this request (auto-generated UUID).
+     */
+    @Id
+    @GeneratedValue
+    @Column(columnDefinition = "uuid", unique = true, nullable = false)
+    private UUID id;
+
+    /**
+     * The mapping configuration being requested.
+     * 
+     * <p>This is a one-to-one relationship - each request
+     * contains exactly one mapping configuration.</p>
+     * 
+     * @see Mapping
+     */
+    @OneToOne
+    @JoinColumn(name = "mapping_id", unique = true, nullable = false)
+    private Mapping mapping;
+
+    /**
+     * User who created this request.
+     * 
+     * <p>This field is required and tracks accountability.</p>
+     * 
+     * @see User
+     */
+    @ManyToOne
+    @JoinColumn(name = "created_by", nullable = false)
+    private User createdBy;
+
+    /**
+     * User who approved or rejected this request.
+     * 
+     * <p>This is null until the request is processed.</p>
+     * 
+     * @see User
+     */
+    @ManyToOne
+    @JoinColumn(name = "accepted_by")
+    private User acceptedBy;
+
+    /**
+     * Status of the mapping request in the workflow.
+     * 
+     * @see RequestStatus
+     */
+    public enum RequestStatus {
+        /**
+         * Request is waiting for approval.
+         */
+        PENDING,
+
+        /**
+         * Request has been approved.
+         * The mapping should now be applied to the tunnel.
+         */
+        APPROVED,
+
+        /**
+         * Request has been rejected.
+         * No changes will be made to the tunnel.
+         */
+        REJECTED
+    }
+
+    /**
+     * Current status of this request.
+     * 
+     * <p>Initially set to PENDING when created.</p>
+     * 
+     * @see RequestStatus
+     */
+    @Enumerated(EnumType.STRING)
+    @Column(length = 10, nullable = false)
+    private RequestStatus status;
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Entity/Tunnel.java

@@ -0,0 +1,67 @@
+package com.hithomelabs.cftunnels.Entity;
+
+import jakarta.persistence.*;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.util.UUID;
+
+/**
+ * JPA Entity representing a Cloudflare Tunnel configuration.
+ * 
+ * <p>This entity stores the locally cached configuration of a Cloudflare Tunnel,
+ * linking the tunnel's unique identifier from Cloudflare with its local
+ * environment name for easier reference and management.</p>
+ * 
+ * <p>The entity is uniquely constrained by tunnel ID and environment name,
+ * ensuring only one configuration exists per tunnel per environment.</p>
+ * 
+ * <p><b>Database Table:</b> {@code tunnels}</p>
+ * 
+ * <p><b>Relationships:</b></p>
+ * <ul>
+ *   <li>One Tunnel has many Mappings (via tunnel_id foreign key)</li>
+ * </ul>
+ * 
+ * @see Mapping
+ * @see Request
+ */
+@Entity
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "tunnels")
+public class Tunnel {
+
+    /**
+     * Unique identifier for the tunnel (UUID).
+     * 
+     * <p>This corresponds to the Cloudflare-assigned tunnel ID
+     * and serves as the primary key for this entity.</p>
+     */
+    @Id
+    @Column(columnDefinition = "uuid", insertable = false, updatable = false, nullable = false)
+    private UUID id;
+
+    /**
+     * Environment name associated with this tunnel configuration.
+     * 
+     * <p>Examples: "production", "staging", "development"</p>
+     * <p>Each tunnel can be configured for multiple environments.</p>
+     */
+    @Column(length = 10, unique = true, nullable = false)
+    private String environment;
+
+    /**
+     * Display name of the tunnel as configured in Cloudflare.
+     * 
+     * <p>This is the user-friendly name assigned to the tunnel
+     * when it was created in Cloudflare Zero Trust Dashboard
+     * or via the Cloudflare API.</p>
+     */
+    @Column(length = 50, unique = true, nullable = false)
+    private String name;
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Entity/User.java

@@ -0,0 +1,68 @@
+package com.hithomelabs.cftunnels.Entity;
+
+import jakarta.persistence.*;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.util.UUID;
+
+/**
+ * JPA Entity representing a user in the system.
+ * 
+ * <p>This entity stores user information synced from the OIDC provider
+ * during authentication. Users are assigned roles that determine their
+ * access levels to the API endpoints.</p>
+ * 
+ * <p><b>Database Table:</b> {@code users}</p>
+ * 
+ * <p><b>Roles:</b></p>
+ * <ul>
+ *   <li>USER - Basic access to view tunnels</li>
+ *   <li>DEVELOPER - Can create/modify mappings</li>
+ *   <li>APPROVER - Can approve/reject requests</li>
+ *   <li>ADMIN - Full access including tunnel configuration</li>
+ * </ul>
+ * 
+ * @see Request
+ * @see Mapping
+ */
+@Entity
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "users")
+public class User {
+
+    /**
+     * Unique identifier for the user (UUID).
+     * 
+     * <p>This corresponds to the user's ID in the OIDC provider.</p>
+     */
+    @Id
+    @GeneratedValue
+    @Column(columnDefinition = "uuid", insertable = false, updatable = false, nullable = false)
+    private UUID id;
+
+    /**
+     * User's display name.
+     * 
+     * <p>This is typically the full name from the OIDC provider.</p>
+     */
+    @Column(length = 50, nullable = false)
+    @Size(max = 50)
+    private String name;
+
+    /**
+     * User's email address.
+     * 
+     * <p>Used as the unique identifier for authentication
+     * and for associating users with their roles.</p>
+     */
+    @Column(length = 50, nullable = false)
+    @Size(max = 50)
+    private String email;
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Exceptions/ExternalServiceException.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Exceptions;
+package com.hithomelabs.cftunnels.Exceptions;
 
 public class ExternalServiceException extends RuntimeException {
     public ExternalServiceException(String message) { super(message); }

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Headers/AuthKeyEmailHeader.java

@@ -1,6 +1,6 @@
-package com.hithomelabs.CFTunnels.Headers;
+package com.hithomelabs.cftunnels.Headers;
 
-import com.hithomelabs.CFTunnels.Config.CloudflareConfig;
+import com.hithomelabs.cftunnels.Config.CloudflareConfig;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpHeaders;
 import org.springframework.stereotype.Component;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/Authorities.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 public class Authorities {
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/Config.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 import com.fasterxml.jackson.annotation.*;
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/Groups.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 public class Groups {
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/Ingress.java

@@ -0,0 +1,95 @@
+package com.hithomelabs.cftunnels.Models;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Model representing an ingress rule for a Cloudflare Tunnel.
+ * 
+ * <p>Ingress rules define how incoming requests should be routed through
+ * the tunnel to your internal services. Each rule specifies:</p>
+ * <ul>
+ *   <li>{@link #hostname} - The domain/subdomain to match</li>
+ *   <li>{@link #service} - The internal service URL</li>
+ *   <li>{@link #originRequest} - Optional settings for origin requests</li>
+ *   <li>{@link #path} - Optional path prefix to match</li>
+ * </ul>
+ * 
+ * <p><b>Example JSON:</b></p>
+ * <pre>
+ * {
+ *   "hostname": "api.example.com",
+ *   "service": "http://localhost:8080",
+ *   "originRequest": {
+ *     "noTLSVerify": true
+ *   },
+ *   "path": "/api"
+ * }
+ * </pre>
+ * 
+ * @see <a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/routing/ingress/">Cloudflare Ingress Docs</a>
+ */
+@NoArgsConstructor
+@AllArgsConstructor
+@Getter
+@Setter
+public class Ingress {
+
+    /**
+     * The target service URL.
+     * 
+     * <p>Format: {@code protocol://host:port}</p>
+     * <p>Example: {@code http://localhost:8080}</p>
+     */
+    private String service;
+
+    /**
+     * Hostname pattern to match for this ingress rule.
+     * 
+     * <p>Can be a full domain (api.example.com) or use wildcards 
+     * (*.example.com) to match subdomains.</p>
+     * <p>If null, this rule acts as a catch-all.</p>
+     */
+    private String hostname;
+
+    /**
+     * Optional settings for requests to the origin server.
+     * 
+     * <p>Supported options:</p>
+     * <ul>
+     *   <li>noTLSVerify - Skip TLS verification</li>
+     *   <li>connectTimeout - Connection timeout in seconds</li>
+     *   <li>tlsTimeout - TLS handshake timeout</li>
+     *   <li>httpHostHeader - Host header to send</li>
+     * </ul>
+     */
+    private Map<String, Object> originRequest;
+
+    /**
+     * Optional path to match before routing.
+     * 
+     * <p>Example: "/api" would only route requests with
+     * paths starting with /api to this service.</p>
+     */
+    private String path;
+
+    /**
+     * Removes an ingress rule by hostname from a list.
+     * 
+     * <p>This utility method finds and removes the first ingress
+     * matching the given hostname.</p>
+     * 
+     * @param ingressList  List of ingress rules to modify
+     * @param toBeDeleted Hostname of the rule to remove
+     * @return true if an ingress was removed, false otherwise
+     */
+    public static boolean deleteByHostName(List<Ingress> ingressList, String toBeDeleted){
+         return ingressList.removeIf(ingress -> ingress.getHostname() != null && ingress.getHostname().equals(toBeDeleted));
+    }
+
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/Result.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/TunnelResponse.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 import lombok.AllArgsConstructor;
 import lombok.Getter;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/TunnelResult.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import lombok.AllArgsConstructor;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Models/TunnelsResponse.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.Models;
+package com.hithomelabs.cftunnels.Models;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import lombok.AllArgsConstructor;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Repositories/MappingRepository.java

@@ -1,6 +1,6 @@
-package com.hithomelabs.CFTunnels.Repositories;
+package com.hithomelabs.cftunnels.Repositories;
 
-import com.hithomelabs.CFTunnels.Entity.Mapping;
+import com.hithomelabs.cftunnels.Entity.Mapping;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.stereotype.Repository;
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Repositories/RequestRepository.java

@@ -1,6 +1,6 @@
-package com.hithomelabs.CFTunnels.Repositories;
+package com.hithomelabs.cftunnels.Repositories;
 
-import com.hithomelabs.CFTunnels.Entity.Request;
+import com.hithomelabs.cftunnels.Entity.Request;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Repositories/TunnelRepository.java

@@ -1,6 +1,6 @@
-package com.hithomelabs.CFTunnels.Repositories;
+package com.hithomelabs.cftunnels.Repositories;
 
-import com.hithomelabs.CFTunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.stereotype.Repository;
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Repositories/UserRepository.java

@@ -1,6 +1,6 @@
-package com.hithomelabs.CFTunnels.Repositories;
+package com.hithomelabs.cftunnels.Repositories;
 
-import com.hithomelabs.CFTunnels.Entity.User;
+import com.hithomelabs.cftunnels.Entity.User;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.stereotype.Repository;
 

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Services/CloudflareAPIService.java

@@ -0,0 +1,203 @@
+package com.hithomelabs.cftunnels.Services;
+
+import com.hithomelabs.cftunnels.Config.CloudflareConfig;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Exceptions.ExternalServiceException;
+import com.hithomelabs.cftunnels.Headers.AuthKeyEmailHeader;
+import com.hithomelabs.cftunnels.Models.Config;
+import com.hithomelabs.cftunnels.Models.Ingress;
+import com.hithomelabs.cftunnels.Models.TunnelResponse;
+import com.hithomelabs.cftunnels.Models.TunnelResult;
+import com.hithomelabs.cftunnels.Models.TunnelsResponse;
+import com.hithomelabs.cftunnels.Repositories.TunnelRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.dao.DataAccessException;
+import org.springframework.http.*;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.List;
+import java.util.Map;
+import java.util.NoSuchElementException;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Service for interacting with the Cloudflare Tunnel API.
+ * 
+ * <p>This service provides methods to manage Cloudflare Tunnels,
+ * including fetching tunnel configurations, creating/updating tunnels,
+ * and adding ingress mappings. It handles all communication with the
+ * Cloudflare API using the configured credentials.</p>
+ * 
+ * <p><b>API Endpoints Used:</b></p>
+ * <ul>
+ *   <li>GET /accounts/{accountId}/cfd_tunnel - List all tunnels</li>
+ *   <li>GET /accounts/{accountId}/cfd_tunnel/{tunnelId}/configurations - Get tunnel config</li>
+ *   <li>PUT /accounts/{accountId}/cfd_tunnel/{tunnelId}/configurations - Update tunnel config</li>
+ * </ul>
+ * 
+ * @see CloudflareConfig
+ * @see Tunnel
+ * @see Ingress
+ */
+@Service
+public class CloudflareAPIService {
+
+    /**
+     * Configuration for Cloudflare API credentials and settings.
+     * Loaded from application.properties using the {@code cloudflare.*} prefix.
+     */
+    @Autowired
+    CloudflareConfig cloudflareConfig;
+
+    /**
+     * Header provider for Cloudflare API authentication.
+     * Generates the X-Auth-Key and X-Auth-Email headers.
+     */
+    @Autowired
+    AuthKeyEmailHeader authKeyEmailHeader;
+
+    /**
+     * HTTP client for making API requests.
+     */
+    @Autowired
+    RestTemplate restTemplate;
+
+    /**
+     * Repository for storing tunnel configurations locally.
+     */
+    @Autowired
+    TunnelRepository tunnelRepository;
+
+    /**
+     * Fetches all Cloudflare tunnels from the API.
+     * 
+     * @return Response containing the list of tunnels from Cloudflare
+     * @see TunnelsResponse
+     */
+    public ResponseEntity<TunnelsResponse> getCloudflareTunnels() {
+
+        String url = "https://api.cloudflare.com/client/v4/accounts/" + cloudflareConfig.getAccountId() + "/cfd_tunnel";
+
+        HttpEntity<String> httpEntity = new HttpEntity<>("", authKeyEmailHeader.getHttpHeaders());
+        ResponseEntity<TunnelsResponse> responseEntity = restTemplate.exchange(url, HttpMethod.GET, httpEntity, TunnelsResponse.class);
+        return responseEntity;
+    }
+
+    /**
+     * Fetches the configuration for a specific tunnel.
+     * 
+     * @param tunnelId      The Cloudflare tunnel ID (UUID string)
+     * @param restTemplate HTTP client to use for the request
+     * @param responseType Class to deserialize the response into
+     * @param <T>         Response type
+     * @return Response containing the tunnel configuration
+     */
+    public <T> ResponseEntity<T> getCloudflareTunnelConfigurations(String tunnelId, RestTemplate restTemplate, Class<T> responseType) {
+
+        // Resource URL to hit get request at
+        String url = "https://api.cloudflare.com/client/v4/accounts/" + cloudflareConfig.getAccountId() + "/cfd_tunnel/" + tunnelId + "/configurations";
+
+        HttpEntity<String> httpEntity = new HttpEntity<>("",authKeyEmailHeader.getHttpHeaders());
+        ResponseEntity<T> responseEntity = restTemplate.exchange(url, HttpMethod.GET, httpEntity, responseType);
+        return responseEntity;
+    }
+
+    /**
+     * Updates the configuration for a specific tunnel.
+     * 
+     * <p>This method is used to add, modify, or remove ingress mappings
+     * by providing a complete configuration object.</p>
+     * 
+     * @param tunnelId      The Cloudflare tunnel ID (UUID string)
+     * @param restTemplate HTTP client to use for the request
+     * @param responseType Class to deserialize the response into
+     * @param config      The new configuration to apply
+     * @param <T>        Response type
+     * @return Response containing the updated tunnel configuration
+     */
+    public <T> ResponseEntity<T> putCloudflareTunnelConfigurations(String tunnelId, RestTemplate restTemplate, Class<T> responseType, Config config) {
+
+        // Resource URL to hit get request at
+        String url = "https://api.cloudflare.com/client/v4/accounts/" + cloudflareConfig.getAccountId() + "/cfd_tunnel/" + tunnelId + "/configurations";
+
+        HttpHeaders httpHeaders = authKeyEmailHeader.getHttpHeaders();
+        httpHeaders.setContentType(MediaType.APPLICATION_JSON);
+        HttpEntity<Config> entity = new HttpEntity<>(config, httpHeaders);
+        ResponseEntity<T> responseEntity = restTemplate.exchange(url, HttpMethod.PUT, entity, responseType);
+        return responseEntity;
+    }
+
+    /**
+     * Converts a Cloudflare API tunnel result to a local Tunnel entity.
+     * 
+     * @param tunnelResult The tunnel result from Cloudflare API
+     * @param env          The environment name to associate
+     * @return New Tunnel entity instance
+     */
+    private Tunnel getTunnelFromTunnelResponse(TunnelResult tunnelResult, String env){
+        return new Tunnel(UUID.fromString(tunnelResult.getId()), env, tunnelResult.getName());
+    }
+
+    /**
+     * Creates or updates a tunnel's local configuration.
+     * 
+     * <p>This method fetches the tunnel from Cloudflare API, validates it exists,
+     * and stores a local copy with the environment association.</p>
+     * 
+     * @param tunnelId    The Cloudflare tunnel ID
+     * @param environment Environment name (e.g., "production", "staging")
+     * @return The created or updated Tunnel entity
+     * @throws ExternalServiceException if Cloudflare API returns an error
+     * @throws NoSuchElementException if the tunnel doesn't exist in Cloudflare
+     */
+    public Tunnel createOrUpdateTunnel(String tunnelId, String environment) throws ExternalServiceException, NoSuchElementException  {
+
+        ResponseEntity<TunnelsResponse> responseEntity = getCloudflareTunnels();
+
+        if (responseEntity.getStatusCode().isError())
+            throw new ExternalServiceException("Cloudflare API error: " + responseEntity.getStatusCode());
+
+        TunnelResult tunnelResult = responseEntity.getBody().getResult().stream().filter(t -> t.getId().equals(tunnelId)).findFirst().orElse(null);
+        if (tunnelResult == null)
+            throw new NoSuchElementException();
+
+        Tunnel toBeConfigured = getTunnelFromTunnelResponse(tunnelResult, environment);
+        Tunnel fromDatabase = tunnelRepository.findById(UUID.fromString(tunnelId)).orElse(null);
+
+        if (fromDatabase != null)
+            tunnelRepository.deleteById(UUID.fromString(tunnelId));
+        tunnelRepository.save(toBeConfigured);
+        return toBeConfigured;
+    }
+
+    /**
+     * Retrieves all tunnels that have been locally configured.
+     * 
+     * @return List of locally configured tunnels
+     */
+    public List<Tunnel> getAllConfiguredTunnels() {
+        return tunnelRepository.findAll();
+    }
+
+    /**
+     * Adds an ingress mapping to an existing tunnel.
+     * 
+     * <p>The new ingress is inserted at the second-to-last position in the
+     * ingress list (Cloudflare requires a catch-all rule at the end).</p>
+     * 
+     * @param tunnelId The Cloudflare tunnel ID
+     * @param ingress  The ingress configuration to add
+     * @return Response with the updated tunnel configuration
+     */
+    public ResponseEntity<TunnelResponse> addTunnelIngress(String tunnelId, Ingress ingress) {
+        ResponseEntity<TunnelResponse> currentConfig = getCloudflareTunnelConfigurations(tunnelId, restTemplate, TunnelResponse.class);
+        
+        Config config = currentConfig.getBody().getResult().getConfig();
+        List<Ingress> ingressList = config.getIngress();
+        ingressList.add(ingressList.size() - 1, ingress);
+        
+        return putCloudflareTunnelConfigurations(tunnelId, restTemplate, TunnelResponse.class, config);
+    }
+}

cftunnels-service/src/main/java/com/hithomelabs/cftunnels/Services/MappingRequestService.java

@@ -1,15 +1,15 @@
-package com.hithomelabs.CFTunnels.Services;
+package com.hithomelabs.cftunnels.Services;
 
-import com.hithomelabs.CFTunnels.Entity.Mapping;
+import com.hithomelabs.cftunnels.Entity.Mapping;
-import com.hithomelabs.CFTunnels.Entity.Protocol;
+import com.hithomelabs.cftunnels.Entity.Protocol;
-import com.hithomelabs.CFTunnels.Entity.Request;
+import com.hithomelabs.cftunnels.Entity.Request;
-import com.hithomelabs.CFTunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
-import com.hithomelabs.CFTunnels.Entity.User;
+import com.hithomelabs.cftunnels.Entity.User;
-import com.hithomelabs.CFTunnels.Models.Ingress;
+import com.hithomelabs.cftunnels.Models.Ingress;
-import com.hithomelabs.CFTunnels.Repositories.MappingRepository;
+import com.hithomelabs.cftunnels.Repositories.MappingRepository;
-import com.hithomelabs.CFTunnels.Repositories.RequestRepository;
+import com.hithomelabs.cftunnels.Repositories.RequestRepository;
-import com.hithomelabs.CFTunnels.Repositories.TunnelRepository;
+import com.hithomelabs.cftunnels.Repositories.TunnelRepository;
-import com.hithomelabs.CFTunnels.Repositories.UserRepository;
+import com.hithomelabs.cftunnels.Repositories.UserRepository;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.oauth2.core.oidc.user.OidcUser;

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

@@ -5,3 +5,7 @@ spring.datasource.driver-class-name=org.h2.Driver
 spring.datasource.username=sa
 spring.datasource.password=
 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
+# Actuator configuration for local development
-management.endpoints.web.exposure.include=health
+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

@@ -10,3 +10,7 @@ spring.datasource.driver-class-name=org.postgresql.Driver
 spring.jpa.hibernate.ddl-auto=create-drop
 spring.jpa.show-sql=false
 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

@@ -2,9 +2,9 @@ spring.application.name=CFTunnels
 cloudflare.accountId=${CLOUDFLARE_ACCOUNT_ID}
 cloudflare.apiKey=${CLOUDFLARE_API_KEY}
 cloudflare.email=${CLOUDFLARE_EMAIL}
-spring.profiles.active=${ENV}
+spring.profiles.active=${ENV:default}
 
-/ * * Masking sure app works behind a reverse proxy
+# Making sure app works behind a reverse proxy
 server.forward-headers-strategy=framework
 
 spring.security.oauth2.client.registration.cftunnels.client-id=${OAUTH_CLIENT_ID}
@@ -36,3 +36,8 @@ spring.jpa.show-sql=true
 spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
 
 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

cftunnels-service/src/test/java/com/hithomelabs/cftunnels/CfTunnelsApplicationTests.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels;
+package com.hithomelabs.cftunnels;
 
 import org.junit.jupiter.api.Test;
 import org.springframework.boot.test.context.SpringBootTest;

cftunnels-service/src/test/java/com/hithomelabs/cftunnels/Controllers/TunnelControllerTest.java

@@ -1,21 +1,21 @@
-package com.hithomelabs.CFTunnels.Controllers;
+package com.hithomelabs.cftunnels.Controllers;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.hithomelabs.CFTunnels.Config.AuthoritiesToGroupMapping;
+import com.hithomelabs.cftunnels.Config.AuthoritiesToGroupMapping;
-import com.hithomelabs.CFTunnels.Config.CloudflareConfig;
+import com.hithomelabs.cftunnels.Config.CloudflareConfig;
-import com.hithomelabs.CFTunnels.Config.RestTemplateConfig;
+import com.hithomelabs.common.config.RestTemplateConfig;
-import com.hithomelabs.CFTunnels.Headers.AuthKeyEmailHeader;
+import com.hithomelabs.cftunnels.Headers.AuthKeyEmailHeader;
-import com.hithomelabs.CFTunnels.Entity.Request;
+import com.hithomelabs.cftunnels.Entity.Request;
-import com.hithomelabs.CFTunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
-import com.hithomelabs.CFTunnels.Models.Authorities;
+import com.hithomelabs.cftunnels.Models.Authorities;
-import com.hithomelabs.CFTunnels.Models.Config;
+import com.hithomelabs.cftunnels.Models.Config;
-import com.hithomelabs.CFTunnels.Models.Groups;
+import com.hithomelabs.cftunnels.Models.Groups;
-import com.hithomelabs.CFTunnels.Models.TunnelResponse;
+import com.hithomelabs.cftunnels.Models.TunnelResponse;
-import com.hithomelabs.CFTunnels.Models.TunnelResult;
+import com.hithomelabs.cftunnels.Models.TunnelResult;
-import com.hithomelabs.CFTunnels.Models.TunnelsResponse;
+import com.hithomelabs.cftunnels.Models.TunnelsResponse;
-import com.hithomelabs.CFTunnels.Repositories.UserRepository;
+import com.hithomelabs.cftunnels.Repositories.UserRepository;
-import com.hithomelabs.CFTunnels.Services.CloudflareAPIService;
+import com.hithomelabs.cftunnels.Services.CloudflareAPIService;
-import com.hithomelabs.CFTunnels.Services.MappingRequestService;
+import com.hithomelabs.cftunnels.Services.MappingRequestService;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -38,7 +38,7 @@ import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageImpl;
 import org.springframework.data.domain.PageRequest;
 
-import static com.hithomelabs.CFTunnels.TestUtils.Util.getClassPathDataResource;
+import static com.hithomelabs.cftunnels.TestUtils.Util.getClassPathDataResource;
 import static org.hamcrest.core.IsIterableContaining.hasItem;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
@@ -207,9 +207,9 @@ class TunnelControllerTest {
     @Test
     @DisplayName("should return list of requests")
     void getAllRequests_Success() throws Exception {
-        List<com.hithomelabs.CFTunnels.Entity.Request> requests = Arrays.asList(
+        List<com.hithomelabs.cftunnels.Entity.Request> requests = Arrays.asList(
-                createTestRequest(UUID.randomUUID(), com.hithomelabs.CFTunnels.Entity.Request.RequestStatus.PENDING),
+                createTestRequest(UUID.randomUUID(), com.hithomelabs.cftunnels.Entity.Request.RequestStatus.PENDING),
-                createTestRequest(UUID.randomUUID(), com.hithomelabs.CFTunnels.Entity.Request.RequestStatus.APPROVED)
+                createTestRequest(UUID.randomUUID(), com.hithomelabs.cftunnels.Entity.Request.RequestStatus.APPROVED)
         );
         
         when(mappingRequestService.getAllRequests()).thenReturn(requests);
@@ -227,11 +227,11 @@ class TunnelControllerTest {
     @DisplayName("should create mapping request successfully")
     void createTunnelMappingRequest_Success() throws Exception {
         UUID tunnelId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.Request createdRequest = new com.hithomelabs.CFTunnels.Entity.Request();
+        com.hithomelabs.cftunnels.Entity.Request createdRequest = new com.hithomelabs.cftunnels.Entity.Request();
         createdRequest.setId(UUID.randomUUID());
-        createdRequest.setStatus(com.hithomelabs.CFTunnels.Entity.Request.RequestStatus.PENDING);
+        createdRequest.setStatus(com.hithomelabs.cftunnels.Entity.Request.RequestStatus.PENDING);
 
-        when(mappingRequestService.createMappingRequest(any(String.class), any(com.hithomelabs.CFTunnels.Models.Ingress.class), any())).thenReturn(createdRequest);
+        when(mappingRequestService.createMappingRequest(any(String.class), any(com.hithomelabs.cftunnels.Models.Ingress.class), any())).thenReturn(createdRequest);
 
         mockMvc.perform(post("/cloudflare/tunnels/configure/{tunnelId}/requests", tunnelId.toString())
                         .with(oauth2Login().oauth2User(buildOidcUser("developer", Groups.HOMELAB_DEVELOPER)))
@@ -247,15 +247,15 @@ class TunnelControllerTest {
     @DisplayName("should approve mapping request successfully")
     void approveMappingRequest_Success() throws Exception {
         UUID requestId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.User approverUser = new com.hithomelabs.CFTunnels.Entity.User();
+        com.hithomelabs.cftunnels.Entity.User approverUser = new com.hithomelabs.cftunnels.Entity.User();
         approverUser.setEmail("approver@example.com");
         approverUser.setName("Approver");
 
-        com.hithomelabs.CFTunnels.Entity.Request approvedRequest = new com.hithomelabs.CFTunnels.Entity.Request();
+        com.hithomelabs.cftunnels.Entity.Request approvedRequest = new com.hithomelabs.cftunnels.Entity.Request();
         approvedRequest.setId(requestId);
-        approvedRequest.setStatus(com.hithomelabs.CFTunnels.Entity.Request.RequestStatus.APPROVED);
+        approvedRequest.setStatus(com.hithomelabs.cftunnels.Entity.Request.RequestStatus.APPROVED);
 
-        when(mappingRequestService.approveRequest(eq(requestId), any(com.hithomelabs.CFTunnels.Entity.User.class)))
+        when(mappingRequestService.approveRequest(eq(requestId), any(com.hithomelabs.cftunnels.Entity.User.class)))
                 .thenReturn(approvedRequest);
         when(userRepository.findByEmail("approver@example.com"))
                 .thenReturn(java.util.Optional.of(approverUser));
@@ -272,11 +272,11 @@ class TunnelControllerTest {
     @DisplayName("should return 404 when request not found")
     void approveMappingRequest_NotFound() throws Exception {
         UUID requestId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.User approverUser = new com.hithomelabs.CFTunnels.Entity.User();
+        com.hithomelabs.cftunnels.Entity.User approverUser = new com.hithomelabs.cftunnels.Entity.User();
         approverUser.setEmail("approver@example.com");
         approverUser.setName("Approver");
 
-        when(mappingRequestService.approveRequest(eq(requestId), any(com.hithomelabs.CFTunnels.Entity.User.class)))
+        when(mappingRequestService.approveRequest(eq(requestId), any(com.hithomelabs.cftunnels.Entity.User.class)))
                 .thenThrow(new NoSuchElementException("Request not found"));
         when(userRepository.findByEmail("approver@example.com"))
                 .thenReturn(java.util.Optional.of(approverUser));
@@ -291,11 +291,11 @@ class TunnelControllerTest {
     @DisplayName("should return 500 when mapping creation fails")
     void approveMappingRequest_InternalServerError() throws Exception {
         UUID requestId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.User approverUser = new com.hithomelabs.CFTunnels.Entity.User();
+        com.hithomelabs.cftunnels.Entity.User approverUser = new com.hithomelabs.cftunnels.Entity.User();
         approverUser.setEmail("approver@example.com");
         approverUser.setName("Approver");
 
-        when(mappingRequestService.approveRequest(eq(requestId), any(com.hithomelabs.CFTunnels.Entity.User.class)))
+        when(mappingRequestService.approveRequest(eq(requestId), any(com.hithomelabs.cftunnels.Entity.User.class)))
                 .thenThrow(new RuntimeException("Failed to add mapping to Cloudflare"));
         when(userRepository.findByEmail("approver@example.com"))
                 .thenReturn(java.util.Optional.of(approverUser));
@@ -310,15 +310,15 @@ class TunnelControllerTest {
     @DisplayName("should reject mapping request successfully")
     void rejectMappingRequest_Success() throws Exception {
         UUID requestId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.User rejecterUser = new com.hithomelabs.CFTunnels.Entity.User();
+        com.hithomelabs.cftunnels.Entity.User rejecterUser = new com.hithomelabs.cftunnels.Entity.User();
         rejecterUser.setEmail("rejecter@example.com");
         rejecterUser.setName("Rejecter");
 
-        com.hithomelabs.CFTunnels.Entity.Request rejectedRequest = new com.hithomelabs.CFTunnels.Entity.Request();
+        com.hithomelabs.cftunnels.Entity.Request rejectedRequest = new com.hithomelabs.cftunnels.Entity.Request();
         rejectedRequest.setId(requestId);
-        rejectedRequest.setStatus(com.hithomelabs.CFTunnels.Entity.Request.RequestStatus.REJECTED);
+        rejectedRequest.setStatus(com.hithomelabs.cftunnels.Entity.Request.RequestStatus.REJECTED);
 
-        when(mappingRequestService.rejectRequest(eq(requestId), any(com.hithomelabs.CFTunnels.Entity.User.class)))
+        when(mappingRequestService.rejectRequest(eq(requestId), any(com.hithomelabs.cftunnels.Entity.User.class)))
                 .thenReturn(rejectedRequest);
         when(userRepository.findByEmail("rejecter@example.com"))
                 .thenReturn(java.util.Optional.of(rejecterUser));
@@ -335,11 +335,11 @@ class TunnelControllerTest {
     @DisplayName("should return 404 when rejecting non-existent request")
     void rejectMappingRequest_NotFound() throws Exception {
         UUID requestId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.User rejecterUser = new com.hithomelabs.CFTunnels.Entity.User();
+        com.hithomelabs.cftunnels.Entity.User rejecterUser = new com.hithomelabs.cftunnels.Entity.User();
         rejecterUser.setEmail("rejecter@example.com");
         rejecterUser.setName("Rejecter");
 
-        when(mappingRequestService.rejectRequest(eq(requestId), any(com.hithomelabs.CFTunnels.Entity.User.class)))
+        when(mappingRequestService.rejectRequest(eq(requestId), any(com.hithomelabs.cftunnels.Entity.User.class)))
                 .thenThrow(new NoSuchElementException("Request not found"));
         when(userRepository.findByEmail("rejecter@example.com"))
                 .thenReturn(java.util.Optional.of(rejecterUser));
@@ -354,11 +354,11 @@ class TunnelControllerTest {
     @DisplayName("should return 409 when rejecting already processed request")
     void rejectMappingRequest_Conflict() throws Exception {
         UUID requestId = UUID.randomUUID();
-        com.hithomelabs.CFTunnels.Entity.User rejecterUser = new com.hithomelabs.CFTunnels.Entity.User();
+        com.hithomelabs.cftunnels.Entity.User rejecterUser = new com.hithomelabs.cftunnels.Entity.User();
         rejecterUser.setEmail("rejecter@example.com");
         rejecterUser.setName("Rejecter");
 
-        when(mappingRequestService.rejectRequest(eq(requestId), any(com.hithomelabs.CFTunnels.Entity.User.class)))
+        when(mappingRequestService.rejectRequest(eq(requestId), any(com.hithomelabs.cftunnels.Entity.User.class)))
                 .thenThrow(new IllegalStateException("Request is not in PENDING status"));
         when(userRepository.findByEmail("rejecter@example.com"))
                 .thenReturn(java.util.Optional.of(rejecterUser));

cftunnels-service/src/test/java/com/hithomelabs/cftunnels/Integration/CoudflareApiIntegrationTest.java

@@ -1,13 +1,13 @@
-package com.hithomelabs.CFTunnels.Integration;
+package com.hithomelabs.cftunnels.Integration;
 
-import com.hithomelabs.CFTunnels.Config.CloudflareConfig;
+import com.hithomelabs.cftunnels.Config.CloudflareConfig;
-import com.hithomelabs.CFTunnels.Headers.AuthKeyEmailHeader;
+import com.hithomelabs.cftunnels.Headers.AuthKeyEmailHeader;
-import com.hithomelabs.CFTunnels.Models.Config;
+import com.hithomelabs.cftunnels.Models.Config;
-import com.hithomelabs.CFTunnels.Models.Ingress;
+import com.hithomelabs.cftunnels.Models.Ingress;
-import com.hithomelabs.CFTunnels.Models.TunnelResponse;
+import com.hithomelabs.cftunnels.Models.TunnelResponse;
-import com.hithomelabs.CFTunnels.Models.TunnelResult;
+import com.hithomelabs.cftunnels.Models.TunnelResult;
-import com.hithomelabs.CFTunnels.Models.TunnelsResponse;
+import com.hithomelabs.cftunnels.Models.TunnelsResponse;
-import com.hithomelabs.CFTunnels.Services.CloudflareAPIService;
+import com.hithomelabs.cftunnels.Services.CloudflareAPIService;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;

cftunnels-service/src/test/java/com/hithomelabs/cftunnels/Repositories/RequestRepositoryTest.java

@@ -1,10 +1,10 @@
-package com.hithomelabs.CFTunnels.Repositories;
+package com.hithomelabs.cftunnels.Repositories;
 
-import com.hithomelabs.CFTunnels.Entity.Mapping;
+import com.hithomelabs.cftunnels.Entity.Mapping;
-import com.hithomelabs.CFTunnels.Entity.Protocol;
+import com.hithomelabs.cftunnels.Entity.Protocol;
-import com.hithomelabs.CFTunnels.Entity.Request;
+import com.hithomelabs.cftunnels.Entity.Request;
-import com.hithomelabs.CFTunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
-import com.hithomelabs.CFTunnels.Entity.User;
+import com.hithomelabs.cftunnels.Entity.User;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;

cftunnels-service/src/test/java/com/hithomelabs/cftunnels/Services/CloudflareAPIServiceTest.java

@@ -1,17 +1,17 @@
-package com.hithomelabs.CFTunnels.Services;
+package com.hithomelabs.cftunnels.Services;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
-import com.hithomelabs.CFTunnels.Config.CloudflareConfig;
+import com.hithomelabs.cftunnels.Config.CloudflareConfig;
-import com.hithomelabs.CFTunnels.Entity.Tunnel;
+import com.hithomelabs.cftunnels.Entity.Tunnel;
-import com.hithomelabs.CFTunnels.Exceptions.ExternalServiceException;
+import com.hithomelabs.cftunnels.Exceptions.ExternalServiceException;
-import com.hithomelabs.CFTunnels.Headers.AuthKeyEmailHeader;
+import com.hithomelabs.cftunnels.Headers.AuthKeyEmailHeader;
-import com.hithomelabs.CFTunnels.Models.Config;
+import com.hithomelabs.cftunnels.Models.Config;
-import com.hithomelabs.CFTunnels.Models.Ingress;
+import com.hithomelabs.cftunnels.Models.Ingress;
-import com.hithomelabs.CFTunnels.Models.TunnelResponse;
+import com.hithomelabs.cftunnels.Models.TunnelResponse;
-import com.hithomelabs.CFTunnels.Models.TunnelResult;
+import com.hithomelabs.cftunnels.Models.TunnelResult;
-import com.hithomelabs.CFTunnels.Models.TunnelsResponse;
+import com.hithomelabs.cftunnels.Models.TunnelsResponse;
-import com.hithomelabs.CFTunnels.Repositories.TunnelRepository;
+import com.hithomelabs.cftunnels.Repositories.TunnelRepository;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.InjectMocks;
@@ -26,7 +26,7 @@ import java.util.NoSuchElementException;
 import java.util.Optional;
 import java.util.UUID;
 
-import static com.hithomelabs.CFTunnels.TestUtils.Util.getClassPathDataResource;
+import static com.hithomelabs.cftunnels.TestUtils.Util.getClassPathDataResource;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.mockito.ArgumentMatchers.any;

cftunnels-service/src/test/java/com/hithomelabs/cftunnels/TestUtils/Util.java

@@ -1,4 +1,4 @@
-package com.hithomelabs.CFTunnels.TestUtils;
+package com.hithomelabs.cftunnels.TestUtils;
 
 import org.springframework.core.io.ClassPathResource;
 

common/build.gradle

@@ -0,0 +1,13 @@
+dependencies {
+    implementation 'org.springframework:spring-context'
+    implementation 'org.springframework:spring-web'
+    implementation 'com.fasterxml.jackson.core:jackson-databind'
+    implementation 'org.apache.httpcomponents.client5:httpclient5'
+
+    compileOnly 'org.projectlombok:lombok'
+    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

@@ -0,0 +1,34 @@
+package com.hithomelabs.common.config;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+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() {
+        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));
+        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

@@ -1,27 +1,10 @@
 services:
-  frontend:
-    build:
-      context: ./frontend
-      args:
-        - OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}
-        - OAUTH_REDIRECT_URI=${OAUTH_REDIRECT_URI}
-    container_name: cftunnels-frontend_${ENV}
-    ports:
-      - "${FRONTEND_PORT:-80}:80"
-    environment:
-      - OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}
-      - OAUTH_REDIRECT_URI=${OAUTH_REDIRECT_URI}
-    depends_on:
-      - app
-    restart: unless-stopped
-    networks:
-      - cftunnels-network
-
   app:
     image: gitea.hithomelabs.com/hithomelabs/cftunnels:${ENV}
     container_name: cftunnels_${ENV}
     ports:
-      - "${HOST_PORT:-8080}:8080"
+      - ${HOST_PORT}:8080
+      - ${MGMT_PORT:-5003}:8081
     environment:
       - CLOUDFLARE_ACCOUNT_ID=${CLOUDFLARE_ACCOUNT_ID}
       - CLOUDFLARE_API_KEY=${CLOUDFLARE_API_KEY}
@@ -35,12 +18,7 @@ services:
       - SWAGGER_OAUTH_CLIENT_ID=${SWAGGER_OAUTH_CLIENT_ID}
     env_file:
       - stack.env
-    depends_on:
-      - postgres
     restart: unless-stopped
-    networks:
-      - cftunnels-network
-
   postgres:
     image: postgres:15-alpine
     container_name: cftunnel-db-${ENV}
@@ -50,12 +28,6 @@ services:
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
     restart: unless-stopped
     ports:
-      - "${DB_PORT:-5432}:5432"
+      - "${DB_PORT}:5432"
     volumes:
       - ${DB_PATH}:/var/lib/postgresql/data
-    networks:
-      - cftunnels-network
-
-networks:
-  cftunnels-network:
-    driver: bridge

frontend/.dockerignore

@@ -1,24 +0,0 @@
-# Dependencies
-node_modules/
-
-# Build output
-dist/
-.angular/
-
-# IDE
-.idea/
-.vscode/
-
-# OS
-.DS_Store
-
-# Logs
-*.log
-npm-debug.log*
-
-# Test
-coverage/
-
-# Misc
-*.tgz
-.cache/

frontend/.gitignore

@@ -1,32 +0,0 @@
-# Dependencies
-node_modules/
-
-# Build output
-dist/
-.angular/
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Environment files (keep template)
-# environment.ts is generated from environment.*.ts by Angular CLI
-
-# Test coverage
-coverage/
-
-# Logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-# Misc
-*.tgz
-.cache/

frontend/Dockerfile

@@ -1,38 +0,0 @@
-FROM node:20-alpine AS build
-
-WORKDIR /app
-
-# Copy package files
-COPY package.json package-lock.json ./
-
-# Install dependencies
-RUN npm ci
-
-# Copy source files
-COPY . .
-
-# Build arguments for OIDC config
-ARG OAUTH_CLIENT_ID=cftunnels
-ARG OAUTH_REDIRECT_URI=http://localhost:80/login
-
-# Set build-time environment variables
-ENV OAUTH_CLIENT_ID=$OAUTH_CLIENT_ID
-ENV OAUTH_REDIRECT_URI=$OAUTH_REDIRECT_URI
-
-# Build the application
-RUN npm run build
-
-# Production stage
-FROM nginx:alpine
-
-# Copy built files
-COPY --from=build /app/dist/cftunnels-frontend/browser /usr/share/nginx/html
-
-# Copy nginx configuration
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-
-# Expose port
-EXPOSE 80
-
-# Start nginx
-CMD ["nginx", "-g", "daemon off;"]

frontend/angular.json

@@ -1,121 +0,0 @@
-{
-  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
-  "version": 1,
-  "newProjectRoot": "projects",
-  "projects": {
-    "cftunnels-frontend": {
-      "projectType": "application",
-      "schematics": {
-        "@schematics/angular:component": {
-          "style": "scss",
-          "standalone": true
-        },
-        "@schematics/angular:directive": {
-          "standalone": true
-        },
-        "@schematics/angular:pipe": {
-          "standalone": true
-        }
-      },
-      "root": "",
-      "sourceRoot": "src",
-      "prefix": "app",
-      "architect": {
-        "build": {
-          "builder": "@angular-devkit/build-angular:application",
-          "options": {
-            "outputPath": "dist/cftunnels-frontend",
-            "index": "src/index.html",
-            "browser": "src/main.ts",
-            "polyfills": ["zone.js"],
-            "tsConfig": "tsconfig.app.json",
-            "inlineStyleLanguage": "scss",
-            "assets": ["src/favicon.ico", "src/assets"],
-            "styles": ["src/styles.scss"],
-            "scripts": []
-          },
-          "configurations": {
-            "production": {
-              "budgets": [
-                {
-                  "type": "initial",
-                  "maximumWarning": "500kb",
-                  "maximumError": "1mb"
-                },
-                {
-                  "type": "anyComponentStyle",
-                  "maximumWarning": "2kb",
-                  "maximumError": "4kb"
-                }
-              ],
-              "outputHashing": "all",
-              "fileReplacements": [
-                {
-                  "replace": "src/environments/environment.ts",
-                  "with": "src/environments/environment.prod.ts"
-                }
-              ]
-            },
-            "development": {
-              "optimization": false,
-              "extractLicenses": false,
-              "sourceMap": true
-            },
-            "local": {
-              "optimization": false,
-              "extractLicenses": false,
-              "sourceMap": true,
-              "fileReplacements": [
-                {
-                  "replace": "src/environments/environment.ts",
-                  "with": "src/environments/environment.local.ts"
-                }
-              ]
-            },
-            "test": {
-              "optimization": false,
-              "extractLicenses": false,
-              "sourceMap": true,
-              "fileReplacements": [
-                {
-                  "replace": "src/environments/environment.ts",
-                  "with": "src/environments/environment.test.ts"
-                }
-              ]
-            }
-          },
-          "defaultConfiguration": "production"
-        },
-        "serve": {
-          "builder": "@angular-devkit/build-angular:dev-server",
-          "configurations": {
-            "production": {
-              "buildTarget": "cftunnels-frontend:build:production"
-            },
-            "development": {
-              "buildTarget": "cftunnels-frontend:build:development"
-            },
-            "local": {
-              "buildTarget": "cftunnels-frontend:build:local"
-            },
-            "test": {
-              "buildTarget": "cftunnels-frontend:build:test"
-            }
-          },
-          "defaultConfiguration": "development"
-        },
-        "test": {
-          "builder": "@angular-devkit/build-angular:karma",
-          "options": {
-            "polyfills": ["zone.js", "zone.js/testing"],
-            "tsConfig": "tsconfig.spec.json",
-            "inlineStyleLanguage": "scss",
-            "assets": ["src/favicon.ico", "src/assets"],
-            "styles": ["src/styles.scss"],
-            "scripts": []
-          }
-        }
-      }
-    }
-  }
-}

frontend/nginx.conf

@@ -1,40 +0,0 @@
-server {
-    listen 80;
-    root /usr/share/nginx/html;
-    index index.html;
-
-    # Gzip compression
-    gzip on;
-    gzip_vary on;
-    gzip_min_length 1024;
-    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;
-
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # Proxy API calls to backend
-    location /cloudflare/ {
-        proxy_pass http://app:8080/cloudflare/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        
-        # Timeouts
-        proxy_connect_timeout 60s;
-        proxy_send_timeout 60s;
-        proxy_read_timeout 60s;
-    }
-
-    # Cache static assets
-    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
-        expires 1y;
-        add_header Cache-Control "public, immutable";
-    }
-
-    # Security headers
-    add_header X-Frame-Options "DENY" always;
-    add_header X-Content-Type-Options "nosniff" always;
-    add_header X-XSS-Protection "1; mode=block" always;
-}

frontend/package.json

@@ -1,38 +0,0 @@
-{
-  "name": "cftunnels-frontend",
-  "version": "1.0.0",
-  "scripts": {
-    "ng": "ng",
-    "start": "ng serve",
-    "build": "ng build",
-    "watch": "ng build --watch --configuration development",
-    "test": "ng test"
-  },
-  "private": true,
-  "dependencies": {
-    "@angular/animations": "^17.3.0",
-    "@angular/cdk": "^17.3.0",
-    "@angular/common": "^17.3.0",
-    "@angular/compiler": "^17.3.0",
-    "@angular/core": "^17.3.0",
-    "@angular/forms": "^17.3.0",
-    "@angular/material": "^17.3.0",
-    "@angular/platform-browser": "^17.3.0",
-    "@angular/platform-browser-dynamic": "^17.3.0",
-    "@angular/router": "^17.3.0",
-    "angular-oauth2-oidc": "^17.0.0",
-    "rxjs": "~7.8.0",
-    "tslib": "^2.6.0",
-    "zone.js": "~0.14.0"
-  },
-  "devDependencies": {
-    "@angular-devkit/build-angular": "^17.3.0",
-    "@angular/cli": "^17.3.0",
-    "@angular/compiler-cli": "^17.3.0",
-    "@types/node": "^20.0.0",
-    "autoprefixer": "^10.4.0",
-    "postcss": "^8.4.0",
-    "tailwindcss": "^3.4.0",
-    "typescript": "~5.4.0"
-  }
-}

frontend/postcss.config.js

@@ -1,6 +0,0 @@
-module.exports = {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-}

frontend/src/app/app.component.ts

@@ -1,10 +0,0 @@
-import { Component } from '@angular/core';
-import { RouterOutlet } from '@angular/router';
-
-@Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [RouterOutlet],
-  template: `<router-outlet></router-outlet>`,
-})
-export class AppComponent {}

frontend/src/app/app.config.ts

@@ -1,28 +0,0 @@
-import { ApplicationConfig, importProvidersFrom } from '@angular/core';
-import { provideRouter } from '@angular/router';
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { provideAnimations } from '@angular/platform-browser/animations';
-import { OAuthModule } from 'angular-oauth2-oidc';
-
-import { routes } from './app/app.routes';
-import { authInterceptor } from './app/core/auth/auth.interceptor';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideRouter(routes),
-    provideHttpClient(withInterceptors([authInterceptor])),
-    provideAnimations(),
-    importProvidersFrom(
-      OAuthModule.forRoot({
-        config: {
-          issuer: 'https://auth.hithomelabs.com/application/o/cftunnels/',
-          redirectUri: window.location.origin + '/login',
-          clientId: 'cftunnels',
-          scope: 'openid profile email offline_access',
-          responseType: 'code',
-          showDebugInformation: true,
-        },
-      })
-    ),
-  ],
-};

frontend/src/app/app.routes.ts

@@ -1,24 +0,0 @@
-import { Routes } from '@angular/router';
-import { authGuard } from './core/auth/auth.guard';
-import { loginGuard } from './core/auth/login.guard';
-
-export const routes: Routes = [
-  {
-    path: '',
-    canActivate: [authGuard],
-    loadComponent: () =>
-      import('./features/dashboard/dashboard.component').then(
-        (m) => m.DashboardComponent
-      ),
-  },
-  {
-    path: 'login',
-    canActivate: [loginGuard],
-    loadComponent: () =>
-      import('./features/login/login.component').then((m) => m.LoginComponent),
-  },
-  {
-    path: '**',
-    redirectTo: '',
-  },
-];

frontend/src/app/core/auth/auth.guard.ts

@@ -1,17 +0,0 @@
-import { inject } from '@angular/core';
-import { Router, CanActivateFn } from '@angular/router';
-import { AuthService } from './auth.service';
-
-export const authGuard: CanActivateFn = (route, state) => {
-  const authService = inject(AuthService);
-  const router = inject(Router);
-
-  if (authService['oauthService'].isAuthenticated()) {
-    return true;
-  }
-
-  router.navigate(['/login'], {
-    queryParams: { returnUrl: state.url },
-  });
-  return false;
-};

frontend/src/app/core/auth/auth.interceptor.ts

@@ -1,30 +0,0 @@
-import { HttpInterceptorFn, HttpErrorResponse } from '@angular/common/http';
-import { inject } from '@angular/core';
-import { Router } from '@angular/router';
-import { catchError, throwError } from 'rxjs';
-import { AuthService } from './auth.service';
-
-export const authInterceptor: HttpInterceptorFn = (req, next) => {
-  const authService = inject(AuthService);
-  const router = inject(Router);
-
-  const token = authService.getAccessToken();
-
-  if (token && req.url.includes('/cloudflare/')) {
-    req = req.clone({
-      setHeaders: {
-        Authorization: `Bearer ${token}`,
-      },
-    });
-  }
-
-  return next(req).pipe(
-    catchError((error: HttpErrorResponse) => {
-      if (error.status === 401) {
-        authService.logout();
-        router.navigate(['/login']);
-      }
-      return throwError(() => error);
-    })
-  );
-};

frontend/src/app/core/auth/auth.service.ts

@@ -1,99 +0,0 @@
-import { Injectable, signal } from '@angular/core';
-import { Router } from '@angular/router';
-import {
-  OAuthService,
-  AuthConfig,
-} from 'angular-oauth2-oidc';
-import { BehaviorSubject, Observable } from 'rxjs';
-import { User } from '../shared/models';
-
-@Injectable({
-  providedIn: 'root',
-})
-export class AuthService {
-  private userSubject = new BehaviorSubject<User | null>(null);
-  public user$ = this.userSubject.asObservable();
-
-  private isAuthenticatedSubject = new BehaviorSubject<boolean>(false);
-  public isAuthenticated$ = this.isAuthenticatedSubject.asObservable();
-
-  constructor(
-    private oauthService: OAuthService,
-    private router: Router
-  ) {}
-
-  configure(): void {
-    const authCodeFlowConfig: AuthConfig = {
-      issuer: 'https://auth.hithomelabs.com/application/o/cftunnels/',
-      redirectUri: window.location.origin + '/login',
-      clientId: 'cftunnels',
-      scope: 'openid profile email offline_access',
-      responseType: 'code',
-      showDebugInformation: true,
-      strictDiscoveryDocumentValidation: false,
-      useSilentRefresh: true,
-    };
-
-    this.oauthService.configure(authCodeFlowConfig);
-    this.oauthService.loadDiscoveryDocumentAndTryLogin();
-  }
-
-  async login(): Promise<void> {
-    await this.oauthService.loadDiscoveryDocument();
-    await this.oauthService.initCodeFlow();
-  }
-
-  async handleLoginCallback(): Promise<void> {
-    await this.oauthService.loadDiscoveryDocumentAndTryLogin();
-    if (this.oauthService.isAuthenticated()) {
-      await this.fetchUserInfo();
-      this.isAuthenticatedSubject.next(true);
-    }
-  }
-
-  private async fetchUserInfo(): Promise<void> {
-    try {
-      const claims = await this.oauthService.loadUserProfile();
-      const userInfo = claims as unknown as {
-        info: { email: string; name: string };
-        groups: string[];
-      };
-
-      const user: User = {
-        username: userInfo.info?.name || userInfo.info?.email || 'Unknown',
-        roles: userInfo.groups || [],
-      };
-
-      this.userSubject.next(user);
-    } catch (error) {
-      console.error('Error fetching user info:', error);
-    }
-  }
-
-  logout(): void {
-    this.oauthService.logOut();
-    this.userSubject.next(null);
-    this.isAuthenticatedSubject.next(false);
-    this.router.navigate(['/login']);
-  }
-
-  getAccessToken(): string | null {
-    return this.oauthService.getAccessToken();
-  }
-
-  hasRole(role: string): boolean {
-    const user = this.userSubject.getValue();
-    if (!user) return false;
-    return user.roles.some(
-      (r) => r === role || r === `ROLE_${role}` || r === `ROLE_${role.toUpperCase()}`
-    );
-  }
-
-  hasAnyRole(roles: string[]): boolean {
-    return roles.some((role) => this.hasRole(role));
-  }
-
-  getUser(): User | null {
-    return this.userSubject.getValue();
-  }
-}

frontend/src/app/core/auth/login.guard.ts

@@ -1,15 +0,0 @@
-import { inject } from '@angular/core';
-import { Router, CanActivateFn } from '@angular/router';
-import { AuthService } from './auth.service';
-
-export const loginGuard: CanActivateFn = (route, state) => {
-  const authService = inject(AuthService);
-  const router = inject(Router);
-
-  if (authService['oauthService'].isAuthenticated()) {
-    router.navigate(['/']);
-    return false;
-  }
-
-  return true;
-};

frontend/src/app/core/services/api.service.ts

@@ -1,63 +0,0 @@
-import { Injectable } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { Observable } from 'rxjs';
-import {
-  ApiResponse,
-  User,
-  Request,
-  Tunnel,
-  Mapping,
-} from '../../shared/models';
-
-@Injectable({
-  providedIn: 'root',
-})
-export class ApiService {
-  private baseUrl = '/cloudflare';
-
-  constructor(private http: HttpClient) {}
-
-  whoami(): Observable<ApiResponse<User>> {
-    return this.http.get<ApiResponse<User>>(`${this.baseUrl}/whoami`);
-  }
-
-  getRequests(): Observable<ApiResponse<Request[]>> {
-    return this.http.get<ApiResponse<Request[]>>(`${this.baseUrl}/requests`);
-  }
-
-  approveRequest(requestId: string): Observable<Request> {
-    return this.http.put<Request>(
-      `${this.baseUrl}/requests/${requestId}/approve`,
-      {}
-    );
-  }
-
-  rejectRequest(requestId: string): Observable<Request> {
-    return this.http.put<Request>(
-      `${this.baseUrl}/requests/${requestId}/reject`,
-      {}
-    );
-  }
-
-  getConfiguredTunnels(): Observable<ApiResponse<Tunnel[]>> {
-    return this.http.get<ApiResponse<Tunnel[]>>(
-      `${this.baseUrl}/configured/tunnels`
-    );
-  }
-
-  getTunnelMappings(tunnelId: string): Observable<ApiResponse<Mapping[]>> {
-    return this.http.get<ApiResponse<Mapping[]>>(
-      `${this.baseUrl}/tunnels/${tunnelId}/mappings`
-    );
-  }
-
-  createMappingRequest(
-    tunnelId: string,
-    mapping: { subdomain: string; protocol: string; port: number }
-  ): Observable<Request> {
-    return this.http.post<Request>(
-      `${this.baseUrl}/tunnels/${tunnelId}/requests`,
-      mapping
-    );
-  }
-}

frontend/src/app/features/dashboard/create-mapping/create-mapping.component.ts

@@ -1,220 +0,0 @@
-import { Component, OnInit } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { FormBuilder, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
-import { MatCardModule } from '@angular/material/card';
-import { MatFormFieldModule } from '@angular/material/form-field';
-import { MatInputModule } from '@angular/material/input';
-import { MatSelectModule } from '@angular/material/select';
-import { MatButtonModule } from '@angular/material/button';
-import { MatIconModule } from '@angular/material/icon';
-import { MatSnackBar, MatSnackBarModule } from '@angular/material/snack-bar';
-import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
-import { Tunnel } from '../../../shared/models';
-import { ApiService } from '../../../core/services/api.service';
-
-@Component({
-  selector: 'app-create-mapping',
-  standalone: true,
-  imports: [
-    CommonModule,
-    ReactiveFormsModule,
-    MatCardModule,
-    MatFormFieldModule,
-    MatInputModule,
-    MatSelectModule,
-    MatButtonModule,
-    MatIconModule,
-    MatSnackBarModule,
-    MatProgressSpinnerModule,
-  ],
-  template: `
-    <mat-card class="create-card">
-      <mat-card-header>
-        <mat-icon mat-card-avatar>add_circle</mat-icon>
-        <mat-card-title>Create New Mapping Request</mat-card-title>
-        <mat-card-subtitle>Request a new subdomain mapping</mat-card-subtitle>
-      </mat-card-header>
-
-      <mat-card-content>
-        <form [formGroup]="mappingForm" (ngSubmit)="onSubmit()">
-          <div class="form-row">
-            <mat-form-field appearance="outline">
-              <mat-label>Subdomain</mat-label>
-              <input
-                matInput
-                formControlName="subdomain"
-                placeholder="myapp"
-              />
-              <span matSuffix>.hithomelabs.com</span>
-              @if (mappingForm.get('subdomain')?.hasError('required')) {
-                <mat-error>Subdomain is required</mat-error>
-              }
-            </mat-form-field>
-          </div>
-
-          <div class="form-row">
-            <mat-form-field appearance="outline">
-              <mat-label>Tunnel</mat-label>
-              <mat-select formControlName="tunnelId">
-                @for (tunnel of tunnels; track tunnel.id) {
-                  <mat-option [value]="tunnel.id">
-                    {{ tunnel.name }} ({{ tunnel.environment }})
-                  </mat-option>
-                }
-              </mat-select>
-              @if (mappingForm.get('tunnelId')?.hasError('required')) {
-                <mat-error>Tunnel is required</mat-error>
-              }
-            </mat-form-field>
-          </div>
-
-          <div class="form-row two-columns">
-            <mat-form-field appearance="outline">
-              <mat-label>Protocol</mat-label>
-              <mat-select formControlName="protocol">
-                <mat-option value="http">HTTP</mat-option>
-                <mat-option value="https">HTTPS</mat-option>
-                <mat-option value="ssh">SSH</mat-option>
-                <mat-option value="tcp">TCP</mat-option>
-              </mat-select>
-            </mat-form-field>
-
-            <mat-form-field appearance="outline">
-              <mat-label>Port</mat-label>
-              <input
-                matInput
-                type="number"
-                formControlName="port"
-                placeholder="8080"
-              />
-              @if (mappingForm.get('port')?.hasError('required')) {
-                <mat-error>Port is required</mat-error>
-              }
-              @if (mappingForm.get('port')?.hasError('min')) {
-                <mat-error>Port must be greater than 0</mat-error>
-              }
-              @if (mappingForm.get('port')?.hasError('max')) {
-                <mat-error>Port must be less than 65535</mat-error>
-              }
-            </mat-form-field>
-          </div>
-
-          <div class="form-actions">
-            <button
-              mat-raised-button
-              color="primary"
-              type="submit"
-              [disabled]="mappingForm.invalid || isSubmitting"
-            >
-              @if (isSubmitting) {
-                <mat-spinner diameter="20"></mat-spinner>
-              } @else {
-                <mat-icon>send</mat-icon>
-              }
-              Submit Request
-            </button>
-          </div>
-        </form>
-      </mat-card-content>
-    </mat-card>
-  `,
-  styles: [
-    `
-      .create-card {
-        margin-bottom: 1.5rem;
-      }
-
-      .form-row {
-        margin-bottom: 1rem;
-      }
-
-      .two-columns {
-        display: grid;
-        grid-template-columns: 1fr 1fr;
-        gap: 1rem;
-      }
-
-      mat-form-field {
-        width: 100%;
-      }
-
-      .form-actions {
-        display: flex;
-        justify-content: flex-end;
-        margin-top: 1.5rem;
-      }
-
-      button[mat-raised-button] {
-        min-width: 150px;
-      }
-
-      button mat-spinner {
-        display: inline-block;
-      }
-    `,
-  ],
-})
-export class CreateMappingComponent implements OnInit {
-  mappingForm: FormGroup;
-  tunnels: Tunnel[] = [];
-  isSubmitting = false;
-
-  constructor(
-    private fb: FormBuilder,
-    private apiService: ApiService,
-    private snackBar: MatSnackBar
-  ) {
-    this.mappingForm = this.fb.group({
-      subdomain: ['', [Validators.required, Validators.pattern(/^[a-z0-9-]+$/)]],
-      tunnelId: ['', Validators.required],
-      protocol: ['http', Validators.required],
-      port: ['', [Validators.required, Validators.min(1), Validators.max(65535)]],
-    });
-  }
-
-  ngOnInit(): void {
-    this.loadTunnels();
-  }
-
-  loadTunnels(): void {
-    this.apiService.getConfiguredTunnels().subscribe({
-      next: (response) => {
-        this.tunnels = response.data;
-      },
-      error: (err) => {
-        console.error('Error loading tunnels:', err);
-        this.snackBar.open('Failed to load tunnels', 'Close', {
-          duration: 3000,
-        });
-      },
-    });
-  }
-
-  onSubmit(): void {
-    if (this.mappingForm.invalid) return;
-
-    this.isSubmitting = true;
-    const { subdomain, tunnelId, protocol, port } = this.mappingForm.value;
-
-    this.apiService.createMappingRequest(tunnelId, {
-      subdomain,
-      protocol,
-      port,
-    }).subscribe({
-      next: () => {
-        this.snackBar.open('Mapping request submitted successfully!', 'Close', {
-          duration: 3000,
-        });
-        this.mappingForm.reset({ protocol: 'http' });
-        this.isSubmitting = false;
-      },
-      error: (err) => {
-        console.error('Error creating mapping request:', err);
-        this.snackBar.open('Failed to submit mapping request', 'Close', {
-          duration: 3000,
-        });
-        this.isSubmitting = false;
-      },
-    });
-  }
-}

frontend/src/app/features/dashboard/dashboard.component.ts

@@ -1,167 +0,0 @@
-import { Component, OnInit } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { MatToolbarModule } from '@angular/material/toolbar';
-import { MatButtonModule } from '@angular/material/button';
-import { MatIconModule } from '@angular/material/icon';
-import { MatSidenavModule } from '@angular/material/sidenav';
-import { MatListModule } from '@angular/material/list';
-import { MatCardModule } from '@angular/material/card';
-import { AuthService } from '../../core/auth/auth.service';
-import { ApiService } from '../../core/services/api.service';
-import { User, Request, Tunnel } from '../../shared/models';
-import { PendingRequestsComponent } from './pending-requests/pending-requests.component';
-import { TunnelListComponent } from './tunnel-list/tunnel-list.component';
-import { CreateMappingComponent } from './create-mapping/create-mapping.component';
-
-@Component({
-  selector: 'app-dashboard',
-  standalone: true,
-  imports: [
-    CommonModule,
-    MatToolbarModule,
-    MatButtonModule,
-    MatIconModule,
-    MatSidenavModule,
-    MatListModule,
-    MatCardModule,
-    PendingRequestsComponent,
-    TunnelListComponent,
-    CreateMappingComponent,
-  ],
-  template: `
-    <mat-toolbar color="primary" class="toolbar">
-      <span class="title">
-        <mat-icon>hub</mat-icon>
-        CFTunnels
-      </span>
-      <span class="spacer"></span>
-      <span class="user-info" *ngIf="user">
-        {{ user.username }}
-        <span class="roles">({{ user.roles.join(', ') }})</span>
-      </span>
-      <button mat-icon-button (click)="logout()" title="Logout">
-        <mat-icon>logout</mat-icon>
-      </button>
-    </mat-toolbar>
-
-    <div class="dashboard-container">
-      <div class="dashboard-content">
-        <!-- Pending Requests Section - APPROVER/ADMIN only -->
-        @if (canApprove()) {
-          <app-pending-requests
-            [requests]="pendingRequests"
-            (requestUpdated)="loadRequests()"
-          ></app-pending-requests>
-        }
-
-        <!-- Tunnel List Section - DEVELOPER+ -->
-        @if (canViewTunnels()) {
-          <app-tunnel-list [tunnels]="tunnels"></app-tunnel-list>
-        }
-
-        <!-- Create Mapping Section - USER+ -->
-        <app-create-mapping></app-create-mapping>
-      </div>
-    </div>
-  `,
-  styles: [
-    `
-      .toolbar {
-        position: sticky;
-        top: 0;
-        z-index: 1000;
-      }
-
-      .title {
-        display: flex;
-        align-items: center;
-        gap: 0.5rem;
-        font-weight: 500;
-      }
-
-      .spacer {
-        flex: 1 1 auto;
-      }
-
-      .user-info {
-        display: flex;
-        align-items: center;
-        gap: 0.5rem;
-        margin-right: 1rem;
-        font-size: 0.9rem;
-      }
-
-      .roles {
-        color: rgba(255, 255, 255, 0.7);
-        font-size: 0.8rem;
-      }
-
-      .dashboard-container {
-        display: flex;
-        justify-content: center;
-        padding: 1.5rem;
-      }
-
-      .dashboard-content {
-        width: 100%;
-        max-width: 900px;
-      }
-    `,
-  ],
-})
-export class DashboardComponent implements OnInit {
-  user: User | null = null;
-  pendingRequests: Request[] = [];
-  tunnels: Tunnel[] = [];
-
-  constructor(
-    private authService: AuthService,
-    private apiService: ApiService
-  ) {}
-
-  ngOnInit(): void {
-    this.authService.user$.subscribe((user) => {
-      this.user = user;
-      if (user) {
-        this.loadData();
-      }
-    });
-  }
-
-  loadData(): void {
-    this.loadRequests();
-    this.loadTunnels();
-  }
-
-  loadRequests(): void {
-    this.apiService.getRequests().subscribe({
-      next: (response) => {
-        this.pendingRequests = response.data.filter(
-          (r) => r.status === 'PENDING'
-        );
-      },
-      error: (err) => console.error('Error loading requests:', err),
-    });
-  }
-
-  loadTunnels(): void {
-    this.apiService.getConfiguredTunnels().subscribe({
-      next: (response) => {
-        this.tunnels = response.data;
-      },
-      error: (err) => console.error('Error loading tunnels:', err),
-    });
-  }
-
-  canApprove(): boolean {
-    return this.authService.hasAnyRole(['APPROVER', 'ADMIN']);
-  }
-
-  canViewTunnels(): boolean {
-    return this.authService.hasAnyRole(['DEVELOPER', 'APPROVER', 'ADMIN']);
-  }
-
-  logout(): void {
-    this.authService.logout();
-  }
-}

frontend/src/app/features/dashboard/pending-requests/pending-requests.component.ts

@@ -1,174 +0,0 @@
-import { Component, Input, Output, EventEmitter, OnInit } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { MatCardModule } from '@angular/material/card';
-import { MatButtonModule } from '@angular/material/button';
-import { MatIconModule } from '@angular/material/icon';
-import { MatChipsModule } from '@angular/material/chips';
-import { MatProgressBarModule } from '@angular/material/progress-bar';
-import { Request } from '../../../shared/models';
-import { ApiService } from '../../../core/services/api.service';
-
-@Component({
-  selector: 'app-pending-requests',
-  standalone: true,
-  imports: [
-    CommonModule,
-    MatCardModule,
-    MatButtonModule,
-    MatIconModule,
-    MatChipsModule,
-    MatProgressBarModule,
-  ],
-  template: `
-    <mat-card class="requests-card">
-      <mat-card-header>
-        <mat-icon mat-card-avatar>pending_actions</mat-icon>
-        <mat-card-title>Pending Requests</mat-card-title>
-        <mat-card-subtitle
-          >{{ requests.length }} request(s) awaiting approval</mat-card-subtitle
-        >
-      </mat-card-header>
-
-      <mat-card-content>
-        @if (isLoading) {
-          <mat-progress-bar mode="indeterminate"></mat-progress-bar>
-        }
-
-        @if (!isLoading && requests.length === 0) {
-          <div class="empty-state">
-            <mat-icon>check_circle</mat-icon>
-            <p>No pending requests</p>
-          </div>
-        }
-
-        @for (request of requests; track request.id) {
-          <div class="request-item">
-            <div class="request-info">
-              <span class="subdomain">{{ request.mapping.subdomain }}.hithomelabs.com</span>
-              <span class="tunnel">→ {{ request.mapping.tunnel.name }}</span>
-              <span class="port">Port: {{ request.mapping.port }}</span>
-            </div>
-            <div class="request-actions">
-              <button
-                mat-mini-fab
-                color="primary"
-                (click)="approve(request.id)"
-                [disabled]="actionInProgress"
-                title="Approve"
-              >
-                <mat-icon>check</mat-icon>
-              </button>
-              <button
-                mat-mini-fab
-                color="warn"
-                (click)="reject(request.id)"
-                [disabled]="actionInProgress"
-                title="Reject"
-              >
-                <mat-icon>close</mat-icon>
-              </button>
-            </div>
-          </div>
-        }
-      </mat-card-content>
-    </mat-card>
-  `,
-  styles: [
-    `
-      .requests-card {
-        margin-bottom: 1.5rem;
-      }
-
-      .empty-state {
-        display: flex;
-        flex-direction: column;
-        align-items: center;
-        padding: 2rem;
-        color: #4caf50;
-      }
-
-      .empty-state mat-icon {
-        font-size: 48px;
-        width: 48px;
-        height: 48px;
-      }
-
-      .request-item {
-        display: flex;
-        justify-content: space-between;
-        align-items: center;
-        padding: 1rem;
-        border-bottom: 1px solid #eee;
-      }
-
-      .request-item:last-child {
-        border-bottom: none;
-      }
-
-      .request-info {
-        display: flex;
-        flex-direction: column;
-        gap: 0.25rem;
-      }
-
-      .subdomain {
-        font-weight: 500;
-        color: #1976d2;
-      }
-
-      .tunnel {
-        color: #666;
-        font-size: 0.9rem;
-      }
-
-      .port {
-        color: #999;
-        font-size: 0.85rem;
-      }
-
-      .request-actions {
-        display: flex;
-        gap: 0.5rem;
-      }
-    `,
-  ],
-})
-export class PendingRequestsComponent implements OnInit {
-  @Input() requests: Request[] = [];
-  @Output() requestUpdated = new EventEmitter<void>();
-
-  isLoading = false;
-  actionInProgress = false;
-
-  constructor(private apiService: ApiService) {}
-
-  ngOnInit(): void {}
-
-  approve(requestId: string): void {
-    this.actionInProgress = true;
-    this.apiService.approveRequest(requestId).subscribe({
-      next: () => {
-        this.requestUpdated.emit();
-        this.actionInProgress = false;
-      },
-      error: (err) => {
-        console.error('Error approving request:', err);
-        this.actionInProgress = false;
-      },
-    });
-  }
-
-  reject(requestId: string): void {
-    this.actionInProgress = true;
-    this.apiService.rejectRequest(requestId).subscribe({
-      next: () => {
-        this.requestUpdated.emit();
-        this.actionInProgress = false;
-      },
-      error: (err) => {
-        console.error('Error rejecting request:', err);
-        this.actionInProgress = false;
-      },
-    });
-  }
-}

frontend/src/app/features/dashboard/tunnel-list/tunnel-list.component.ts

@@ -1,182 +0,0 @@
-import { Component, Input, OnInit } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { MatCardModule } from '@angular/material/card';
-import { MatButtonModule } from '@angular/material/button';
-import { MatIconModule } from '@angular/material/icon';
-import { MatExpansionModule } from '@angular/material/expansion';
-import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
-import { Tunnel, Mapping } from '../../../shared/models';
-import { ApiService } from '../../../core/services/api.service';
-
-@Component({
-  selector: 'app-tunnel-list',
-  standalone: true,
-  imports: [
-    CommonModule,
-    MatCardModule,
-    MatButtonModule,
-    MatIconModule,
-    MatExpansionModule,
-    MatProgressSpinnerModule,
-  ],
-  template: `
-    <mat-card class="tunnels-card">
-      <mat-card-header>
-        <mat-icon mat-card-avatar>dns</mat-icon>
-        <mat-card-title>Tunnels</mat-card-title>
-        <mat-card-subtitle
-          >{{ tunnels.length }} tunnel(s) configured</mat-card-subtitle
-        >
-      </mat-card-header>
-
-      <mat-card-content>
-        @if (isLoading) {
-          <div class="loading-container">
-            <mat-spinner diameter="30"></mat-spinner>
-          </div>
-        }
-
-        @if (!isLoading && tunnels.length === 0) {
-          <div class="empty-state">
-            <mat-icon>info</mat-icon>
-            <p>No tunnels configured</p>
-          </div>
-        }
-
-        <mat-accordion>
-          @for (tunnel of tunnels; track tunnel.id) {
-            <mat-expansion-panel>
-              <mat-expansion-panel-header>
-                <mat-panel-title>
-                  <mat-icon class="tunnel-icon">hub</mat-icon>
-                  {{ tunnel.name }}
-                </mat-panel-title>
-                <mat-panel-description>
-                  {{ tunnel.environment }}
-                </mat-panel-description>
-              </mat-expansion-panel-header>
-
-              @if (expandedTunnelId === tunnel.id) {
-                @if (mappingsLoading) {
-                  <mat-spinner diameter="20"></mat-spinner>
-                } @else if (tunnelMappings[tunnel.id]?.length === 0) {
-                  <p class="no-mappings">No mappings for this tunnel</p>
-                } @else {
-                  @for (mapping of tunnelMappings[tunnel.id]; track mapping.id) {
-                    <div class="mapping-item">
-                      <span class="hostname"
-                        >{{ mapping.subdomain }}.hithomelabs.com</span
-                      >
-                      <span class="service"
-                        >→ {{ mapping.protocol }}://192.168.0.100:{{
-                          mapping.port
-                        }}</span
-                      >
-                    </div>
-                  }
-                }
-              } @else {
-                <button
-                  mat-button
-                  color="primary"
-                  (click)="loadMappings(tunnel.id)"
-                >
-                  <mat-icon>visibility</mat-icon>
-                  View Mappings
-                </button>
-              }
-            </mat-expansion-panel>
-          }
-        </mat-accordion>
-      </mat-card-content>
-    </mat-card>
-  `,
-  styles: [
-    `
-      .tunnels-card {
-        margin-bottom: 1.5rem;
-      }
-
-      .loading-container {
-        display: flex;
-        justify-content: center;
-        padding: 2rem;
-      }
-
-      .empty-state {
-        display: flex;
-        flex-direction: column;
-        align-items: center;
-        padding: 2rem;
-        color: #666;
-      }
-
-      .empty-state mat-icon {
-        font-size: 48px;
-        width: 48px;
-        height: 48px;
-      }
-
-      .tunnel-icon {
-        margin-right: 0.5rem;
-      }
-
-      .mapping-item {
-        display: flex;
-        flex-direction: column;
-        padding: 0.75rem;
-        margin: 0.5rem 0;
-        background: #f5f5f5;
-        border-radius: 4px;
-      }
-
-      .hostname {
-        font-weight: 500;
-        color: #1976d2;
-      }
-
-      .service {
-        color: #666;
-        font-size: 0.9rem;
-      }
-
-      .no-mappings {
-        color: #999;
-        font-style: italic;
-      }
-
-      mat-panel-title {
-        display: flex;
-        align-items: center;
-      }
-    `,
-  ],
-})
-export class TunnelListComponent implements OnInit {
-  @Input() tunnels: Tunnel[] = [];
-
-  isLoading = false;
-  mappingsLoading = false;
-  expandedTunnelId: string | null = null;
-  tunnelMappings: { [key: string]: Mapping[] } = {};
-
-  constructor(private apiService: ApiService) {}
-
-  ngOnInit(): void {}
-
-  loadMappings(tunnelId: string): void {
-    this.expandedTunnelId = tunnelId;
-    this.mappingsLoading = true;
-
-    this.apiService.getTunnelMappings(tunnelId).subscribe({
-      next: (response) => {
-        this.tunnelMappings[tunnelId] = response.data;
-        this.mappingsLoading = false;
-      },
-      error: (err) => {
-        console.error('Error loading mappings:', err);
-        this.mappingsLoading = false;
-      },
-    });
-  }
-}

frontend/src/app/features/login/login.component.ts

@@ -1,127 +0,0 @@
-import { Component, OnInit } from '@angular/core';
-import { CommonModule } from '@angular/common';
-import { Router } from '@angular/router';
-import { MatButtonModule } from '@angular/material/button';
-import { MatCardModule } from '@angular/material/card';
-import { MatIconModule } from '@angular/material/icon';
-import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
-import { AuthService } from '../../core/auth/auth.service';
-
-@Component({
-  selector: 'app-login',
-  standalone: true,
-  imports: [
-    CommonModule,
-    MatButtonModule,
-    MatCardModule,
-    MatIconModule,
-    MatProgressSpinnerModule,
-  ],
-  template: `
-    <div class="login-container">
-      <mat-card class="login-card">
-        <mat-card-header>
-          <mat-card-title>
-            <mat-icon class="logo-icon">hub</mat-icon>
-            CFTunnels
-          </mat-card-title>
-          <mat-card-subtitle>Cloudflare Tunnel Management</mat-card-subtitle>
-        </mat-card-header>
-
-        <mat-card-content>
-          <p>Sign in to manage your Cloudflare Tunnels and mappings.</p>
-
-          @if (isLoading) {
-            <div class="spinner-container">
-              <mat-spinner diameter="40"></mat-spinner>
-            </div>
-          } @else {
-            <button
-              mat-raised-button
-              color="primary"
-              class="login-button"
-              (click)="login()"
-            >
-              <mat-icon>login</mat-icon>
-              Login with Authentik
-            </button>
-          }
-        </mat-card-content>
-      </mat-card>
-    </div>
-  `,
-  styles: [
-    `
-      .login-container {
-        display: flex;
-        justify-content: center;
-        align-items: center;
-        min-height: 100vh;
-        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-      }
-
-      .login-card {
-        width: 400px;
-        padding: 2rem;
-        text-align: center;
-      }
-
-      .logo-icon {
-        font-size: 48px;
-        width: 48px;
-        height: 48px;
-        margin-bottom: 1rem;
-        color: #667eea;
-      }
-
-      mat-card-title {
-        font-size: 2rem;
-        margin-bottom: 0.5rem;
-      }
-
-      mat-card-subtitle {
-        margin-bottom: 2rem;
-      }
-
-      p {
-        color: #666;
-        margin-bottom: 2rem;
-      }
-
-      .login-button {
-        width: 100%;
-        padding: 1rem;
-        font-size: 1.1rem;
-      }
-
-      .spinner-container {
-        display: flex;
-        justify-content: center;
-        margin-top: 2rem;
-      }
-    `,
-  ],
-})
-export class LoginComponent implements OnInit {
-  isLoading = false;
-
-  constructor(
-    private authService: AuthService,
-    private router: Router
-  ) {}
-
-  ngOnInit(): void {
-    const urlParams = new URLSearchParams(window.location.search);
-    if (urlParams.has('code') || urlParams.has('state')) {
-      this.isLoading = true;
-      this.authService.handleLoginCallback().then(() => {
-        this.router.navigate(['/']);
-      });
-    }
-  }
-
-  async login(): Promise<void> {
-    this.isLoading = true;
-    await this.authService.login();
-  }
-}

frontend/src/app/shared/models/index.ts

@@ -1,35 +0,0 @@
-export interface User {
-  username: string;
-  roles: string[];
-}
-
-export interface Tunnel {
-  id: string;
-  name: string;
-  environment: string;
-}
-
-export interface Mapping {
-  id: string;
-  subdomain: string;
-  protocol: string;
-  port: number;
-  tunnel: Tunnel;
-}
-
-export interface Request {
-  id: string;
-  mapping: Mapping;
-  createdBy: User;
-  acceptedBy?: User;
-  status: 'PENDING' | 'APPROVED' | 'REJECTED';
-}
-
-export interface ApiResponse<T> {
-  status: string;
-  data: T;
-}
-
-export interface TunnelWithMappings extends Tunnel {
-  mappings?: Mapping[];
-}

frontend/src/environments/environment.local.ts

@@ -1,7 +0,0 @@
-export const environment = {
-  production: false,
-  apiUrl: '/cloudflare',
-  issuer: 'https://auth.hithomelabs.com/application/o/cftunnels/',
-  oauthClientId: 'cftunnels',
-  redirectUri: 'http://localhost:80/login'
-};

frontend/src/environments/environment.prod.ts

@@ -1,7 +0,0 @@
-export const environment = {
-  production: true,
-  apiUrl: '/cloudflare',
-  issuer: 'https://auth.hithomelabs.com/application/o/cftunnels/',
-  oauthClientId: 'cftunnels',
-  redirectUri: 'https://cftunnels.hithomelabs.com/login'
-};