> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup and start

> Generate, configure, and run a Spring Boot application using an Atoti Enterprise Risk Suite solution archetype, and open Atoti UI and Atoti Admin UI.

This guide explains how to create a Spring Boot application with an Atoti Enterprise Risk Suite solution.
The result is a running application, configurable and extensible using the Atoti Configuration API. The same API is used to customize the solution's default database and cube behavior, and to add new cubes.

Setup involves the following steps:

1. Generate an application from the archetype
2. Configure the application properties
3. Run the application

## Prerequisites

* Java 25 or later installed.
* Apache Maven 3.9+ installed.
* Access to the ActiveViam Maven repository (`atoti-solutions-mvn`).
* A valid Atoti license, configured via the `ATOTI_LICENSE` environment variable (base64-encoded string) or file path. See [Getting Started: License](https://docs.activeviam.com/engine/java-sdk/latest/start/license).

## Step 1: Generate the application

Use the `solution-app-archetype` to generate a ready-to-run application. The archetype is published to the ActiveViam Maven repository.

Run the following command:

```bash theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
mvn archetype:generate \
  -DarchetypeGroupId=com.activeviam.solutions \
  -DarchetypeArtifactId=solution-app-archetype \
  -DarchetypeVersion=${solutions.version} \
  -DgroupId=com.activeviam.myapp \
  -DartifactId=my-app \
  -Dpackage=com.activeviam.myapp \
  -DapplicationName=MyApp \
  -DstarterGroupId=${starter.groupId} \
  -DstarterArtifactId=${starter.artifactId} \
  -DstarterVersion=${solutions.version} \
  -DinteractiveMode=false
```

Replace `${solutions.version}` with the target release version, and `${starter.groupId}` and `${starter.artifactId}` with the coordinates for the chosen solution. The following table lists the available starters:

| Solution | starterGroupId | starterArtifactId |
| - | - | - |
| Market Risk (Enterprise Risk) | `com.activeviam.springboot` | `var-cube-starter` |
| Counterparty Credit Risk (Enterprise Risk), PFE | `com.activeviam.springboot` | `pfe-cube-starter` |
| Counterparty Credit Risk (Enterprise Risk), Ratings | `com.activeviam.springboot` | `ratings-cube-starter` |

For Counterparty Credit Risk (Enterprise Risk), each cube has its own starter. See [PFE setup and start](../../solutions/counterparty-credit-risk/pfe/developer-guide/setup-and-start) and [Ratings setup and start](../../solutions/counterparty-credit-risk/ratings/developer-guide/setup-and-start).

> **Note**: If your `artifactId` contains hyphens (e.g., `my-app`), set `package` to a valid Java package name (e.g., `-Dpackage=com.activeviam.myapp`).

### Generated project structure

The archetype generates a complete Spring Boot application:

```
my-app/
├── pom.xml
├── src/main/java/com/activeviam/myapp/
│   ├── MyAppApplication.java                  # Entry point; opts into as-of-date data loading
│   ├── ModelConfigurer.java                   # Hook for custom database/cube configuration
│   ├── security/                              # Authentication and security filters
│   └── ui/
│       └── CustomUiEnvJsResourceConfig.java   # UI configuration
├── src/main/resources/
│   ├── application.yml
│   ├── i18n/en-US                             # Atoti UI translations
│   └── static/atoti-ui/
│       └── extensions.json
└── src/test/
    ├── java/com/activeviam/myapp/
    │   └── MyAppApplicationIT.java            # Context-load integration test
    └── resources/
        └── application-it.yml                 # Binds a free port for the test above
```

## Step 2: Configure the application properties

The generated `application.yml` provides sensible defaults that are sufficient to start the application without changes. Customize cube behavior by editing `src/main/resources/application.yml`.

For solution-specific properties, refer to the configuration properties page for the chosen solution.

### How to customize the application

The generated `ModelConfigurer.java` is the entry point for extending the default configuration of any solution. It implements `IModelConfigurer`, which exposes two methods:

* `configureDatabase(IDatabaseConfigurator)`: defines tables and joins in the database
* `configureCubes(ICubeManagerConfigurator)`: defines cubes, dimensions, and measures

The generated class is a stub with a commented-out cube field. Once wired to a cube, it has the following shape:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
@RequiredArgsConstructor
public static class ModelConfigurer implements IModelConfigurer {
  // Inject your solution's cube interface, for example IVaRCube.
  private final ObjectProvider<ISolutionCube<?, ?, ?, ?>> cube;
  @Override
  public void configureDatabase(final IDatabaseConfigurator databaseConfigurator) {
    // Add tables, fields and joins here, referencing them through
    // cube.getObject().databaseModel().
  }
  @Override
  public void configureCubes(
      final ICubeManagerConfigurator cubeManagerConfigurator,
      final IDatabaseSchema databaseSchema) {
    cube.ifAvailable(
        solutionCube -> {
          final var measuresConfigurator =
              cubeManagerConfigurator.cube(solutionCube.name()).measures();
          // Build on solutionCube.measures() to add measures of your own.
          measuresConfigurator.addMeasure("Contributors Count", Copper.count());
        });
  }
}
```

Replace `ISolutionCube<?, ?, ?, ?>` with the cube interface of the solution. The table below lists them.

| Solution | Cube interface | Registered by | Public API |
| - | - | - | - |
| Market Risk (Enterprise Risk) | `IVaRCube` | `var-cube-starter` | [Public API](../../solutions/market-risk/var/developer-guide/public-api) |
| Counterparty Credit Risk (Enterprise Risk), PFE | `IPfeCube` | `pfe-cube-starter` | [PFE public API](../../solutions/counterparty-credit-risk/pfe/developer-guide/public-api) |
| Counterparty Credit Risk (Enterprise Risk), Ratings | `IRatingsCube` | `ratings-cube-starter` | [Ratings public API](../../solutions/counterparty-credit-risk/ratings/developer-guide/public-api) |

Inject the cube through `ObjectProvider` when the cube can be disabled. The configurer then still loads when the cube is off, and `ifAvailable` runs only when the cube is present. A cube that is always on can be injected directly. An application that runs several cubes injects one `ObjectProvider` per cube.

The generated class is a top-level class annotated with `@Configuration`, which registers it as a Spring bean.

For examples of how to use each method, see [Customizing the data model](./database/customizing-data-model), [Dimensions](./cube/dimensions), and [Measures](./cube/measures).

### Data loading

Each solution ships the channels and CSV topics that describe how its cube is fed, and an alias grouping them that it publishes through its topics bean (`I[Cube name]CubeTopics`).
Point them at your files with `atoti.solution.data-load.csv.base-path`, and set `topic-type` to read from a cloud bucket or the local filesystem.

Requesting a load is the application's part, and the generated application already opts in. `@Import(AsOfDateDataLoadConfiguration.class)` on the application class gives it the startup load, the `/activeviam/as-of-date/rest/v1` endpoints, and the load and unload events. What is left to fill in is what to load and when:

```yaml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
atoti:
  solution:
    data-load:
      csv:
        base-path: ./data/#{AS_OF_DATE}
      as-of-date:
        # One alias per starter this application depends on.
        topics:
          - PFE_LOAD
        unload-topics:
          - PFE_UNLOAD
        initial-dates:
          enabled: true
          dates:
            - 2024-03-04
```

Until `topics` names something, the application starts and serves its cube but loads nothing.

To go further than the properties (repoint a topic at your own files, or attach a table of your own to one the solution already reads), publish an `IDataLoadConfigurer` bean. Inject the solution's channel and topic name beans alongside it (e.g. `IPfeCubeChannels` and `IPfeCubeTopics`) and take every channel and topic name from them rather than writing the name out. [Data loading](./data-loading) covers the full property set and shows both overrides.

## Step 3: Run the application

Start the Spring Boot application. The default server port is `9090`, configured in `src/main/resources/application.yml`.

To confirm the cube is available, query the cube discovery endpoint. The generated application includes a default `admin` user (password: `admin`):

```
http://localhost:9090/activeviam/pivot/rest/v10/cube/discovery
```

To explore the cube in a browser, see [How to access Atoti UI and Atoti Admin UI](#how-to-access-atoti-ui-and-atoti-admin-ui).

### Optional: How to enable the health endpoint

The Spring Boot Actuator health endpoint is not exposed by default. To enable it, add the following to your `application.yml`:

```yaml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
management:
  endpoints:
    web:
      exposure:
        include: health
```

Verify the application status at:

```
http://localhost:9090/actuator/health
```

Expected output:

```json theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
{"status": "UP"}
```

## How to access Atoti UI and Atoti Admin UI

The application serves two web interfaces next to the cube:

* **Atoti UI** is where users build dashboards and explore the data of the cube.
* **Atoti Admin UI** is where administrators monitor the server, manage users, inspect the datastore, and perform other administrative tasks.

On the default port, they are available at:

| Interface | URL |
| - | - |
| Atoti UI | `http://localhost:9090/ui` |
| Atoti Admin UI | `http://localhost:9090/admin/ui` |

For an application that listens elsewhere, use `http://<host>:<port>/ui` and `http://<host>:<port>/admin/ui`.

Every solution starter and cube starter brings `atoti-ui-starter` and `atoti-admin-ui-starter`, so no additional server-side configuration is needed to expose a cube to either interface. An application generated from the archetype already contains the environment configuration both interfaces read (`CustomUiEnvJsResourceConfig`). Sign in with a user the application defines, such as the default `admin` user of the generated application.

For the use of Atoti UI, see the [Atoti UI documentation](https://docs.activeviam.com/products/atoti/ui/latest/).

## Related pages

* [Customizing the data model](./database/customizing-data-model)
* [Dimensions](./cube/dimensions)
* [Measures](./cube/measures)