Preparation
Before you begin, make sure you have completed the following preparations:
- A Hugging Face account.
- Your Komari Agent’s
-eand-tparameters. - Create space‑Docker‑Black.
Create Project Files
First, create three files:
- Dockerfile: defines how to build the container image.
- start.sh: script executed when the container starts.
- README.md: configuration file for Hugging Face Spaces.
Write the Startup Script
This script performs two tasks simultaneously: it launches the Komari Agent in the background, then starts a simple Python web server in the foreground. The web server is the key to “tricking” Hugging Face Spaces; it continuously responds to health‑check requests, keeping the container in a running state.
Create a start.sh file in the project folder and copy the following content:
#!/bin/bash
# Use Hugging Face Spaces environment variables to start Komari Agent
# Note: Enclose parameters in double quotes to prevent special characters in values
/usr/local/bin/komari-agent -e “$KOMARI_ENDPOINT” -t “$KOMARI_TOKEN” &
# Start a simple Python HTTP server
# Listen on port 7860 and keep running in the foreground
python3 -m http.server 7860
Create the README.md File
README.md is the key for Hugging Face Spaces to recognize and configure your Docker app. It contains the deployment type and port settings.
Create a README.md file in the project folder and copy the following content:
-–
title: Komari Agent
emoji: 🚀
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
-–
# Komari Agent Docker Deployment
This is a simple Docker deployment for Komari Agent, designed to run on Hugging Face Spaces.
Add Secrets
Click the Settings option in the top‑right corner.
Scroll down to Secrets, then click Add new secret.
Create two new secrets:
- Name:
KOMARI_ENDPOINTValue:xxxx - Name:
KOMARI_TOKENValue:xxxxx
These correspond to the -e and -t parameters of the installation script.
Write the Dockerfile
This Dockerfile uses a multi‑stage build: it extracts the executable from the Komari Agent image, then uses a lightweight Python image as the base to avoid complex permission issues.
Create a Dockerfile in Hugging Face and copy the following content:
# Stage 1: Builder, extract executable from Komari Agent image
FROM skylerhe/komari-agent:amd64 AS builder
# Stage 2: Final image, using a lightweight Python image
FROM python:3.10-slim
# Copy Komari Agent executable into the final image
COPY --from=builder /app/komari-agent /usr/local/bin/
# Expose port 7860, which is the default listening port for Hugging Face Spaces
EXPOSE 7860
# Copy the startup script into the container
COPY start.sh /start.sh
# When the container starts, execute the start.sh script
CMD [“bash”, “/start”]
After submitting the Dockerfile, Hugging Face Spaces will automatically start building and deploying the container. Once the container launches successfully, the Space status will change from Building and Starting to Running.
About Keep‑Alive
Use an uptime‑monitoring webpage to keep the app alive. If you don’t have an uptime service, you can manually visit the page yourself. In short, visiting the webpage keeps it alive.
Return to Komari and you’ll see it online—so easy.
