Platform Prerequisites

Before building or integrating applications on the Milesoft Platform, you must establish your administrative billing identities and configure your local workstation with essential command-line tools. These steps ensure secure repository access, identity management, and streamlined deployment.

1. Billing Account Setup

Establishing your billing footprint on both the Milesoft Platform and Google Cloud Platform is the foundational first step.

1.1 Milesoft Billing Account

Before setting up your local environment or bootstrapping any application, you must establish your Milesoft platform identity by setting up your Milesoft Billing Account.

  • Action Required: Navigate to the Milesoft Billing portal to set up your account.
  • Single Sign-On (SSO): Your Milesoft Billing account uses a centralized identity provider. The same credentials you create to access Billing will be used to log in via the Milesoft CLI (milesoft login) and to authenticate into your custom applications once they are running.

1.2 Google Cloud Platform & Billing

Downstream applications running on the Milesoft Platform reside within single-tenant, customer-owned Google Cloud projects. To deploy and run your customized services, your organization must establish a Google Cloud Billing account and link your deployment projects to it.

💡 Why direct GCP Billing? A lot of platforms try to middleman your cloud infrastructure — they'll handle the hosting for you, but wrap it in hidden fees, hefty markups, and complex tier pricing. We don't believe in that.

With Milesoft, your Google Cloud bill is exactly that: your Google Cloud bill, paid directly to Google. No markup, no hidden premiums, and absolute transparency.

2. Workstation & Core Toolset

We utilize a modern development environment and a dual-CLI strategy to keep infrastructure-level operations separate from platform-level configurations.

2.1 Local Development Environment

Before initializing or compiling a project, ensure your local workstation meets the following runtime specifications:

  • Java Development Kit (JDK) 17+: Spring Boot 3.x and the Milesoft core stack are compiled with Java 17 bytecode compatibility. We highly recommend Azul Zulu or Eclipse Temurin. Verify your local environment and JAVA_HOME variable:
    java -version
echo $JAVA_HOME

3. Command Line Interfaces (CLIs)

3.1 Google Cloud CLI (gcloud)

The gcloud utility serves as our primary security and transport layer. Because Milesoft libraries are hosted securely in Google Cloud Artifact Registry, the local Gradle build plugin leverages gcloud's credential helper to fetch short-lived authorization tokens.

  • Primary Use Case: Authenticating with Maven repositories, pulling private SDK dependencies, inspecting system logs, and executing secure deployments.

  • Installation: Refer to the official Google Cloud CLI Installation Guide to download and install the package manager for your operating system.

  • Authentication:

    # Authenticate primary developer identity
gcloud auth login

# Generate local Application Default Credentials (ADC) for build tools
gcloud auth application-default login

    💡 Why do I need two separate login commands? Google Cloud distinguishes between your interactive terminal commands and background programmatic service access:

    • gcloud auth login establishes your user credentials for executing interactive commands directly in the terminal (e.g., executing deployments or checking cloud logs).
    • gcloud auth application-default login creates local Application Default Credentials (ADC). This saves a specific local token that background build tools and framework compilers (such as our Gradle plugin downloading secure SDK libraries from Google Artifact Registry, or Spring Boot resolving parameters from GCP Secret Manager during local runs) use to programmatically authenticate on your behalf.

3.2 Milesoft CLI (milesoft)

The milesoft CLI is our specialized, high-performance administrative bridge. It allows human developers and automated AI agents (via the Model Context Protocol server mode) to interact directly with the Milesoft gateway APIs.

  • Detailed Guide: For a deep dive into installation, credentials, full command list, and global parameters, see the Milesoft CLI Overview & Reference.

  • Primary Use Case: Bootstrapping a brand new backend project (milesoft init app), switching active application contexts, provisioning tenant accounts, updating email/MFA credentials, compiling Liquid template libraries, and configuring OAuth integrations.

  • Installation:

    # Install the native CLI binary using our universal installer script
