Getting Started

Prerequisites, local setup, bootstrap configuration, and running the admin-service for the first time.

Prerequisites

Before running the admin-service locally, the following platform services must be up and reachable:

Service	Default Local Port	Purpose
HashiCorp Vault	`8091`	Secrets source (AppRole auth + KV v2)
Keycloak	`5433`	JWT issuer + Admin Client
Eureka Server	`8761`	Service registry
Spring Cloud Config Server	`8090`	Remote config
MongoDB	`27017`	Shared data store (via common lib)

The Arya Banking infra stack is managed in the dedicated arya-banking-infra repository using concern-based Docker Compose files (kafka.yml, keycloak.yml, platform.yml, vault.yml) all sharing the arya-banking-net network.

Vault Pre-requisites

The admin-service bootstraps using AppRole authentication. You need a valid role-id and secret-id before the service can start.

Step 1 — Enable the AppRole auth method (once only):

Bash code-highlight

vault auth enable approle

Step 2 — Create the admin-service AppRole with the admin policy:

Bash code-highlight

vault write auth/approle/role/admin-service \
  token_policies="admin-service-policy" \
  token_ttl=1h \
  token_max_ttl=4h

Step 3 — Fetch the role-id:

Bash code-highlight

vault read auth/approle/role/admin-service/role-id

Step 4 — Generate a secret-id:

Bash code-highlight

vault write -f auth/approle/role/admin-service/secret-id

Step 5 — Upload the admin-service policy from the service itself (after first boot with root token):

Bash code-highlight

curl -X POST http://localhost:8089/api/admin/vault/policies?service=admin-service \
  -H "Authorization: Bearer <admin-jwt>"

Vault Credentials File

The bootstrap.yml imports vault-credentials.yml from the project root. Create this file before starting the service — it's already in .gitignore so it won't be committed:

Yaml code-highlight

# vault-credentials.yml (project root — gitignored)
spring:
  cloud:
    vault:
      app-role:
        role-id: <your-role-id>
        secret-id: <your-secret-id>

The optional: prefix in bootstrap.yml allows the service to start even without this file. Without it, Vault auth will fail with the placeholder values.

Running the Service

# From the repo root
mvn spring-boot:run

The service starts on port 8089 and registers with Eureka automatically.

Verifying Startup

Once running, the following checks confirm a healthy start:

Actuator health:

Bash code-highlight

curl http://localhost:8089/actuator/health

Swagger UI:

Open http://localhost:8089/swagger-ui/index.html in your browser. All five controller groups should be visible.

Eureka dashboard:

The service should appear as ARYA-BANKING-ADMIN-SERVICE on http://localhost:8761.

GitHub Packages Authentication

The arya-banking-common dependency is hosted on GitHub Packages. Maven resolves it using the settings.xml at the repo root. Ensure your GH_PAT environment variable is set with read:packages scope, or provide the token directly in ~/.m2/settings.xml.

Xml code-highlight

<!-- settings.xml (repo root) -->
<server>
  <id>github</id>
  <username>${env.GITHUB_ACTOR}</username>
  <password>${env.GH_PAT}</password>
</server>

setuplocaldocker

Architecture

Configuration Reference