Agent.md

# Agent.md

This file documents tricks, ongoing deployment best practices, and API configurations for deploying Matomo to Hugging Face Spaces.

## 1. Deployment Configuration

### Target Space
- **Profile:** `Leon4gr45`  
- **Space:** `matomo`  
- **Full Identifier:** `Leon4gr45/matomo`  
- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)

### Deployment Method
- **Docker SDK:** Configured with custom Dockerfile to containerize Matomo with light-weight PHP server capabilities.

### HF Token
- Loaded from environment variable `HF_TOKEN`.
- Never hardcode the token.

### Required Files
- `Dockerfile` (exposes port 7860 and serves the app)
- `README.md` with YAML frontmatter pointing to `sdk: docker` and `app_port: 7860`
- `.hfignore` to prevent uploading massive unnecessary logs or cache files
- `Agent.md` (this file)

---

## 2. API Exposure and Documentation

### Mandatory Endpoints
Every deployment exposes:

- **`/health`**  
  - **Method:** GET  
  - **Purpose:** Health check returning HTTP 200 when ready.  
  - **Response Example:**
    ```json
    {
      "status": "healthy",
      "app": "matomo"
    }
    ```

- **`/api-docs`**  
  - **Method:** GET  
  - **Purpose:** Documents all available API endpoints.  
  - **Response Example:**
    ```json
    {
      "openapi": "3.0.0",
      "info": {
        "title": "Matomo Hugging Face API",
        "version": "1.0.0"
      },
      "paths": {
        "/health": {
          "get": {
            "summary": "Health check",
            "responses": {
              "200": {
                "description": "App is healthy"
              }
            }
          }
        },
        "/api-docs": {
          "get": {
            "summary": "API Documentation",
            "responses": {
              "200": {
                "description": "API Schema"
              }
            }
          }
        }
      }
    }
    ```

---

## 3. Deployment Workflow

### Precondition
Ensure the space is empty of files not belonging to the project. Use the hub CLI to delete them first if any.

### Standard Deployment Command
To deploy any local modifications, execute:
```bash
hf upload Leon4gr45/matomo --repo-type=space
```

### Logs Monitoring
Build logs (SSE):
```bash
curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/matomo/logs/build"
```

Run logs (SSE):
```bash
curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/matomo/logs/run"
```