Metadata-Version: 2.4
Name: bodc-seam
Version: 0.0.2
Summary: API service to perform data mutation and format conversion.
License-File: LICENSE
Author: British Oceanographic Data Centre (BODC)
Author-email: enquiries@bodc.ac.uk
Requires-Python: >=3.14,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: bodc-transfer (>=4.6.0,<5.0.0)
Requires-Dist: fastapi (>=0.135.3,<0.136.0)
Requires-Dist: importlib-metadata (==7.2.1)
Requires-Dist: pandas (>=2.3.3,<3.0.0)
Requires-Dist: poetry-dynamic-versioning (>=1.1.0,<2.0.0)
Requires-Dist: uvicorn (>=0.44.0,<0.45.0)
Project-URL: Repository, https://gitlab.com/nocacuk/seai/bodc/seam.git
Description-Content-Type: text/markdown

SEAM
====

API service to perform data mutation.

The purpose of this repo is to facilitate the API service to perform mutation on data and do required processing.
It provides endpoint to perform mutation on data passed.

---

## Documentation

PROVIDE A LINK TO THE DOCUMENTATION HERE

---

## Development

PROVIDE A LINK TO ANY DEVELOPMENT INFORMATION HERE

---

## Running Locally

### Installation and Setup

1. **Install/Update Dependencies**
    ```bash
    poetry install
    ```
    or to update existing dependencies:
    ```bash
    poetry update
    ```

2. **Run the Application**
    ```bash
    poetry run uvicorn seam_api.app:app --reload
    ```
    or by poetry task : 
    ```bash
    poetry run task start-app
    ```
    The API will be available at `http://localhost:8000`


### Running app using Container

1. **Build the Image**
    ```bash
    docker build -f Containerfile -t bodc-seam:latest .
    ```

2. **Run the Container**
    ```bash
    docker run -p 8000:8000 bodc-seam:latest
    ```

3. **Verify the Application**

    Test the hello-world endpoint:
    ```bash
    curl http://localhost:8000/api/hello-world
    ```
    Or visit `http://localhost:8000/api/hello-world` in your browser

    You should see:
    ```json
    {"message":"Hello, World!"}
    ```

### Running app on Kubernetes

#### Prerequisites

- Local kubernetes cluster is running and accessible
- `kubectl` is installed and configured
- Helm is installed (for deployment management)

#### Deployment Steps

1. **Deploy seam-api using Helm**
    ```bash
    helm install seam ./helm/ -n bodc --create-namespace
    ```
    Or to upgrade an existing deployment:
    ```bash
    helm upgrade seam ./helm/ -n bodc
    ```

2. **Check Deployment Status**
    ```bash
    kubectl get deployments -n bodc
    ```
    You should see the seam deployment listed with the desired and ready replicas.

3. **Check if Pods are Running**
    ```bash
    kubectl get pods -n bodc
    ```
    Verify that the seam pods are in the `Running` state. You can also get more detailed information with:
    ```bash
    kubectl describe pod <pod-name> -n bodc
    ```

4. **Port Forwarding (in a separate terminal)**
    ```bash
    kubectl port-forward svc/seam 8000:80 -n bodc
    ```
    This forwards local port 8000 to the service port 80. The command will display:
    ```
    Forwarding from 127.0.0.1:8000 -> 8000
    Forwarding from [::1]:8000 -> 8000
    ```

5. **Verify the Application is Running**
    In another terminal, test the hello-world endpoint:
    ```bash
    curl http://localhost:8000/api/hello-world
    ```
    You should see:
    ```json
    {"message":"Hello, World!"}
    ```

#### Additional Kubernetes Commands

- **View Logs**
    ```bash
    kubectl logs -f deployment/seam -n bodc
    ```

- **Access API Documentation**
    After port-forwarding, visit `http://localhost:8000/docs` in your browser for Swagger UI

- **Delete the Deployment**
    ```bash
    helm uninstall seam -n bodc
    ```

- **Check Service**
    ```bash
    kubectl get svc -n bodc
    ```

### Development Notes

- The interactive API documentation is available at `http://localhost:8000/docs` (Swagger UI)

---

## Package Installation

Poetry is used to manage the building of this package (.whl & .tar.gz files), and Poetry can be used to install the package
dependencies for you. The dependencies are in the pyproject.toml file, to install them run:

- `poetry install`

To update your installed dependencies, run:

- `poetry update`

To install a new dependency and add it to the projects pyproject.toml file, run:

- `poetry add package_name`

To view your projects dependencies, run:

- `poetry show`

To view the specific dependencies for a particular package, run:

- `poetry show package_name`

---

## Code Testing

Run the following commands to test and validate your code:

- `poetry run task tests` - Run all unit tests with coverage report
- `poetry run task lint` - Lint code with ruff
- `poetry run task lint-fix` - Fix linting issues with ruff
- `poetry run task format` - Auto-format code with ruff
- `poetry run task format-check` - Check code formatting without fixing
- `poetry run task build` - Build the package

---

## Releasing a new version

Versions of the package are denoted by tags in git.
To create a new tag, you can use the GitLab UI by following these steps:

1. Go the repository tags page
2. Click **New tag**
3. Enter the tag name. There are four options for the format for this tag:

   - Alpha release (development release): `vX.Y.ZaW`, for example `v1.0.2-dev3`
   - Release candidate (test release): `vX.Y.ZrcW`, for example `v1.10.9-tst2`
   - Full release (production release): `vX.Y.Z`, for example `v3.0.11`

4. Select the branch to create the tag from, this will normally be `main`
5. Enter a message for the tag, this is required for the CI/CD pipeline to function correctly
6. Click **Create tag**
7. This will trigger a CI/CD pipeline

