Deploy To Hf Spaces

Deploy to Hugging Face Spaces

Guide for deploying and updating a research article on Hugging Face Spaces.

Prerequisites

• A Hugging Face account with an SSH key configured (git@hf.co)
• Or HTTPS access with huggingface-cli login

First deployment

1. Create the Space

Via CLI:

huggingface-cli repo create <username>/<space-name> --repo-type space --space_sdk docker

Or manually at https://huggingface.co/new-space (select Docker SDK).

2. Add the remote

git remote add space git@hf.co:spaces/<username>/<space-name>

3. Push

git push space main

The Space will build automatically using the included Dockerfile and nginx.conf. Build typically takes 3-5 minutes.

Updating an existing Space

git add -A
git commit -m "feat: describe your changes"
git push space main

Force push (when needed)

If the Space history has diverged (e.g., after a factory reset or manual edit on HF):

git push space main --force

Verifying deployment

1. Go to https://huggingface.co/spaces/<username>/<space-name>
2. Check the Factory tab for build logs
3. The build is complete when status shows "Running"
4. If the page looks stale, append ?v=<timestamp> to the URL to bypass CDN cache

Cache busting

Hugging Face Spaces aggressively cache static assets. If changes don't appear after a successful build:

1. Check that the CSS bundle hash has changed (view page source, look for /_astro/*.css)
2. If unchanged, the build used a stale cache - push an empty commit to force rebuild:

   git commit --allow-empty -m "chore: trigger rebuild"
   git push space main
   

3. Wait for the new build to complete before checking again

README tag (critical)

The README.md YAML frontmatter must contain:

tags:
  - research-article-template

NEVER remove this tag. It is used by the Research Article Gallery to list the article. Without it, the Space becomes invisible in the gallery.

README frontmatter reference

---
title: "Article Title"
emoji: 📝
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 8080
header: mini
pinned: false
tags:
  - research-article-template
---

Troubleshooting