DEPLOYMENT.md

Deployment Guide for Hugging Face Spaces

This guide explains how to deploy the Datasets Navigator app to Hugging Face Spaces using Docker.

Prerequisites

• Docker installed and running (for local testing)
• Hugging Face account (sign up here)

Files Created for Docker Deployment

• Dockerfile - Multi-stage Docker build configuration
• .dockerignore - Excludes unnecessary files from Docker build
• docker-compose.yml - For local testing
• README.md - Updated with HF Spaces metadata
• next.config.mjs - Updated with output: 'standalone' for Docker

Local Testing (Optional)

Before deploying to Hugging Face Spaces, you can test the Docker build locally:

Option 1: Using Docker directly

# Build the image
docker build -t datasets-navigator .

# Run the container
docker run -p 7860:7860 datasets-navigator

# Access the app at http://localhost:7860

Option 2: Using Docker Compose

# Build and run
docker-compose up --build

# Access the app at http://localhost:7860

# Stop with Ctrl+C, or in detached mode:
docker-compose down

Deploying to Hugging Face Spaces

Method 1: Via Hugging Face Web Interface

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: Choose a name (e.g., datasets-navigator)
   • License: Select appropriate license
   • SDK: Select "Docker"
   • Hardware: Start with "CPU basic" (can upgrade later)
4. Clone the Space repository:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   

5. Copy all files from datasets_navigator_app/ to the cloned repository
6. Push to Hugging Face:

   cd YOUR_SPACE_NAME
   git add .
   git commit -m "Initial commit: Datasets Navigator app"
   git push
   

Method 2: Push Existing Repository

If you already have a Space created:

# Add Hugging Face as a remote
cd datasets_navigator_app
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# Push to Hugging Face
git add .
git commit -m "Deploy Datasets Navigator to HF Spaces"
git push hf main

Configuration

The app is configured via README.md frontmatter:

---
title: Prova
emoji: 🍽️
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
---

You can customize:

• title: The Space's display name
• emoji: Icon shown in the Space
• colorFrom / colorTo: Gradient colors for the Space card
• app_port: Must match the port in Dockerfile (7860)

Environment Variables & Secrets

If your app needs environment variables or secrets:

1. Go to your Space settings on Hugging Face
2. Navigate to "Variables and secrets"
3. Add variables (public) or secrets (private)

They will be available as environment variables in the Docker container.

Troubleshooting

Build Fails

• Check the build logs in the Space's "Logs" tab
• Verify all dependencies are in package.json
• Ensure package-lock.json is committed

App Won't Start

• Verify the app listens on 0.0.0.0:7860
• Check the Docker logs for errors
• Ensure user permissions are correct (user ID 1000)

Port Issues

• The app MUST listen on the port specified in app_port (7860)
• Verify ENV PORT=7860 in Dockerfile
• Next.js reads the PORT environment variable automatically

Upgrading Space Hardware

If you need more resources:

1. Go to Space settings
2. Select "Hardware" tab
3. Choose upgrade (CPU/GPU options available)
4. Confirm the upgrade

Note: GPU and upgraded hardware have associated costs.

References

• HF Spaces Docker Documentation
• Next.js Docker Documentation
• Hugging Face Spaces Examples