docs/dockerization_guide.md

Dockerization Guide: Quran App Suite

This guide provides instructions on how to build, run, and manage the Docker containers for the backend (Spring Boot) and frontend (React/Vite) applications.

---

📂 Files Created & Configured

Backend Setup:

1. quran-app-backend/Dockerfile: Multi-stage Dockerfile packaging Maven, Java 21, and system FFmpeg.
2. quran-app-backend/.dockerignore: Excludes local maven builds and workspace settings.

Frontend Setup:

1. F_Pro/Dockerfile: Multi-stage Dockerfile packaging Node 20-alpine for building static files, and Nginx-alpine to serve them.
2. F_Pro/nginx.conf: Configures Nginx SPA routing (redirecting all paths to index.html to prevent 404s on page reloads).
3. F_Pro/.dockerignore: Excludes node_modules and local build artifacts (dist).

Orchestration:

1. docker-compose.yml: Combines both backend and frontend services, maps ports (3000 for frontend, 8080 for backend), and forwards environment variables.

---

🚀 How to Run the Entire Suite

Ensure your Docker daemon/Desktop is running, and then execute the following commands in the root of the project:

1. Build and Start Both Services

To build and start both the backend and frontend containers:

docker compose up --build

To run in detached mode (background):

docker compose up -d --build

2. Access the Application

• Frontend: Navigate to http://localhost:3000/ in your browser.
• Backend API: The backend is running on http://localhost:8080/.

3. Manage Container State

• Check Status: docker compose ps
• View Logs: docker compose logs -f
• Stop services: docker compose down

---

🛠️ Troubleshooting & Networking Notes

Device Testing & External IPs

If you are testing from external devices (like your phone or an external device on the same local network):

1. Open the root .env file and set the backend host IP:

   VITE_API_BASE_URL=http://<YOUR_LOCAL_IP>:8080
   VITE_WS_URL=http://<YOUR_LOCAL_IP>:8080
   

2. Restart the containers with docker compose up --build so Vite bakes the correct backend IP into the static frontend files.

Why is Docker Compose failing to connect?

If you receive the error:

failed to connect to the docker API at unix:///var/run/docker.sock

Make sure the Docker daemon or Docker Desktop is started:

• For Linux (systemd):

  sudo systemctl start docker
  

• For Docker Desktop: Open the Docker Desktop application and wait for the green indicator.