Jump-Start your Cumulocity Microservice Project in Java - 2026 Edition

Knowledge Base
, , , , ,
1

Introduction

Four years ago, I introduced the cumulocity-microservice-archetype - a Maven archetype that helps developers quickly scaffold Cumulocity microservice projects. Since then, I’ve gathered feedback from the community and significantly enhanced the archetype with modern development practices, improved IDE integration, and automated setup workflows.

This updated archetype now delivers a production-ready microservice template in under 5 minutes, complete with automated credential management, pre-configured IDE launch configurations for both VS Code and IntelliJ IDEA, and industry best practices baked in from the start, including GitHub Actions and Copilot custom agents.

In this article, I’ll walk you through the revamped archetype and highlight the game-changing improvements that make microservice development faster, smoother, and more enjoyable.

What’s New? Major Improvements at a Glance

:rocket: Automated Initialization Scripts

The biggest improvement is the addition of automated initializer scripts that handle the entire microservice bootstrap process for your local development environment. Two scripts are included in the generated project:

  • initializr.ps1 (Windows/PowerShell)
  • initializr.sh (Linux/macOS/Bash)

These scripts automatically:

  • :white_check_mark: Create the microservice in your Cumulocity tenant
  • :white_check_mark: Subscribe your tenant to the microservice
  • :white_check_mark: Retrieve bootstrap credentials
  • :white_check_mark: Store environment variables in .env/dev.env for local development
  • :white_check_mark: Use your existing sessions from go-c8y-cli

No more manual credential hunting! The days of copying Base64-encoded credentials from browser Developer Tools are over. You can now directly use your go-c8y-cli sessions. The scripts are independent of the project build process and can be re-run anytime you need to refresh credentials.

The .env/dev.env file generated by the initializer scripts contains the microservice bootstrap credential and tenant configuration:

C8Y_BASEURL=https://your-tenant.cumulocity.com
C8Y_BOOTSTRAP_TENANT=t12345
C8Y_BOOTSTRAP_USER=servicebootstrap_microservice-name
C8Y_BOOTSTRAP_PASSWORD=********
C8Y_MICROSERVICE_ISOLATION=MULTI_TENANT

:hammer_and_wrench: Full IDE Integration

The archetype now includes pre-configured launch configurations for the two most popular Java IDEs:

VS Code Integration

  • .vscode/launch.json with Spring Boot run configuration
  • Automatic environment variable loading from .env/dev.env
  • Pre-configured VM arguments for Logback logging

IntelliJ IDEA Integration

  • .idea/runConfigurations/Spring_Boot-App.xml ready to use
  • EnvFile plugin support for automatic .env/dev.env loading
  • No manual run configuration needed - just open and run!

Both configurations point to the same .env/dev.env file, ensuring consistency across IDEs and team members.

:counterclockwise_arrows_button: GitHub Actions

The archetype now includes two sample GitHub Actions workflows for CI/CD. These workflows automate building, testing, and deploying your microservice to a Cumulocity tenant whenever you push changes to the main and develop branches or create a new pull request.

The workflow .github/workflows/maven_build_deploy.yml includes steps for packaging three different deployment sizes (Small, Medium, Large) and deploying them to your tenant using go-c8y-cli. It is best practice to provide different packages for different environments: small means fewer CPU and memory resources are requested and is suited for development tenants, while large is suited for production tenants. However, the appropriate version depends highly on your microservice implementation and the environment where it is deployed.

:robot: Copilot Custom Agents (Experimental)

The archetype now includes Copilot custom agents, enabling AI-assisted development. The custom agent contains best practices, URLs, and specific knowledge about Cumulocity microservices.

This allows you to use GitHub Copilot more effectively within your microservice project context, accelerating development while maintaining code quality standards.

:file_folder: Enhanced Project Structure

The generated project now includes additional resources and best practices:

project/
├── pom.xml
├── .gitignore                   # NEW: Comprehensive ignore rules
├── README.md                    # NEW: Template for project documentation
├── initializr.ps1               # NEW: Windows initializer
├── initializr.sh                # NEW: Linux/Mac initializer
├── .vscode/                     # NEW: VS Code configuration
│   └── launch.json
├── .idea/                       # NEW: IntelliJ configuration
│   └── runConfigurations/
│       └── Spring_Boot-App.xml
├── .env/                        # NEW: Environment variables
│   └── dev.env                  # Generated by initializer
├── .github
│   ├── agents
│   │   └── ps-java-microservice.agent.md   # NEW: Copilot custom agent
│   └── workflows
│       ├── maven_build.yml         # NEW: GitHub Action, CI workflow  
│       └── maven_build_deploy.yml  # NEW: GitHub Action, CD workflow
└── src/
    ├── main/
    │   ├── java/
    │   │   └── package/
    │   │       ├── App.java
    │   │       ├── controller/
    │   │       │   └── ExampleController.java
    │   │       └── service/
    │   │           └── ExampleService.java
    │   ├── resources/
    │   │   ├── application.properties
    │   │   ├── application-dev.properties   # Spring profile support
    │   │   ├── application-test.properties
    │   │   ├── application-prod.properties
    │   │   └── banner.txt                   # NEW: Fancy Cumulocity banner
    │   ├── configuration/
    │   │   ├── cumulocity.json             # Microservice manifest
    │   │   └── logging.xml                 # Logback configuration
    │   └── docker/
    │       └── Dockerfile
    └── test/
        └── java/
            └── AppTest.java                # JUnit 5 + SpringBootTest

:hammer_and_wrench: Updated Dependencies: Spring Boot and Cumulocity SDK Versions

