feat: doocs

Projects/kompose/docs/content/3.guide/troubleshooting.md

@@ -0,0 +1,113 @@
+---
+title: Troubleshooting
+description: Common issues and solutions
+---
+
+### Common Issues
+
+#### :icon{name="lucide:ban"} 404 Error from Traefik
+
+**Problem:** Websites return 404 even though containers are running
+
+**Solution:**
+```bash
+# Check Traefik logs
+docker logs proxy_app
+
+# Verify network configuration
+docker network inspect kompose
+
+# Restart proxy and affected stacks
+./kompose.sh proxy down && ./kompose.sh proxy up -d
+./kompose.sh blog restart
+```
+
+**Debug:**
+```bash
+# Check Traefik dashboard
+http://your-server:8080
+
+# Verify container labels
+docker inspect blog_app | grep traefik
+```
+
+#### :icon{name="lucide:hard-drive"} Database Import Fails
+
+**Problem:** `db:import` command fails
+
+**Common causes:**
+1. **Active connections** - Solved automatically (kompose terminates connections)
+2. **Missing dump file** - Check file path
+3. **Insufficient permissions** - Check DB_USER permissions
+4. **Wrong database** - Verify DB_NAME in stack `.env`
+
+**Solution:**
+```bash
+# Check database connectivity
+docker exec data_postgres psql -U $DB_USER -l
+
+# Verify dump file exists
+ls -lh news/*.sql
+
+# Check logs for detailed error
+./kompose.sh news db:import 2>&1 | tee import.log
+```
+
+#### :icon{name="lucide:plug"} Container Won't Connect to Network
+
+**Problem:** Container fails to join kompose network
+
+**Solution:**
+```bash
+# Recreate network
+docker network rm kompose
+docker network create kompose
+
+# Restart all stacks
+./kompose.sh "*" down
+./kompose.sh "*" up -d
+```
+
+#### :icon{name="lucide:git-branch"} Hooks Not Executing
+
+**Problem:** Custom hooks aren't running
+
+**Checklist:**
+- [ ] `hooks.sh` file exists in stack directory
+- [ ] `hooks.sh` is executable: `chmod +x <stack>/hooks.sh`
+- [ ] Function names match: `hook_pre_db_export`, etc.
+- [ ] Functions return 0 (success) or 1 (failure)
+
+**Test:**
+```bash
+# Dry-run shows hook execution
+./kompose.sh sexy db:export --dry-run
+
+# Check if hooks.sh exists
+./kompose.sh --list | grep hooks
+```
+
+### Debug Mode
+
+Enable verbose logging:
+
+```bash
+# View Traefik debug logs
+docker logs -f proxy_app
+
+# Check environment variables
+./kompose.sh news ps
+docker exec news_backend env
+
+# Inspect running containers
+docker ps -a
+docker inspect <container_name>
+```
+
+### Getting Help
+
+1. **Check logs:** `./kompose.sh <stack> logs`
+2. **Use dry-run:** `./kompose.sh --dry-run <pattern> <command>`
+3. **List stacks:** `./kompose.sh --list`
+4. **Read help:** `./kompose.sh --help`
+5. **Open an issue:** [GitHub Issues](https://github.com/yourusername/kompose/issues)