Getting Started

Axelix and your environments

A typical software development lifecycle spans several environments. Whatever your exact names for them — dev, sandbox, QA, UAT, staging — every environment falls into one of two classes: production and non-production.

So the first question teams usually ask: is Axelix Master supposed to run in production? Yes. Master is designed to run both in production and in test environments — from the performance, security, and fault-tolerance points of view. Running Master in production is an established practice, not an off-label use.

However, we strongly recommend keeping the production deployment of Axelix separate from the deployment that manages your test environments. In other words: do not run a single Master that manages every environment. The reasons:

1. Access control differs. The RBAC configuration on a test environment almost certainly does not match production. The list of people allowed to change log levels, toggle caches, or take a heap dump in production is much shorter than on staging. See Roles and authorities.
2. Network rules differ. The rules governing who can reach the Master UI and the Master MCP server are typically far stricter in production than in test environments.
3. Policies will differ. The Axelix Enterprise policies, currently in development, are also expected to be environment-specific.

With that separation in mind, the adoption path goes test-first. As a result, by the time Axelix reaches production, both the configuration and your team's habits are already proven.

Step 1 — Prepare the database

Master needs a relational database. Out of the box it ships with embedded SQLite and the default jdbc:sqlite:axelix.db URL, so a first run needs no database configuration at all. That default is there to get you up and running quickly.

If you are past playing around and want real value from the installation, pick an engine from the supported list: PostgreSQL, MySQL, or SQLite. For anything beyond a single-node trial, choose PostgreSQL or MySQL — SQLite stores data in a local file, so it does not survive container restarts without a mounted volume and cannot back multiple Master replicas. We plan to expand the list of supported engines in future releases.

Provision the database and a user with schema-migration privileges, because Master applies its schema itself: Liquibase runs on every startup, and you never run migrations by hand — see Database Migrations. The connection is configured through three properties described in the Database section.

Once the database is ready, move on.

Step 2 — Install Master on a test environment

Install Master on a test environment first (or several of them, if you keep separate Axelix deployments per test environment). Any packaging works, so pick whatever fits your infrastructure: a plain JAR, Docker, Docker Compose, or Kubernetes with the first-party Helm chart. The minimal launch for each:

docker run --rm -p 8080:8080 \
  -e AXELIX_MASTER_AUTH_JWT_ALGORITHM=HMAC512 \
  -e AXELIX_MASTER_AUTH_JWT_SIGNINGKEY=replace-with-a-long-random-secret \
  ghcr.io/axelixlabs/axelix:1.0.0

Master is then reachable at http://localhost:8080 (or behind your Ingress on Kubernetes). Sign in with the super-admin account.

Then configure it. Master accepts configuration from many sources — environment variables, an external config file, a Spring Cloud Config Server, or HashiCorp Vault — so fitting it into your existing configuration pipeline should not be a big deal. See Supplying properties.

The two JWT values in the launch snippets above are the only properties Master requires to start: axelix.master.auth.jwt.algorithm and axelix.master.auth.jwt.signing-key — see Authentication — JWT. Treat the signing key with care from day one: it is the shared secret every managed service will later present to Master, so generate a long random value and keep it in your secret manager rather than in a checked-in file.

Beyond the database connection and the signing key, two decisions are worth making consciously at this step:

• Discovery mode. With auto-discovery, Master scans its Kubernetes environment and probes the services it finds. With self-registration, each service posts heartbeats to Master instead. The two modes can be combined — for example, auto-discovery for in-cluster services plus self-registration for services Master cannot scan.
• Sign-in and RBAC. For small teams, local users — where Master stores user accounts in its own database — will probably be enough. For large organizations, OAuth2 / OIDC against your identity provider is usually the better option. Either way, the bootstrap super-admin account gets you into the UI on day one.

Step 3 — Add the starter and the build plugin to your services

Next, gradually add the client-side components to the services you want Master to manage. There are two of them, and both are required: the Axelix Spring Boot starter matching the service's Spring Boot major version, and the Axelix build plugin for Maven or Gradle. Both are published on Maven Central, so adding them is an ordinary dependency change — no private repositories involved. Axelix is versioned in lockstep, so use the same Axelix version for Master, the starters, and the build plugin — see Compatibility & Versioning for the starter-to-Boot mapping and the exact drift rules.

For a Spring Boot 4 service, the build changes look like this (replace the 4 with 2 or 3 to match the service's Boot major version):

plugins {
    id("com.axelixlabs.axelix") version "1.0.0"
}

dependencies {
    implementation("com.axelixlabs:axelix-spring-boot-4-starter:1.0.0")
}

Adding the dependencies alone is not enough. In addition, each service needs two pieces of configuration, all described in detail on the starter configuration page. On Axelix 1.2.0 and later the actuator endpoints themselves need nothing here: the starter adds them to management.endpoints.web.exposure.include automatically — see Actuator endpoints. On older versions exposing them is a third, mandatory piece of configuration — see the note below the snippets.

• Set the shared JWT signing key from step 2 under axelix.sbs.auth.jwt.*. A key mismatch between Master and the service is the most common cause of 401 responses — see Share the JWT signing key with Master and Troubleshooting.
• Configure discovery — only if you chose self-registration. Point the axelix.sbs.discovery.* properties at your Master, as shown in Let Master find the instance. With Master-side auto-discovery, there is nothing extra to configure in the service.

Put together, the minimal service configuration:

axelix:
  sbs:
    auth:
      jwt:
        algorithm: HMAC512
        signing-key: ${AXELIX_JWT_SIGNING_KEY}

management:
  endpoints:
    web:
      exposure:
        include:
          - axelix-metadata
          - axelix-beans
          - axelix-caches
          - axelix-conditions
          - axelix-configprops
          - axelix-details
          - axelix-env
          - axelix-feign
          - axelix-gc
          - axelix-heap-dump
          - axelix-loggers
          - axelix-metrics
          - axelix-scheduled-tasks
          - axelix-thread-dump

Roll them out service by service. As each service redeploys to a test environment, it shows up in the test Master, and the team can start using the UI and MCP against it right away.

One production-related detail is worth planning for. Services usually promote the same artifact from test toward production, so the starter reaches production before Master does. If such a service runs with self-registration enabled, its starter will keep trying to register against a Master that does not exist yet. For those services, set axelix.sbs.enabled=false in the production configuration to keep the starter dormant — see Disabling the starter.

Step 4 — Install Master in production

Finally, when the test rollout has proven itself, bring Axelix to production. This is a repeat of steps 1 and 2, as a separate deployment: its own database, production-grade RBAC, and the stricter network access rules to the UI and the MCP server that production demands.

Once the production Master is up, remove any temporary axelix.sbs.enabled=false overrides from step 3 so the production instances register and become visible.

Related

• What is Master? — background on what Master does with the services it manages.
• Configuring Master — every Master property, packaging option, and configuration source.
• Configuring Spring Boot Starter — wiring a service up in detail.
• Configuring the build plugin — the second required client-side component.
• Authentication — sign-in options, roles, and authorities.
• Compatibility & Versioning — which starter matches which Spring Boot and Java version, and how component versions stay compatible with each other.
• Troubleshooting — the most common installation problems (401 responses, wrong starter module, a service that never registers) and their fixes.