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:

    {
      "status": "healthy",
      "app": "matomo"
    }
    

• /api-docs

  • Method: GET
  • Purpose: Documents all available API endpoints.
  • Response Example:

    {
      "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:

hf upload Leon4gr45/matomo --repo-type=space

Logs Monitoring

Build logs (SSE):

curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/matomo/logs/build"

Run logs (SSE):

curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/matomo/logs/run"