> ## Documentation Index
> Fetch the complete documentation index at: https://ritika-fa61c43f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate Your Submission Before Submitting to OpenEnv

> Use the validate-submission.sh script to run the 3-step pre-submission check: HuggingFace Space ping, Docker build, and openenv validate.

Before submitting your CRM Data Pipeline environment to the OpenEnv platform, you must verify three things: your HuggingFace Space is live and responding to `/reset`, your Dockerfile produces a valid container image, and your `openenv.yaml` passes the OpenEnv schema validator. The `scripts/validate-submission.sh` script automates all three checks in sequence and exits with a clear pass/fail for each. Running it takes under 10 minutes and catches the vast majority of submission problems before they reach the platform.

## Prerequisites

The script depends on three external tools. Install them before running:

| Tool | Install | Why it is needed |
| - | - | - |
| **Docker** | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) | Builds the container image to verify the Dockerfile is valid |
| **openenv-core** | `pip install openenv-core` | Provides the `openenv validate` command that checks `openenv.yaml` |
| **curl** | Pre-installed on macOS and most Linux distributions | Sends the HTTP POST to your HuggingFace Space's `/reset` endpoint |

Verify all three are available before running the script:

```bash theme={null}
docker --version        # Docker version 24.x or later
openenv --version       # openenv-core 0.x
curl --version          # curl 7.x or later
```

## Usage

**1. Make the script executable**

If you cloned the repository, give the script execute permission first:

```bash theme={null}
chmod +x scripts/validate-submission.sh
```

**2. Run the validator**

Pass your HuggingFace Space URL as the first argument. The second argument is the path to your repo directory (defaults to `.` if omitted):

```bash theme={null}
# Validate against the current directory
./scripts/validate-submission.sh https://my-team.hf.space

# Validate a specific repo directory
./scripts/validate-submission.sh https://my-team.hf.space ./my-repo

# Run directly from GitHub without downloading (pipe into bash)
curl -fsSL https://raw.githubusercontent.com/GaurRitika/CRM-Datapipeline-env/main/scripts/validate-submission.sh \
  | bash -s -- https://my-team.hf.space .
```

> [!WARNING]
>
> When piping directly from GitHub with `| bash -s --`, the script runs in your current shell context. Ensure you are in your repo directory or pass the explicit repo path as the second argument — the script needs a `Dockerfile` or `server/Dockerfile` to exist within that directory.

## The Three Validation Steps

**1. Ping HF Space — verify the server is live**

The script sends a `POST` request to `<your-hf-space-url>/reset` with an empty JSON body and a 30-second timeout:

```bash theme={null}
curl -s -o /tmp/validate-curl-XXXXX -w "%{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://my-team.hf.space/reset" \
  --max-time 30
```

The script expects HTTP `200`. Any other outcome fails the check:

| HTTP code | Outcome | Meaning |
| - | - | - |
| `200` | ✅ PASSED | Space is live and the FastAPI `/reset` route is working |
| `000` | ❌ FAILED | Connection refused, DNS failure, or 30-second timeout |
| `4xx` / `5xx` | ❌ FAILED | Space is reachable but `/reset` is returning an error |

This step failing immediately halts the script — there is no point testing Docker if the deployed server is broken.

**2. Docker build — verify the container builds**

The script locates your `Dockerfile` (checking the repo root first, then `server/Dockerfile`) and runs `docker build` with a **600-second timeout**:

```bash theme={null}
docker build /path/to/repo
```

If the build succeeds, the check passes. If the build fails for any reason — missing base image, dependency resolution error, syntax error in `Dockerfile` — the script prints the last 20 lines of build output and halts.

The 600-second timeout is intentional: pulling a Python 3.12 base image and installing all dependencies can take several minutes on a cold Docker cache. The script uses `timeout` (Linux) or `gtimeout` (macOS via Homebrew `coreutils`) for portability, falling back to a background-process watchdog if neither is available.

**3. openenv validate — verify the manifest**

The script changes into the repo directory and runs:

```bash theme={null}
cd /path/to/repo && openenv validate
```

This command parses `openenv.yaml` and checks it against the OpenEnv specification schema. A passing result looks like:

```text theme={null}
openenv.yaml is valid ✓
```

A failure prints the exact schema violation. Common issues include missing required fields (`tasks`, `app_port`, `reset_route`) or invalid task IDs.

## Expected Success Output

A fully passing validation run produces:

```text theme={null}
========================================
  OpenEnv Submission Validator
========================================
[10:32:01] Repo:     /home/user/crm-pipeline-env
[10:32:01] Ping URL: https://my-team.hf.space

[10:32:01] Step 1/3: Pinging HF Space (https://my-team.hf.space/reset) ...
[10:32:02] PASSED -- HF Space is live and responds to /reset
[10:32:02] Step 2/3: Running docker build ...
[10:34:18] PASSED -- Docker build succeeded
[10:34:18] Step 3/3: Running openenv validate ...
[10:34:19] PASSED -- openenv validate passed

========================================
  All 3/3 checks passed!
  Your submission is ready to submit.
========================================
```

The script exits with code `0` on success and code `1` on any failure.

## Troubleshooting Failures

