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

# Spring Boot SDK - Installation

> Register the GitLab Maven registry and add the nexus-spring-boot-starter dependency.

The `nexus-spring-boot-starter` artifact is hosted on the [GitLab Maven Package Registry](https://gitlab.com/westyx/nexus/sdk/spring-boot/-/packages). It is **public** - no token is required to install.

## 1. Register the repository

Add the registry to your project. Use the **numeric project ID** rather than the URL path so your build is resilient to any future repository moves.

<CodeGroup>
  ```xml title="Maven (pom.xml)" theme={null}
  <repositories>
    <repository>
      <id>gitlab-westyx-nexus</id>
      <url>https://gitlab.com/api/v4/projects/81979866/packages/maven</url>
    </repository>
  </repositories>
  ```

  ```kotlin title="Gradle (build.gradle.kts)" theme={null}
  repositories {
      maven {
          url = uri("https://gitlab.com/api/v4/projects/81979866/packages/maven")
      }
  }
  ```
</CodeGroup>

<Info>
  No token is required - the registry is public.
</Info>

## 2. Add the dependency

<CodeGroup>
  ```xml title="Maven" theme={null}
  <dependency>
    <groupId>dev.westyx.nexus</groupId>
    <artifactId>nexus-spring-boot-starter</artifactId>
    <version>0.10.0</version>
  </dependency>
  ```

  ```kotlin title="Gradle" theme={null}
  implementation("dev.westyx.nexus:nexus-spring-boot-starter:0.10.0")
  ```
</CodeGroup>

## Requirements

* **Java 17** or newer
* **Spring Boot 3.2** or newer (works on any 3.x release)
* (Auto-configured) **Jackson** and **SLF4J** - both already on the Spring Boot classpath

## Verify the installation

After a `mvn dependency:resolve` (or Gradle equivalent) and a fresh build, you should see in the application startup logs:

```
nexus: client ready (key_type=sk, ttl=PT1M)
```

If you don't see this line, the auto-configuration didn't fire. Common causes:

* Missing `nexus.base-url` and `nexus.api-key` in `application.yml` / `application.properties` - the starter is conditional on both being set
* A pre-existing `NexusClient` bean elsewhere - `@ConditionalOnMissingBean` causes the starter to back off when one is already registered
* Spring Boot version below 3.2

## Verifying connectivity

Before writing any code, confirm your endpoint and API key work with a plain `curl`:

```sh theme={null}
curl -s \
  -H "X-Nexus-API-Key: wxs_..." \
  https://your-service.westyx.dev/v1/sync
```

A valid response returns a JSON snapshot with your `configs`, `secrets`, and `flags`. An `HTTP 401` means the key is wrong; `HTTP 404` means the slug is wrong.

To watch the live SSE stream:

```sh theme={null}
curl -N \
  -H "X-Nexus-API-Key: wxs_..." \
  -H "Accept: text/event-stream" \
  https://your-service.westyx.dev/v1/stream
```

You should see `event:resync` arrive within a second. Press `Ctrl+C` to stop.

## Troubleshooting

* **`Could not transfer artifact dev.westyx.nexus:nexus-spring-boot-starter`** - your Maven settings haven't picked up the GitLab registry. Confirm the `<repositories>` block is in your `pom.xml`, not just `~/.m2/settings.xml`. Repository declarations in `pom.xml` are local to the project; in `settings.xml` they need a matching `<profile>` to be active.
* **`401 Unauthorized` from the registry** - the registry might be configured with an old path that's no longer valid. Switch to the numeric-ID variant above.
* **Bean not created at startup** - check that `nexus.base-url` and `nexus.api-key` are both set; the auto-configuration uses `@ConditionalOnProperty` on both.