Metadata-Version: 2.4
Name: pumpwood-deploy-frontend
Version: 0.0.1
Summary: Package to assist deploy Pumpwood Frontend components on K8s
License: BSD-3-Clause License
License-File: LICENSE
Author: André Andrade Baceti
Author-email: a.baceti@murabei.com
Requires-Python: >=3.6
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: pumpwood-deploy
Project-URL: Homepage, https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-frontend
Description-Content-Type: text/markdown

# pumpwood-deploy-frontend

Satellite deploy package for the **Pumpwood Frontend** (React) microservice
on Kubernetes. It generates manifests for the frontend secrets and the
``pumpwood-frontend-react`` Deployment/Service — then hands them to
[`pumpwood-deploy`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy)
for apply.

Developed by [Murabei Data Science](https://murabei.com). BSD-3-Clause.

<p align="center" width="60%">
  <img src="static_doc/sitelogo-horizontal.png" /> <br>

  <a href="https://en.wikipedia.org/wiki/Cecropia">
    Pumpwood is a native Brazilian tree
  </a> with a symbiotic relation to ants (Murabei)
</p>

---

## What it deploys

| Manifest | Kubernetes resources |
|----------|----------------------|
| `pumpwood_frontend__secrets` | Secret `pumpwood-frontend-react` |
| `pumpwood_frontend__deploy` | Deployment + Service `pumpwood-frontend-react` |

The React app is the main Pumpwood UI. It uses the public gateway URL for
browser API calls and registers with the platform via the
``microservice--frontend`` service user.

```mermaid
flowchart LR
    subgraph pkg [pumpwood-deploy-frontend]
        A[PumpwoodFrontEndMicroservice]
    end
    subgraph core [pumpwood-deploy]
        B[DeployPumpWood]
    end
    subgraph cluster [Cluster]
        S[pumpwood-frontend-react Secret]
        APP[pumpwood-frontend-react]
        LB[load-balancer / Kong]
    end
    A --> B
    B --> S
    B --> APP
    APP --> LB
```

---

## Prerequisites

This package does **not** stand alone. Before frontend pods can start,
the cluster should already provide:

| Resource | Provided by |
|----------|-------------|
| API gateway / ingress | [`pumpwood-deploy-ingress-api-gateway`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-ingress-api-gateway) or AWS ALB |
| Internal REST proxy | Kong ``load-balancer`` service (port 8000) |
| Auth (typical) | [`pumpwood-deploy-auth`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-auth) |

The pod sets:

- ``NEXT_PUBLIC_APP_API_URL`` from ``gateway_public_ip`` (public URL)
- ``API_URL`` to ``http://load-balancer:8000/rest`` (in-cluster Kong)

No Postgres or storage ConfigMap is required for the frontend pod.

---

## Installation

```bash
pip install pumpwood-deploy-frontend
```

Requires `pumpwood-deploy`.

---

## Quick start

```python
import os
import simplejson as json
from dotenv import load_dotenv
from pumpwood_deploy.deploy import DeployPumpWood
from pumpwood_deploy_frontend import PumpwoodFrontEndMicroservice

with open("secrets/production.json", "r") as file:
    secrets = json.loads(file.read())
load_dotenv()

deploy = DeployPumpWood(
    model_user_password=secrets["microservices--model"],
    rabbitmq_secret=secrets["rabbitmq_secret"],
    hash_salt=secrets["hash_salt"],
    k8_provider="aws",
    k8_deploy_args={
        "region": "us-east-1",
        "cluster_name": "my-cluster",
    },
    k8_namespace="pumpwood",
)

deploy.add_microservice(
    PumpwoodFrontEndMicroservice(
        version=os.getenv("PUMPWOOD_FRONTEND"),
        gateway_public_ip="https://pumpwood.example.com",
        repository="my-registry.example.com",
        microservice_password=secrets["microservice--frontend"],
        debug="FALSE",
    ))

deploy.create_deploy_files()
deploy.deploy_microservices()
```

### Environment variables

```bash
PUMPWOOD_FRONTEND=2.1.0
```

If the rendered manifest matches what is already on the cluster, `kubectl
apply` produces no changes — safe for rolling image updates.

---

## Configuration reference

### Required

| Parameter | Description |
|-----------|-------------|
| `version` | Image tag for `pumpwood-frontend-react` |
| `gateway_public_ip` | Public URL or IP for `NEXT_PUBLIC_APP_API_URL` |

### Optional

| Parameter | Default | Description |
|-----------|---------|-------------|
| `microservice_password` | `microservice--frontend` | Service user password |
| `debug` | `FALSE` | Debug flag (`TRUE` / `FALSE`) |
| `repository` | GCR default | Docker registry |

---

## Migration note

Older deploy scripts imported from the monolithic package:

```python
# Before
from pumpwood_deploy.microservices.frontend.deploy import (
    PumpwoodFrontEndMicroservice)

# After
from pumpwood_deploy_frontend import PumpwoodFrontEndMicroservice
```

---

## Related packages

| Package | Role |
|---------|------|
| [`pumpwood-deploy`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy) | Orchestrator, Kong, RabbitMQ |
| [`pumpwood-deploy-auth`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-auth) | Authorization microservice |
| [`pumpwood-deploy-ingress-api-gateway`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-ingress-api-gateway) | NGINX API gateway |

---

## Development

```bash
pip install -e ../pumpwood-deploy
pip install -e .

PYTHONPATH="src:../pumpwood-deploy/src" \
  python3 -m unittest discover \
  -s src/pumpwood_deploy_frontend/tests -p "test_*.py" -v

ruff check src/
```

---

## License

BSD-3-Clause — see [LICENSE](LICENSE).

