# Beaver App Instance

This branch contains a standalone Beaver app instance for an external orchestrator to deploy.

The app instance is a single Docker image that runs:

- Next.js frontend
- FastAPI backend
- Nginx reverse proxy

Authentication is delegated to Keycloak. This repository does not maintain local user registration, passwords, per-user instance routing, or deployment orchestration.

## Runtime Contract

The external orchestrator is responsible for:

- Building or pulling the app image
- Providing a mounted Beaver home directory
- Providing `config.json`
- Choosing the public host and port
- Registering the public callback URL and post-logout callback URL in Keycloak
- Managing lifecycle, routing, TLS, and scaling

The app instance exposes container port `8080`:

```text
/      frontend
/api   backend API
/ws    backend WebSocket
```

## Keycloak

Default IdP settings:

```text
issuer:    https://keycloak.bwgdi.com/realms/beaver
client_id: beaver-agnet
```

For the current plain-IP deployment, register these values in Keycloak:

```text
web_origin:   http://172.19.0.245:18080
redirect_uri: http://172.19.0.245:18080/auth/callback
post_logout_redirect_uri: http://172.19.0.245:18080/logout/callback
```

The app validates Keycloak JWT issuer, signature, expiry, audience/azp, and nonce where applicable. The Keycloak `sub` claim is used as the application user ID.

## Build

```bash
cd app-instance
docker build -t beaver/app-instance:keycloak-login .
```

## Run Locally

```bash
cd app-instance
./run-standalone.sh --build --replace
```

The script prints the `web_origin`, `redirect_uri`, and `post_logout_redirect_uri` values that must be configured in Keycloak.

## Useful Paths

- `app-instance/` - app image, frontend, backend, runtime helper script, app tests
- `skills/` - reusable skill content retained for product/runtime packaging
- `agents/` - agent registry retained for runtime packaging
- `docs/` - product and architecture documentation
- `AGENTS.md` - local coding-agent instructions

See `app-instance/README.md` for the app-specific contract and environment variables.