curl -fsSL https://milesoft.io/cli/install.sh | sh

  • Authentication: Authenticate securely in the terminal. The CLI will prompt you through email, password, and MFA challenge steps, caching short-lived access tokens and securing refresh keys natively in your OS Keychain:

    # Establish your administrative session securely
milesoft login

4. App, Account, & User Provisioning

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

Before you can run the bootstrap or initialization commands, your organization needs to provision its platform-level application, set up a tenant account, and designate an administrative user context.

  • Provisioning Your App (Mandatory step required before running milesoft login)
    Provision your application in the Milesoft Billing portal by selecting an Application Profile that matches your architecture:
Profile Architecture & Tenancy Frontend Tech Auth & Data Access Model Best Used For
MultiTenant Single backend serving multiple Tenant Accounts. Data owned at Account level. React Web / Native Web View Username/Password + Switch Accounts SaaS apps where users switch between multiple organizations (e.g., Slack, GitHub).
SingleTenant Dedicated to a single entity mapped to one main account. Data owned at User level. React Web / Native Web View Standard Username/Password Enterprise/B2B apps requiring simple logins without account-switching complexity.
MobileOnly Dedicated to a single entity. Data owned at User level. React Native (No Web) Device-bound Simple Auth & Link Code Mobile-first/only experiences requiring swift, device-linked user auth.

For full security and tenancy details, consult the Platform Architecture Guide.

  • Creating a Tenant Account: Once you have logged in, you can register a secure tenant account record representing your organization.
  • Assigning Administrative Users: You can then associate your active developer context with your tenant account and elevate your permissions. This grants your local terminal session full authority to synchronize GCP APIs and deploy cloud systems.

4.1 Creating a Tenant Account

To provision a brand-new tenant account for your organization, execute the milesoft account create command. This creates a secure account record on the central gateway.

  • Command:
    milesoft account create --name "Acme Corporation" --allow-join
  • Result: The gateway registers your new tenant account and returns a unique Account ID (e.g., acc-789-new) and an Account Code (e.g., 123456). Keep the ID handy; you will need it for user management and environment configurations.
  • Key Flags & Parameters:
    • --name (e.g., "Acme Corporation"): The name of your organization's tenant account. This flag is required.
    • --allow-join: A boolean flag allowing users to self-join the account (requires the Account Code). Defaults to true if not specified.

4.2 Adding Yourself as the Admin

With the account created, you must associate your active logged-in user profile with this new account and grant yourself administrative permissions. The administrative context gives your local session authority to configure, manage, and synchronize platform components.

Follow these three simple steps to set up your administrative credentials:

Step 1: Find Your User ID

First, query the platform to find your active user identifier by running the whoami command.

  • Command:
    milesoft whoami
  • Result: Make a note of your User ID (e.g., usr-123-xyz) from the output.

Step 2: Add Yourself to the New Account

Next, use the user add-to command to associate your logged-in user ID with your newly created account.

  • Command:
    milesoft user add-to usr-123-xyz --account acc-789-new
  • Key Flags & Parameters:
    • <user-id> (e.g., usr-123-xyz): Your User ID retrieved from Step 1.
    • --account (e.g., acc-789-new): The Account ID of your newly created tenant.

Step 3: Elevate Your Role to Admin

Lastly, elevate your permissions on the new account by assigning yourself the ROLE_ADMIN role using the user update command.

  • Command:
    milesoft user update usr-123-xyz --account acc-789-new --add-role ROLE_ADMIN
  • Key Flags & Parameters:
    • <user-id> (e.g., usr-123-xyz): Your User ID.
    • --account (e.g., acc-789-new): The Account ID.
    • --add-role: Specify ROLE_ADMIN to grant full administrative permissions.

Once these steps are completed, your local session will have the required administrative context to configure and bootstrap the environment.

5. Next Steps

With your billing environments, CLI setup, and Java runtimes fully configured, proceed to:

  1. Application Bootstrapping & Getting Started — Dive into building your first application, configuring Google Cloud Platform connectivity, and running your Spring Boot microservice locally.