docker setup and troubleshooting guide

README.md

@@ -63,3 +63,96 @@ The voting application only accepts one vote per client browser. It does not reg
 This isn't an example of a properly architected perfectly designed distributed app... it's just a simple
 example of the various types of pieces and languages you might see (queues, persistent data, etc), and how to
 deal with them in Docker at a basic level.
+
+##  Docker Setup & Troubleshooting Guide
+
+This section provides additional help for users who are new to Docker and may face issues while setting up or running the Example Voting App.
+
+1. docker-compose: command not found
+
+Cause: Docker Compose is not installed or not linked properly.
+Fix (for Linux users):
+
+sudo apt install docker-compose
+
+After installation, verify using:
+
+docker compose version
+
+2. Containers fail to start or exit immediately
+
+Cause: A required image or service may have failed to build.
+Fix:
+
+docker compose down
+docker compose build --no-cache
+docker compose up
+
+3. “Port already in use” error
+
+Cause: Another app or previous Docker container is using the same port (8080 or 8081).
+Fix:
+
+Stop all running containers:
+
+docker stop $(docker ps -q)
+
+Or, change the ports in the docker-compose.yml file before running again.
+
+4. Docker daemon not running
+
+Cause: Docker Engine is not active.
+Fix:
+
+On Windows/Mac, open Docker Desktop and wait until it says “Docker is running”.
+
+On Linux, start Docker manually:
+
+sudo systemctl start docker
+
+
+Then try running:
+
+docker ps
+
+
+to verify that Docker is running.
+
+5. Permission denied (Linux)
+
+Cause: Your user account doesn’t have permission to run Docker commands.
+Fix:
+
+sudo usermod -aG docker $USER
+
+6. Cannot access http://localhost:8080 or http://localhost:8081
+
+Cause: Containers might not be running properly.
+Fix:
+
+Check the container status:
+
+docker ps
+
+
+If they aren’t running, restart the app:
+
+docker compose up
+
+7. Reset the environment completely
+
+If you want to start fresh (remove all containers, images, and volumes):
+
+docker compose down --volumes
+docker system prune -a
+
+
+### Verify Installation
+
+Before running the app, make sure both Docker and Docker Compose are installed correctly.
+
+Check by running these commands:
+
+docker --version
+docker compose version
+