> ## 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.

# The Atoti UI Starter

## Introduction

The Atoti UI Starter automatically sets up an Atoti Server application to work with Atoti UI, while
still allowing custom settings to overrule default behaviors.
This starter creates configurable security rules for the endpoints used by Atoti UI, and sets up
its static file delivery.

The Atoti UI starter may be used alone, but we recommend pairing it with the Atoti Server Starter.

## How to set up Atoti UI

### 1. Add the maven dependency

To use the starter, add the following dependency to your `pom.xml`.

```xml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
<dependency>
  <groupId>com.activeviam.springboot</groupId>
  <artifactId>atoti-ui-starter</artifactId>
  <version>${project.version}</version>
</dependency>
```

The UI starter automatically uses a suitable Atoti UI version for your Atoti Server version.
Nevertheless, the `atoti-ui.version` maven property may be set to the desired version to override
the default.
However, only official UI versions 5.2+ are supported.

### 2. Provide the `env.js` file

Atoti UI needs a JavaScript file named `env.js` during startup to locate the Content Server and the Atoti Server.
Without `env.js`, Atoti UI cannot determine where to connect.

#### Content

`env.js` file content structure is described in Atoti UI set up [documentation](/data-visualization/atoti-ui/5.2/developer-guide/install-and-start/set-up#use-atoti-ui).

| Property        | Required | Effect                                                                              |
| --------------- | -------- | ----------------------------------------------------------------------------------- |
| `jwtServer`     | Yes      | Server used for authentication. All requests carry a JWT obtained from it.          |
| `contentServer` | Yes      | Stores dashboards, widgets, and user settings (theme, preferences and permissions). |
| `atotiServers`  | Yes      | Powers data querying (pivot tables, charts, and data-backed widgets).               |

`atotiServers` is a key-value map: the key identifies the server (shown in the UI as its display name), the value is a `{ url, version }` object.
All servers in the map are available to the UI — users can create widgets targeting any of them.
Saved widgets and dashboards reference servers by their keys, so changing a key breaks every saved widget/dashboard that points to it.

#### Location

There are three ways to configure the `env.js` file's location:

1. Without any additional configuration, Atoti UI Starter automatically loads any `resources/static/atoti-ui/env.js` file provided by the application.
2. (Optional) Set the `atoti.atoti-ui.env-js-resource` property to change the location of the `env.js` file.
   It must contain the path to the folder containing the `env.js` file.
3. (Optional) Create an `AtotiUiEnvJs` bean, defined so that its `getResource()` method returns a Spring `Resource` containing the content of the `env.js` file.
   As any implementation of `Resource` may be used, this content does not necessarily come from a file.

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@Bean
public AdminUiEnvJs adminUiProperties() {
  final Resource adminUiEnvJs = adminUiEnvJs();
  return () -> adminUiEnvJs;
}
```

### 3. Provide the `extensions.js` file

Atoti UI also needs an `extensions.js` file placed at `resources/static/atoti-ui/` to define
which extensions must be used. A sample `extensions.js` file can be found in Atoti UI set up [documentation](/data-visualization/atoti-ui/5.2/developer-guide/install-and-start/set-up#use-atoti-ui).<br />
As a default you can set the content with the basic Atoti UI starter:

```
{
"@activeviam/starter":"extensions/@activeviam/starter/extensionEntry.js",
}
```

### 4. Define Security

This starter defines a security rule to control the access to Atoti UI and its web resources.
Like Atoti Server Starter, it automatically uses
an [`HumanToMachineDsl`](atoti_starter#human-to-machine-dsl) to configure general security
rules.

Should a different behavior be needed, the `atoti.server.security.ui.enabled` property can be set
to `false` to disable this default rule and replace it with one of your own.