> [accordion] Step 1 fails — HTTP 000 (connection failed or timed out)
>
> HTTP `000` means curl could not establish a TCP connection at all. This is not an application error — the request never reached your server.
>
> **Possible causes:**
>
> * Your HuggingFace Space is sleeping (free-tier Spaces go idle after inactivity)
> * The URL is wrong — double-check for typos (`hf.space` not `hf.spaces`)
> * Your Space is still building or deploying — check the Space's build logs at `https://huggingface.co/spaces/your-org/your-space`
> * Your local network is blocking outbound HTTPS (corporate firewall)
>
> **Debug command:**
>
> ```bash theme={null}
> curl -v -X POST https://my-team.hf.space/reset \
>   -H "Content-Type: application/json" \
>   -d '{}' --max-time 30
> ```
>
> Open the Space URL in a browser first to wake it up if it is sleeping, then re-run the validator.

> [accordion] Step 1 fails — non-200 response (4xx or 5xx)
>
> The Space is reachable but the `/reset` endpoint is returning an error. This means the FastAPI application is running but the route is broken.
>
> **Common causes:**
>
> * `TASK_ID` environment variable is not set in the HF Space secrets — the server initialises but `/reset` fails because it cannot determine which task to load
> * Python import error in `server/app.py` — check the Space's runtime logs
> * The app is listening on a different port than `8080`
>
> **Fix `TASK_ID` in HF Space:**
>
> 1. Go to your Space → Settings → Repository secrets
> 2. Add `TASK_ID` with value `t1` (or `t2`, `t3`)
> 3. Restart the Space
>
> **Verify the port:**
> Your `openenv.yaml` and HuggingFace `README.md` (the Space card) must both specify `app_port: 8080`. The CRM Pipeline Dockerfile exposes port `8080` by default.

> [accordion] Step 2 fails — Docker build error
>
> The script prints the last 20 lines of Docker build output when the build fails. Read these carefully — they almost always identify the exact line in the Dockerfile or the Python package that failed to install.
>
> **Common causes and fixes:**
>
> | Symptom in build output | Fix |
> | - | - |
> | `Could not find a version that satisfies the requirement` | Pin the package version in `requirements.txt` or `pyproject.toml` |
> | `COPY failed: file not found` | The file path in `COPY` is wrong — paths are relative to the Docker build context |
> | `PermissionError` during install | Add `--user` to pip or ensure the Dockerfile uses the correct UID |
> | `No space left on device` | Free up Docker disk space: `docker system prune -af` |
>
> **Test the build locally in verbose mode:**
>
> ```bash theme={null}
> docker build . --progress=plain 2>&1 | tail -40
> ```
>
> The `--progress=plain` flag disables the compact build UI and shows every layer's output, making it easier to spot the failing command.

> [accordion] Step 3 fails — openenv validate error
>
> `openenv validate` parses `openenv.yaml` against the OpenEnv specification. Common failure messages and fixes:
>
> **`Missing required field: tasks`**
> Your `openenv.yaml` does not define the `tasks` block. Add it:
>
> ```yaml theme={null}
> tasks:
>   - id: t1
>     name: "Web Forms Normalization"
>   - id: t2
>     name: "Legacy DB Deduplication"
>   - id: t3
>     name: "3-Way Enterprise Merge"
> ```
>
> **`Invalid app_port: must be an integer`**
>
> ```yaml theme={null}
> app_port: 8080   # correct — no quotes
> # NOT: app_port: "8080"
> ```
>
> **`reset_route not found`**
>
> ```yaml theme={null}
> reset_route: /reset   # must start with /
> step_route: /step
> ```
>
> **`openenv: command not found`**
> Install the CLI: `pip install openenv-core`. If you are inside a virtual environment, make sure it is activated.
>
> To run `openenv validate` manually and see the full error output:
>
> ```bash theme={null}
> cd /path/to/your-repo
> openenv validate
> ```

## HuggingFace Space Deployment Notes

The CRM Data Pipeline Environment is designed to run on HuggingFace Spaces. Several aspects of the Dockerfile and configuration are specifically tuned for the HF Spaces runtime:

**Port 8080**: HF Spaces routes external traffic to the port declared in `app_port` in the Space card (the `README.md` frontmatter). The Dockerfile exposes `8080` and Uvicorn binds to `0.0.0.0:8080`. Do not change this port without updating both the Dockerfile `EXPOSE` directive and the Space card.

**Non-root user (UID 1000)**: HuggingFace Spaces enforces that containers run as a non-root user. The Dockerfile creates a user with UID `1000` and switches to it before the `CMD`. If you customise the Dockerfile, ensure your `RUN` commands that install packages happen before the `USER 1000` instruction.

**TASK\_ID as a Space secret**: The `TASK_ID` environment variable controls which of the three tasks the server loads on `/reset`. Set it as a HuggingFace Space environment secret rather than hardcoding it in the Dockerfile:

```
Space → Settings → Variables and secrets → New secret
Name:  TASK_ID
Value: t1
```

For a Space that supports all three tasks, you can also leave `TASK_ID` unset and have the client pass it via the request body — check the server's `/reset` route for the exact parameter name.

**Space SDK**: The `README.md` frontmatter must declare `sdk: docker` for the Space to use your Dockerfile:

```yaml theme={null}
---
title: CRM Data Pipeline
emoji: ⚙️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8080
pinned: false
---
```

> [!TIP]
>
> After deploying your Space, wait 2–3 minutes for the Docker image to build and the container to start before running the validator. You can monitor the build in real time at `https://huggingface.co/spaces/your-org/your-space` → the **Logs** tab.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.