README.md

metadata

title: Spring Boot API
emoji: 🚀
colorFrom: green
colorTo: blue
sdk: docker
pinned: false

Spring Boot API on Hugging Face Spaces

A Spring Boot REST API deployed on Hugging Face Spaces using Docker.

Endpoints

Method	Endpoint	Description
GET	/api/health	Health check endpoint
GET	/api/hello?name={name}	Returns a greeting message
POST	/api/echo	Echoes back the JSON body

Example Usage

Health Check

curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/health

Hello Endpoint

curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/hello?name=Developer

Echo Endpoint

curl -X POST https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/echo \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from Hugging Face!"}'

Local Development

Prerequisites

• Java 21 (or use the Maven wrapper which handles this)
• Maven 3.9+ (optional, wrapper included)
• Docker (optional, for container testing)

Run with Maven

# On Linux/macOS
./mvnw spring-boot:run

# On Windows
mvnw.cmd spring-boot:run

The app will start on http://localhost:7860

Build and Run with Docker

# Build the image
docker build -t springboot-hf .

# Run the container
docker run -p 7860:7860 springboot-hf

Deploy to Hugging Face Spaces

Option 1: Push Entire Backend Folder as a Space

1. Create a new Space on Hugging Face

   • Select Docker as the SDK
   • Choose a name for your Space

2. Clone your new Space repository:

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

3. Copy the contents of this backend folder into the Space:

   # Copy all files from backend folder
   cp -r /path/to/backend/* .
   

4. Push to Hugging Face:

   git add .
   git commit -m "Initial Spring Boot deployment"
   git push
   

Option 2: Direct Git Push (if backend is standalone)

1. Add Hugging Face as a remote:

   cd backend
   git init  # if not already a git repo
   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   

2. Push to Hugging Face:

   git add .
   git commit -m "Deploy Spring Boot to HF Spaces"
   git push hf main
   

Important Notes for Hugging Face Spaces

• The app must run on port 7860 (already configured)
• The container runs as a non-root user (UID 1000) - this is required by HF Spaces
• Build times may vary; initial deployment can take a few minutes
• Check the Logs tab in your Space for debugging

Project Structure

backend/
├── src/
│   ├── main/
│   │   ├── java/com/backend/cs203/
│   │   │   └── Cs203Application.java    # Main entry point
│   │   └── resources/
│   │       └── application.properties   # App configuration
│   └── test/
├── pom.xml                              # Maven dependencies
├── Dockerfile                           # Multi-stage Docker build
└── README.md                            # This file

Tech Stack

• Java 21
• Spring Boot 4.0.1
• Maven (with wrapper)
• Docker (multi-stage build)