The archetype now uses the latest stable versions of Spring Boot 3.4 and the Cumulocity Microservice SDK 2025.X, ensuring you start with the most up-to-date libraries and features.

  • Java 17
  • Spring Boot 3.4
  • Cumulocity Microservice SDK 2025.X

Prerequisites

Before you begin, ensure you have:

  • :white_check_mark: Java 17+ installed
  • :white_check_mark: Maven 3.8+ installed
  • :white_check_mark: Cumulocity Tenant 2025.1.0+
  • :white_check_mark: go-c8y-cli installed and configured with a session to your development tenant

Step-by-Step Guide

Step 1: Install the Archetype

Clone and install the archetype in your local Maven repository:

git clone https://github.com/Cumulocity-IoT/cumulocity-microservice-archetype.git
cd cumulocity-microservice-archetype
mvn clean install

Step 2: Generate Your Project

Navigate to your workspace and run the archetype in interactive mode:

Most Terminals:

mvn archetype:generate \
  -DarchetypeGroupId=cumulocity.microservice \
  -DarchetypeArtifactId=cumulocity-microservice-archetype \
  -DinteractiveMode=true

PowerShell:

mvn archetype:generate `
  "-DarchetypeGroupId=cumulocity.microservice" `
  "-DarchetypeArtifactId=cumulocity-microservice-archetype" `
  "-DinteractiveMode=true"

Step 3: Define Your Microservice

The interactive mode will prompt you for:

  1. Microservice Name: Use lowercase letters, digits, and dashes (max 23 characters)

    • Example: hello-devices

  2. Artifact ID: Default is cumulocity-microservice-<name>

    • Press Enter to accept the default or provide your own

  3. Package Name: Default is cumulocity.microservice.<name>

    • :warning: Important: Replace dashes with underscores for valid Java packages
    • Example: cumulocity.microservice.hello_devices

  4. Confirm: Review your configuration and type Y to generate the project

Step 4: Initialize with Bootstrap Credentials (NEW!)

This is where the magic happens! Navigate to your new project and run the initializer script:

Windows (PowerShell):

cd cumulocity-microservice-hello-devices
.\initializr.ps1

Linux/macOS (Bash):

cd cumulocity-microservice-hello-devices
. ./initializr.sh

The script will:

  1. Create the microservice in your Cumulocity tenant
  2. Retrieve bootstrap credentials
  3. Save them to .env/dev.env
  4. Display a confirmation message
Creating microservice 'hello-devices' and retrieving bootstrap credentials...
Wrote environment variables to .env/dev.env
Start your IDE! Run configurations already prepared for IntelliJ and VS Code.

Step 5: Start Developing

Option A: Using VS Code

  1. Open the project in VS Code: code .
  2. Press F5 or go to Run > Start Debugging
  3. Select the Spring Boot-App configuration
  4. The microservice starts with credentials automatically loaded!

Option B: Using IntelliJ IDEA

  1. Open the project in IntelliJ IDEA
  2. Wait for Maven import to complete
  3. (Optional) Install the EnvFile plugin for automatic .env loading
  4. Click the Run button or press Shift+F10
  5. Select the Spring Boot-App configuration
  6. The microservice starts immediately!

Option C: Command Line

mvn clean package
java -jar target/cumulocity-microservice-hello-devices-1.0.0-SNAPSHOT.jar

Be aware that a Docker image is also created during the build process. However, the Docker build can be skipped by changing the property in the pom.xml to <c8y.docker.skip>true</c8y.docker.skip>.

Step 6: Test Your Microservice

Open your browser and navigate to:

http://localhost:8080/api/hello/devices

When prompted for credentials:

  • Username: {tenant}/{username} (e.g., t12345/alexander.pester@cumulocity.com)
  • Password: Your Cumulocity password

You should see a JSON array of all devices from your tenant. Congratulations! Your microservice is running locally and connected to Cumulocity!

Step 7: Push to GitHub and Enable CI/CD

  1. Initialize a Git repository: git init
  2. Create a remote repository on a platform like GitHub, GitLab, or Bitbucket
  3. Check the prepared .gitignore to ensure it meets your needs
  4. Add and commit your code: git add . && git commit -m "Initial commit"
  5. Connect to your remote: git remote add origin <your-repository-url>
  6. Push your code to the remote repository: git push -u origin main
  7. If you use GitHub, the included GitHub Actions workflows will automatically run on pushes to main and develop branches. However, you need to add the following secrets to your repository settings: Secrets and variables > Actions > New repository secret
secrets.C8Y_HOST
secrets.C8Y_USER
secrets.C8Y_PASSWORD

Key Differences from the 2022 Version

Feature 2022 Version 2026 Version
Credential Setup Manual Base64 copy from DevTools Using go-c8y-cli sessions
Environment Variables Set in property files Automated .env/dev.env generation, added to .gitignore
VS Code Support None Pre-configured run configuration
IntelliJ Support None Pre-configured run configuration
Documentation Minimal README Comprehensive README with IDE instructions
GitHub Actions None CI/CD workflows included
Copilot Custom Agents None Included for AI-assisted development

Conclusion

The enhanced cumulocity-microservice-archetype eliminates the friction from microservice development. With automated credential management, full IDE integration, and best practices built in, you can focus on what matters: building great features for your IoT platform.

The initializer scripts alone save 10-15 minutes of manual setup per project. Multiply that across your team and projects, and you’re saving hours with every new project.

Give it a try and share your feedback! The archetype is open-source and welcomes contributions. Please report issues or suggest improvements on the Github repository Issues

Useful Links

GitHub: cumulocity-microservice-archetype

Example generated project: cumulocity-microservice-hello-devices

5 Likes