Updates README

## Getting Started

_This section will include installation and usage instructions once the codebase is published._

### Prerequisites

- **Python 3.12** or higher

- **Docker** and **Docker Compose**

- **Git**

### Installation

1. **Clone the repository:**

   ```bash

   git clone <repository-url>

   cd federation-manager

   ```

2. **Set up configuration:**

   ```bash

   cp src/conf/config.cfg.sample src/conf/config.cfg

   # Edit config.cfg with your specific settings

   ```

3. **Choose your deployment method:**

#### Option A: Docker Compose (Recommended)

   ```bash

   docker-compose up -d

   ```

   This starts:

   - Federation Manager (port 8990)

   - MongoDB (port 27017)

   - Keycloak (port 8080)

#### Option B: Local Development

   ```bash

   # Create virtual environment

   python -m venv venv

   source venv/bin/activate  # On Windows: venv\Scripts\activate

   # Install dependencies

   pip install -r requirements.txt

   # Start services

   cd src/

   python main.py

   ```

### Quick Start

1. **Access the API documentation:**

   - Swagger UI: `http://localhost:8990/ui/`

   - OpenAPI spec: `http://localhost:8990/openapi.yaml`

2. **Authentication:**

   - Keycloak Admin Console: `http://localhost:8080/admin/`

   - Default credentials: `admin/admin`

3. **Test the API:**

   ```bash

   curl -X GET http://localhost:8990/operatorplatform/federation/v1/health

   ```

## Testing

The Federation Manager includes a comprehensive test suite that validates the **dual role architecture**:

### Dual Role Testing

The Federation Manager operates in two modes:

- **Partner OP Mode**: Handles external requests (without `X-Internal` header)

- **Originating OP Mode**: Handles internal requests (with `X-Internal` and `X-Partner-API-Root` headers)

### Running Tests

1. **Run all tests:**

   ```bash

   cd src/

   python test/run_all_tests.py --verbose --coverage

   ```

2. **Test execution order:**

   - `federation_management`

   - `availability_zone_info_synchronization`

   - `artefact_management`

   - `application_onboarding_management`

   - `application_deployment_management`

3. **Coverage reports:**

   - Terminal output with coverage percentage

   - HTML report in `src/htmlcov/` directory

### Test Architecture

The test suite validates the complete stack:

```

API → Adapter → Client → External System

```

Each test runs for both operational modes, ensuring:

- ✅ Partner OP functionality (external federation partners)

- ✅ Originating OP functionality (internal service requests)

- ✅ End-to-end integration across all components

## Development

### CI/CD Pipeline

The project includes GitLab CI/CD configuration (`.gitlab-ci.yml`) with:

- **Build Stage**: Creates and pushes Docker images to GitLab Container Registry

For detailed CI/CD setup instructions, see [CI_CD_SETUP.md](CI_CD_SETUP.md).

### Docker Development

1. **Build the image:**

   ```bash

   docker build -t federation-manager .

   ```

2. **Run with custom configuration:**

   ```bash

   docker run -p 8989:8989 \

     -v ./src/conf/config.cfg:/usr/app/src/conf/config.cfg \

     federation-manager

   ```

3. **Development with docker-compose:**

   ```bash

   docker-compose -f docker-compose.yaml up --build

   ```

### Environment Variables

Key configuration options (set in `src/conf/config.cfg`):

- **Server**: Host, port, and API settings

- **Database**: MongoDB connection parameters

- **Keycloak**: Authentication service configuration

- **Logging**: Log levels and output configuration

## Deployment

### Production Deployment

1. **Using Docker Compose:**

   ```bash

   # Pull latest images

   docker-compose pull

   # Start services

   docker-compose up -d

   # Monitor logs

   docker-compose logs -f federation-manager

   ```

2. **Using Kubernetes:**

   ```bash

   kubectl apply -f src/deploy/

   ```

## API Documentation

### Swagger UI

Interactive API documentation is available at:

- **Local**: `http://localhost:8990/ui/`

- **API Spec**: `http://localhost:8990/openapi.yaml`

### Key Endpoints

1. **Federation Management**:

   - `POST /partner` - Create federation context

   - `GET /{federationContextId}` - Get federation details

   - `DELETE /{federationContextId}` - Terminate federation

2. **Zone Management**:

   - `POST /{federationContextId}/zones` - Register availability zones

   - `GET /{federationContextId}/zones` - List zones

3. **Application Management**:

   - `POST /{federationContextId}/artefact` - Upload application artefacts

   - `POST /{federationContextId}/applicationonboarding` - Onboard applications

   - `POST /{federationContextId}/applicationlcm` - Manage application lifecycle

### Authentication

All API endpoints require OAuth 2.0 Bearer tokens from Keycloak:

```bash

# Get access token

curl -X POST http://localhost:8080/realms/federation/protocol/openid-connect/token \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "grant_type=client_credentials" \

  -d "client_id=<client_id>" \

  -d "client_secret=<client_secret>"

# Use token in API calls

curl -X GET http://localhost:8990/operatorplatform/federation/v1/health \

  -H "Authorization: Bearer <access_token>"

```

## Contributing