/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:
Verify all three are available before running the script:
Usage
1
Make the script executable
If you cloned the repository, give the script execute permission first:
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):The Three Validation Steps
1
Ping HF Space — verify the server is live
The script sends a The script expects HTTP
POST request to <your-hf-space-url>/reset with an empty JSON body and a 30-second timeout:200. Any other outcome fails the check: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 If the build succeeds, the check passes. If the build fails for any reason — missing base image, dependency resolution error, syntax error in
Dockerfile (checking the repo root first, then server/Dockerfile) and runs docker build with a 600-second timeout: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:This command parses A failure prints the exact schema violation. Common issues include missing required fields (
openenv.yaml and checks it against the OpenEnv specification schema. A passing result looks like:tasks, app_port, reset_route) or invalid task IDs.Expected Success Output
A fully passing validation run produces:0 on success and code 1 on any failure.
Troubleshooting Failures
Step 1 fails — HTTP 000 (connection failed or timed out)
Step 1 fails — HTTP 000 (connection failed or timed out)
HTTP Open the Space URL in a browser first to wake it up if it is sleeping, then re-run the validator.
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.spacenothf.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)
Step 1 fails — non-200 response (4xx or 5xx)
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_IDenvironment variable is not set in the HF Space secrets — the server initialises but/resetfails 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
TASK_ID in HF Space:- Go to your Space → Settings → Repository secrets
- Add
TASK_IDwith valuet1(ort2,t3) - Restart the Space
openenv.yaml and HuggingFace README.md (the Space card) must both specify app_port: 8080. The CRM Pipeline Dockerfile exposes port 8080 by default.Step 2 fails — Docker build error
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:The
Test the build locally in verbose mode:
--progress=plain flag disables the compact build UI and shows every layer’s output, making it easier to spot the failing command.Step 3 fails — openenv validate error
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:Invalid app_port: must be an integerreset_route not foundopenenv: 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: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 inapp_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:
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: