Getting Started with the Milesoft Platform

This guide provides a comprehensive, zero-to-one walkthrough for bootstrapping, configuring, and running a brand-new backend application on the Milesoft Platform. By following this guide, you will initialize a Java 17+ Spring Boot microservice, configure the core Milesoft stack, integrate Google Cloud credentials, manage environments and secrets, and extend foundational platform configuration classes.

💡 Notice: This guide assumes milesoft CLI v0.5.2+. Run milesoft update to ensure you are on the latest version.

---

1. Bootstrapping Your Google Cloud Platform (GCP) Project

Before initializing or scaffolding your backend microservice locally, you must bootstrap and configure your Google Cloud Platform (GCP) project environment on the Milesoft Platform by running the milesoft init gcp command.

This step is a strict prerequisite. Running init gcp ensures that:

• Billing is verified: Confirms that your GCP project has an active Google Billing Account linked.
• Service APIs are enabled: Idempotently enables critical GCP APIs (run.googleapis.com, cloudbuild.googleapis.com, secretmanager.googleapis.com, storage.googleapis.com, firestore.googleapis.com).
• Build Bucket is provisioned: Configures a dedicated storage bucket gs://[PROJECT_ID]_cloudbuild with an automatic 7-day deletion lifecycle policy.
• IAM Permissions are set: Grants the default Cloud Run service account the necessary access to Secret Manager.
• Secrets are seeded: Automatically generates 256-bit AES master passwords and cryptographic salts (encryption_password and encryption_salt), securely saving them inside GCP Secret Manager.
• Gateway API Keys are synchronized: Registers your project's milesoft_apiKey securely on both GCP Secret Manager and the central Milesoft Gateway.

