{"id":31895538,"url":"https://github.com/goruck/face-service","last_synced_at":"2025-10-13T10:41:36.397Z","repository":{"id":317538923,"uuid":"1067841462","full_name":"goruck/face-service","owner":"goruck","description":"A FastAPI service for face detection and embedding extraction using InsightFace","archived":false,"fork":false,"pushed_at":"2025-10-01T14:15:10.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T15:29:17.554Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goruck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T13:19:51.000Z","updated_at":"2025-10-01T14:15:16.000Z","dependencies_parsed_at":"2025-10-01T15:29:19.004Z","dependency_job_id":null,"html_url":"https://github.com/goruck/face-service","commit_stats":null,"previous_names":["goruck/face-service"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/goruck/face-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goruck%2Fface-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goruck%2Fface-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goruck%2Fface-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goruck%2Fface-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goruck","download_url":"https://codeload.github.com/goruck/face-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goruck%2Fface-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014647,"owners_count":26085555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T10:41:34.484Z","updated_at":"2025-10-13T10:41:36.387Z","avatar_url":"https://github.com/goruck.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Face Service (FastAPI + InsightFace + ONNXRuntime)\n\nA FastAPI service for **face detection and embedding extraction** using [InsightFace](https://github.com/deepinsight/insightface) with ONNXRuntime (CPU or GPU).\n\n## Features\n- REST API (`/analyze`) → upload an image, get bounding boxes, detection scores, embeddings.\n- Status endpoint (`/status`) → shows backend (CPU/GPU), model bundle, and providers.\n- Configurable via environment variables.\n- Runs manually with `uvicorn` or as a **systemd service** on Ubuntu.\n\n## Project structure\n```text\nface-service/\n├── app.py                   # FastAPI app\n├── requirements-cpu.txt     # Dependencies for CPU build\n├── requirements-gpu.txt     # Dependencies for GPU build\n├── face.env.example         # Example environment config\n├── face-service@.service    # Systemd unit template\n└── README.md                # This file\n```\n\n## Installation\n\n### 1. Clone the project\nYou can clone this repo anywhere (e.g., `/home/\u003cuser\u003e/Develop/face-service` or `/opt/face-service`):\n\n```bash\ngit clone https://github.com/goruck/face-service.git\ncd face-service\n```\n\n⚠️ Important: If you move the repo later, update the paths in your .env file (see Configuration).\n\n### 2. Set up environment\n\nCreate a Python 3.9+ virtual environment:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install --upgrade pip\n```\n\nInstall dependencies (choose either CPU or GPU build):\n\nCPU build\n\n```bash\npip install -r requirements-cpu.txt\n```\n\nGPU build (CUDA)\n\n```bash\npip install -r requirements-gpu.txt\n```\n\nDevelopment tools (optional, for linting)\n\n```bash\npip install -r requirements-dev.txt\n```\n\n### 3. Configuration\n\nEnvironment is controlled by variables in an .env file.\n\nAn example env file is included: face.env.example.\n\nCopy it to /etc/face-service/ and edit as needed:\n\n```bash\nsudo mkdir -p /etc/face-service\nsudo cp face.env.example /etc/face-service/face.env\nsudo nano /etc/face-service/face.env\n```\n\nKey values to set:\n\n- APP_DIR → path where you cloned this repo\n- VENV_DIR → path to the venv inside this repo (usually \u003cAPP_DIR\u003e/.venv)\n- PORT → service port (e.g. 8000, 8001 for another instance)\n- USE_CPU, GPU_ID, FACE_MODEL → control runtime\n\n## Usage\n\n### 1. Run manually\n\nFrom inside the project directory:\n\n```bash\nsource .venv/bin/activate\npython app.py\n```\n\nOr run with uvicorn (recommended):\n\n```bash\nsource .venv/bin/activate\nuvicorn app:app --host 0.0.0.0 --port 8000\n```\n\n### 2. Run as a systemd service (Ubuntu)\n\nThis repo includes a systemd unit template: face-service@.service.\n\n#### 2.1 Copy to systemd\n```bash\nsudo cp face-service@.service /etc/systemd/system/\n```\n\n#### 2.2 Reload and enable\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable face-service@lindo\nsudo systemctl start face-service@lindo\n```\n\nReplace lindo with your Linux username.\n\nThe service will read /etc/face-service/face.env for settings.\n\n#### 2.3 Check logs\n```bash\nsystemctl status face-service@lindo\njournalctl -u face-service@lindo -f\n```\n\n### 3. API\n\nCheck service status\n\n```bash\ncurl http://127.0.0.1:8000/status\n```\n\nAnalyze an image\n\n```bash\ncurl -F \"file=@/path/to/image.jpg\" http://127.0.0.1:8000/analyze\n```\n\n## CI\n\nThis repo ships with a GitHub Actions workflow at `.github/workflows/ci.yml`:\n\n- **cpu-smoke**: installs CPU requirements, lints (ruff), launches the app with `USE_CPU=true`, and curls `/status`.\n- **gpu-install**: verifies `requirements-gpu.txt` is installable on a standard runner (no GPU runtime test).\n\nIf your app file/module isn’t `app.py` with `app = FastAPI()`, edit the CI step:\n```bash\nuvicorn \u003cyour_module\u003e:app --host 127.0.0.1 --port 8000\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoruck%2Fface-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoruck%2Fface-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoruck%2Fface-service/lists"}