[BUG]: Docker Environment Fails to Start API (Missing libGL and Port mapping)

[RITVIKKAMASETTY]

---

name: 🐛 Bug Report
about: Create a report to help us improve FireForm.
title: "[BUG]: Docker Environment Fails to Start API (Missing libGL and Port mapping)"
labels: bug, dev-environment
assignees: ''

---

⚡️ Describe the Bug

The local Docker environment fails out of the box when trying to run the FastAPI server. There are two distinct issues preventing local development/testing:

1. Missing System Dependency: Running the app throws an ImportError: libGL.so.1: cannot open shared object file: No such file or directory. This happens because commonforms relies on ultralytics (YOLO) which relies on OpenCV (cv2). The base python:3.11-slim image strips out libgl1, causing the server crash.
2. Port Not Exposed: The docker-compose.yml does not expose port 8000 for the app container, meaning even if the FastAPI server runs inside the container, the host machine cannot send HTTP requests to localhost:8000.

👣 Steps to Reproduce

1. Run make build and make up.
2. Exec into the container and attempt to start the server: docker compose exec app uvicorn api.main:app --host 0.0.0.0 --port 8000
3. Observe the ImportError: libGL.so.1 stack trace crashing the server instantly.
4. If you artificially bypass that error, curl localhost:8000 from the host Mac/PC fails with Connection Refused because the port is not mapped in Compose.

📉 Expected Behavior

A clean clone of the repo followed by make up should correctly install all system requirements. Developers should be able to start uvicorn and access the API on localhost:8000 immediately.

🖥️ Environment Information

• OS: MacOS / Linux / Windows
• Docker/Compose Version: Latest
• Ollama Model used: N/A (Startup crash)

📸 Screenshots/Logs

  File "/usr/local/lib/python3.11/site-packages/cv2/__init__.py", line 181, in <module>
    bootstrap()
  File "/usr/local/lib/python3.11/site-packages/cv2/__init__.py", line 153, in bootstrap
    native_module = importlib.import_module("cv2")
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ImportError: libGL.so.1: cannot open shared object file: No such file or directory

🕵️ Possible Fix
Add libgl1 and libglib2.0-0 to the apt-get install block in the 

Dockerfile
.
Add a ports: - "8000:8000" mapping to the app service in docker-compose.yml.

[SouravVerma-art]

I would like to work on this issue.
The fix seems straightforward: installing the missing system dependencies (libgl1, libglib2.0-0) in the Dockerfile and exposing port 8000 in docker-compose.yml.

Could you please assign this issue to me?

[RITVIKKAMASETTY]

@SouravVerma-art
already fixed and raised the pr
please contribute for other issues

[SouravVerma-art]

Thanks for the update! I'll look into other open issues and try to contribute.

[kasimlohar]

@RITVIKKAMASETTY
I ran into both of these issues while setting up the project on Windows 11 with Docker Desktop.

• Just tested the fix in PR fix: Add missing libgl dependency resolving cv2 crash and expose API port (Fixes #223) #225 and it resolves both problems. Adding libgl1 + libglib2.0-0 in the Dockerfile and the ports: "8000:8000" mapping in docker-compose works correctly.

One small thought: using opencv-python-headless in requirements.txt could remove the libgl1 dependency for headless/server environments. That could be a separate improvement, though.

Happy to help test or review the PR if needed 👍

[RITVIKKAMASETTY]

@kasimlohar
Thanks for testing and reviewing!
I honestly didn't know there was a lighter, headless version of OpenCV available specifically for server environments — thanks for the heads up!
That's a great suggestion and completely relevant since we're running this in Docker anyway. I'll go ahead and update requirements.txt to use opencv-python-headless and remove libgl1 + libglib2.0-0 from the Dockerfile right now. I'll push those changes here shortly.