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](https://huggingface.co/join))

## 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

```bash
# 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

```bash
# 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](https://huggingface.co/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:
   ```bash
   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:
   ```bash
   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:

```bash
# 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:

```yaml
---
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](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [Next.js Docker Documentation](https://nextjs.org/docs/app/building-your-application/deploying#docker-image)
- [Hugging Face Spaces Examples](https://huggingface.co/spaces)