• Command:

  milesoft init gcp --project "your-gcp-project-id"
  

  (Replace "your-gcp-project-id" with your actual Google Cloud Project ID. If you don't know where to find this, see the How to Find Your GCP Project ID guide).

After running this command, your GCP project will be securely registered with your platform application profile, allowing subsequent bootstrapping commands to dynamically resolve your cloud project ID.

---

2. Bootstrapping Your Application with the CLI

The Milesoft CLI provides a high-performance boilerplate generator through the milesoft init app command. This command sets up a fully scaffolded backend project (following our -app architecture convention) pre-configured with the standard directory structure, Gradle build files, base properties, and security configurations, matching your active platform application context.

2.1 Command Execution

Open your terminal and run:

milesoft init app

2.2 Configuration Prompting

During initialization, the CLI dynamically queries the central gateway for your active application's profile and guides you through several interactive prompts:

• Company Name: Your organization's name (e.g., Acme Corp), used for license and copyright headers across code blocks.
• Company Domain: Your primary domain name (e.g., acme.com). The CLI automatically reverses this domain and sanitizes it to generate clean, idiomatic Java package structures (e.g., com.acme).

2.3 Application Profile Automatic Detection

During bootstrapping, the CLI automatically detects the active application's Application Profile (MultiTenant, SingleTenant, or MobileOnly) from the central gateway configuration and scaffolds the appropriate code template:

Profile	Automatic Template Scaffolded	Main Controller Generated	Primary Frontend	Auth Mechanism
MultiTenant	MultiTenant Spring Boot + React Web	AuthController (extends AbstractMultiTenantAuthController)	React Web / Native Web View	Username/Password + Switch Accounts
SingleTenant	SingleTenant Spring Boot + React Web	AuthController (extends AbstractSingleTenantAuthController)	React Web / Native Web View	Username/Password
MobileOnly	MobileOnly Spring Boot + React Native	AuthController (extends AbstractMobileOnlyAuthController)	React Native (No Web)	Device-bound Simple Auth & Link Code

For an in-depth explanation of these profiles and their architectural security differences, refer to the Platform Architecture Guide.

---

3. Scaffolded Project Architecture

The CLI generates a clean, standardized Spring Boot structure. Here is a high-level overview of the bootstrapped directory layout (assuming a project named my-innovative-app has been initialized):

my-innovative-app/
├── build.gradle                   # Gradle plugins, repositories, and dependency declarations
├── settings.gradle                # Gradle root project settings
├── gradlew                        # Gradle wrapper script for Unix-based systems
├── gradlew.bat                    # Gradle wrapper script for Windows
├── Dockerfile                     # Containerization instructions for deployment
├── cloudbuild.yaml                # Google Cloud Build deployment pipeline script
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/yourcompany/myapp/
    │   │       ├── Application.java      # Spring Boot main class entry point
    │   │       └── config/               # Concrete beans extending platform abstract configs
    │   │           ├── AccountsConfig.java
    │   │           ├── AuthConfig.java
    │   │           └── SecretsConfig.java
    │   └── resources/
    │       ├── application.properties             # Base settings and gateway baseUrl variables
    │       ├── application.private.properties     # GIT-IGNORED: Local default secret overrides
    │       ├── application-sand.properties         # Sandbox/Staging GCP environment profiles
    │       └── application-sand.private.properties # GIT-IGNORED: Local sandbox secret overrides
    └── test/
        └── java/
            └── com/yourcompany/myapp/
                └── TestApplication.java   # Base context verification test

---

4. In-Depth Configuration & Build Setup

4.1 Dependencies and Build Setup (build.gradle)

The scaffolded build file applies the GCP Artifact Registry plugin and declares dependencies on core Milesoft stack foundation libraries. Note that Milesoft modules resolve from the secure read-only milesoft-repo registry:

plugins {
    id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
    id "java"
    id "org.springframework.boot" version "3.5.15"
}

repositories {
    mavenLocal()       // Checked first for local offline development overrides
    mavenCentral()
    maven {
        // Secure Artifact Registry URL containing Milesoft SDKs
        url "artifactregistry://us-west2-maven.pkg.dev/milesoft-repo/repo-maven"
    }
}

dependencies {
    // Ingest the base application stack runtime framework
    implementation "io.milesoft:app-stack:2.5.0"
    
    // Ingest specific platform service SDKs based on CLI prompt selections
    implementation "io.milesoft:liquid-sdk:2.1.0"
    implementation "io.milesoft:contacts-sdk:2.0.1"
    
    // Ingest platform utility extensions
    implementation "io.milesoft:storage-ext:2.0.1"
    implementation "io.milesoft:task-queue-ext:2.1.1"
    implementation "io.milesoft:vertex-ext:2.0.1"
    
    // Standard testing dependencies
    testImplementation "junit:junit:4.13.2"
    testImplementation "org.mockito:mockito-core:5.21.0"
    testImplementation "io.milesoft:openpojo-ext:2.0.1"
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

4.2 Main Properties (application.properties)

The central properties file configures non-sensitive default values, routes traffic to central platform microservices, and defines Secret Manager placeholders:

# Logging Configurations
logging.level.root=INFO
logging.level.io.milesoft=DEBUG
logging.level.com.yourcompany.myapp=DEBUG

# Platform Gateway Services Base URLs
baseUrl.accounts=https://accounts.milesoft.api
baseUrl.notifications=https://notifications.milesoft.api
baseUrl.liquid=https://liquid.milesoft.api
baseUrl.contacts=https://contacts.milesoft.api

# Platform Secret Placeholders (Resolved via Secret Manager or Local Overrides)
secrets.milesoft.apiKey=milesoft_apiKey
secrets.milesoft.token=milesoft_token
secrets.encryption.password=encryption_password
secrets.encryption.salt=encryption_salt

# Active Spring Profile (e.g., sand for local sandbox development)
spring.profiles.active=sand

4.3 GCP Environment Profiles (application-sand.properties)

Environment-specific properties files (such as application-sand.properties for staging or application-prod.properties for production) specify target Google Cloud projects and configurations:

# Application & Auth Identifiers
app.id=my-app-id
account.id=my-sandbox-account-id
user.id=my-sandbox-admin-user-id

# Google Cloud Platform Infrastructure Configuration
secrets.project=my-app-sand
pubSub.project=my-app-sand
taskQueue.project=my-app-sand
vertex.project=my-app-sand

# Storage Configuration
storage.bucket=my-app-sand-documents

# Vertex AI Settings
vertex.location=us-central1
vertex.model=gemini-3.5-flash

---

5. Secret Management & Local Development Overrides

The Milesoft Secrets Extension (secrets-ext) acts as a secure decorator around Google Cloud Secret Manager. It simplifies operations by loading secrets dynamically at runtime without hardcoding sensitive strings into files that get committed to git repositories.

5.1 How Secret Resolution Works

In application.properties, properties matching the prefix secrets. are assigned key values (e.g. secrets.milesoft.apiKey=milesoft_apiKey). At startup:

1. secrets-ext queries Secret Manager in the specified secrets.project (e.g., my-app-sand).
2. It fetches the secret named milesoft_apiKey and transparently injects its decrypted payload into your Spring context as the active value of ${secrets.milesoft.apiKey}.

5.2 Local Development with Zero-Dependency Overrides

Connecting to GCP services during fast local coding sessions or offline development is often unneeded or impossible. To support offline development, secrets-ext detects local override properties:

• Create a file named application.private.properties or application-sand.private.properties inside your src/main/resources folder.
• These files are pre-configured in your .gitignore and must never be committed.
• Write raw, unencrypted override values matching the keys of your target secrets:

# Local raw development secret overrides (src/main/resources/application-sand.private.properties)
encryption.password=myLocalDevRawPasswordValueAndSalt
encryption.salt=4a85da53520247612e50eb0bd5c4ae59
milesoft.apiKey=myLocalDevRawGatewayApiKeyForLocalTesting
milesoft.token=myLocalDevRawGatewayTokenForLocalTesting

At startup, secrets-ext loads these unencrypted local values directly into memory, completely bypassing remote GCP Secret Manager API calls.

---

6. Integrating with Core Base Configuration Classes

To utilize the core platform features of app-stack, downstream developers extend Spring configuration templates to register Spring-managed beans. Here are three standard configurations generated during the milesoft init app process:

6.1 Secrets Configuration (SecretsConfig.java)

Extends the abstract GCP Secret Manager helper, injecting the GCP project identifier to bootstrap the SecretManagerService:

package com.yourcompany.myapp.config;

import io.milesoft.stack.config.AbstractSecretsConfig;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SecretsConfig extends AbstractSecretsConfig {

    @Autowired
    public SecretsConfig(@Value("${secrets.project}") String project) {
        super(project);
    }
}

6.2 Accounts Configuration (AccountsConfig.java)

Integrates your application with the central accounts microservice API. It automatically manages API key authentication when invoking platform services:

package com.yourcompany.myapp.config;

import io.milesoft.secrets.services.SecretManagerService;
import io.milesoft.stack.config.AbstractAccountsConfig;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AccountsConfig extends AbstractAccountsConfig {

    @Autowired
    public AccountsConfig(
        SecretManagerService secretManagerService,
        @Value("${secrets.milesoft.apiKey}") String secretApiKey,
        @Value("${baseUrl.accounts}") String baseUrl) {

        super(secretManagerService, secretApiKey, baseUrl);
    }
}

6.3 Authentication & Identity Configuration (AuthConfig.java)

Extends the abstract multi-tenant security model. It configures JSON Web Token (JWT) verification, registers an administrative fallback actor context, and establishes token refresh handlers:

package com.yourcompany.myapp.config;

import io.milesoft.accounts.client.v2.AuthClient;
import io.milesoft.app.config.AbstractMultiTenantAuthConfig;
import io.milesoft.app.strategy.RefreshTokenManager;
import io.milesoft.clients.PlatformClient;
import java.time.Clock;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cache.CacheManager;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AuthConfig extends AbstractMultiTenantAuthConfig {

   @Autowired
   public AuthConfig(
           Clock clock,
           PlatformClient platformClient,
           AuthClient authClient,
           CacheManager cacheManager,
           RefreshTokenManager refreshTokenManager,
           @Value("${baseUrl.accounts}") String expectedIssuer,
           @Value("${app.id}") String appId) {

      super(clock, platformClient, authClient, cacheManager, refreshTokenManager, 
              expectedIssuer, appId);
   }
}

---

7. Compilation & Execution

Once the configuration class extensions are registered and properties files are specified:

1. Clean and Compile: Clean your workspace and run a compilation phase to ensure all annotation processors (such as Lombok and MapStruct) generate classes successfully:

   ./gradlew clean build -x test
   

2. Launch locally: Launch the Spring Boot application utilizing your local sandbox environment properties:

   ./gradlew bootRun --args='--spring.profiles.active=sand'
   

3. Verify Context: Send a GET request to the local actuator endpoint to verify application context health:

   curl http://localhost:8080/actuator/health
   

---

8. Next Steps

With your application up and running locally, proceed to:

1. Cloud Deployment Guide — Deploy your compiled Spring Boot microservice to Google Cloud Run and register your live service URLs.