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

# WebAdmin Deployment

WebAdmin supports two deployment models: embedded in **your Spring Boot application** via the starter, or as a prebuilt **WAR** for traditional servlet containers.

## Spring Boot application (JAR)

Add the [starter](/webadmin/quick-start) to your own Spring Boot application, then build and run your application as usual:

```bash theme={null}
mvn clean package
java -jar target/<your-app>.jar
```

WebAdmin is served at `http://localhost:8080/webadmin` (or your configured `base-path`). In this model a single application contains both the WebAdmin UI and the engine REST endpoints, so REST security is typically left enabled (`disable-rest-security: false`).

## WAR for Tomcat / WildFly

For traditional servlet containers, **download the prebuilt `aseeflow-webadmin-war`** from the ASEE Flow WebAdmin customer repository — you do not build it from source. Once you have access (see [Accessing artifacts](/introduction/downloading-aseeflow#accessing-artifacts)), download the `.war`:

```bash theme={null}
curl -u YOUR_USERNAME:YOUR_PASSWORD -O <asee-webadmin-repository-url>/org/aseeflow/webadmin/aseeflow-webadmin-war/1.0.2/aseeflow-webadmin-war-1.0.2.war
```

Since 1.0.2, WebAdmin has the same version number as the platform it belongs to.

The **WAR filename determines the context path**, so rename it before deploying (`webadmin.war` → `/webadmin`) and drop it into your container's deploy directory (Tomcat `webapps/`, WildFly `standalone/deployments/`). The Tomcat and WildFly distributions already contain it, deployed as `webadmin`.

### Configuration shipped in the WAR

The WAR ships with these defaults, suited to running alongside a separate engine REST WAR:

```yaml theme={null}
aseeflow:
  webadmin:
    authentication: form
    base-path: ""                       # container provides the context path
    disable-rest-security: true
    engine-rest-proxy-enabled: false    # enable once the Engine REST WAR is protected
    engine-rest-client-url: engine-rest # UI calls /engine-rest directly
    show-swagger: false
    show-legacy-apps: false
```

Why these differ from a Spring Boot app:

| Property | WAR default | Why |
| - | - | - |
| `base-path` | `""` | The container sets the context path from the WAR name; with an empty base path the UI can call `/engine-rest` directly. |
| `disable-rest-security` | `true` | Engine REST is a **separate WAR** with its own security; the WebAdmin WAR must not try to secure endpoints it doesn't contain. |
| `engine-rest-proxy-enabled` | `false` | Fits the default, unprotected Engine REST WAR. Once you protect that WAR, turn the proxy on — in `basic` and in the OIDC modes alike; see [Production hardening](/installation/production-hardening#tomcat-and-wildfly). |
| `show-swagger` | `false` | The link points to `/swagger/index.html`, which the Tomcat and WildFly distributions don't serve. |
| `show-legacy-apps` | `false` | The links point to the legacy web apps — Cockpit, Tasklist and Admin — at `/aseeflow`, a separate WAR with its own login. The distributions deploy it there; in your own container it may be missing. Set `true` where it is deployed. |

### Overriding the configuration

Because you don't rebuild the WAR, override these `aseeflow.webadmin.*` properties from **outside** the artifact using any standard Spring Boot mechanism — there are no profiles to switch, only properties to set:

* **Environment variables** (relaxed binding — uppercase, dots/dashes become underscores):

  ```bash theme={null}
  ASEEFLOW_WEBADMIN_AUTHENTICATION=oauth2
  ASEEFLOW_WEBADMIN_ENGINE_REST_PROXY_ENABLED=true
  ```

* **JVM system properties**, e.g. in Tomcat's `setenv.sh` or WildFly's `standalone.conf`:

  ```bash theme={null}
  -Daseeflow.webadmin.authentication=oauth2
  ```

* **An external `application.yml`**, in a directory you give with a JVM system property:

  ```bash theme={null}
  -Dspring.config.additional-location=file:/opt/aseeflow/webadmin-config/
  ```

  The trailing `/` marks a directory, and the file in it must be named `application.yml`. [Production hardening](/installation/production-hardening#single-sign-on-instead-of-http-basic) uses this for WebAdmin's single sign-on settings.

### Two WARs, two security configs

A traditional deployment has a **WebAdmin WAR** (at `/webadmin`) and a separate **Engine REST WAR** (at `/engine-rest`). Each manages its own security, so `disable-rest-security: true` tells WebAdmin not to secure `/engine-rest/**` — those endpoints live in the other WAR. Setting it to `false` would make WebAdmin try to secure endpoints that aren't part of its deployment, causing conflicts. Disabling REST security is safe **only** once the Engine REST WAR secures itself — and in the Tomcat and WildFly distributions it ships with its authentication filter commented out, so as shipped WebAdmin's login protects its pages while the data behind them is open. [Production hardening](/installation/production-hardening#tomcat-and-wildfly) shows how to turn the filter on and which WebAdmin login mode goes with it. In a standalone Spring Boot app disabling REST security leaves the engine open; see [Never leave the engine REST API unprotected](/webadmin/security#never-leave-the-engine-rest-api-unprotected).

### Enabling the proxy

When REST and WebAdmin are separate WARs and the Engine REST WAR is protected, enable the proxy. In `basic` mode it forwards the browser's credentials to the engine REST API; in `oauth2` it forwards the user's access token, and renews it when it expires. The WAR doesn't support `keycloak` mode — it needs the Keycloak identity plugin, which the WAR doesn't include — so use `oauth2` with Keycloak too. Without the proxy, the browser calls `/engine-rest` directly and asks for a second login there. `form` mode has no credential the proxy could forward, so it doesn't work with a protected Engine REST WAR. Set these alongside your auth configuration (shown here as properties):

```yaml theme={null}
aseeflow:
  webadmin:
    authentication: basic               # or oauth2
    base-path: ""
    disable-rest-security: true
    engine-rest-proxy-enabled: true     # enable the proxy
    engine-rest-client-url: api/engine-rest   # UI calls the proxy
    engine-rest-server-url: /engine-rest      # proxy forwards here
```

## JAR vs. WAR at a glance

| Aspect | Spring Boot application | WAR |
| - | - | - |
| Source | Your application (with the starter) | Prebuilt artifact from the ASEE Flow repository |
| Context path | `aseeflow.webadmin.base-path` | Container (WAR filename) |
| Configuration | `application.yaml` in your app | External env vars / system properties / external `application.yml` |
| REST security | Usually enabled | Usually disabled — Engine REST WAR secures itself |
| Topology | Single application | WebAdmin WAR + Engine REST WAR |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.