From 2029c8821e22196330c6fc391ce2661e6b0bf71e Mon Sep 17 00:00:00 2001
From: jknapp <jknapp85@gmail.com>
Date: Thu, 24 Jul 2025 10:24:42 -0700
Subject: [PATCH] Add comprehensive troubleshooting section and clarify user
 permissions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Clarified that uid/user must match host system values
- Added note that PM2 runs as specified user for security
- Created troubleshooting section with common issues:
  - 502 Bad Gateway errors
  - Permission errors
  - App not starting
- Provided specific commands for debugging each issue

This documentation helps users understand and resolve common
container deployment issues.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 60763eb..62d2574 100644
--- a/README.md
+++ b/README.md
@@ -149,6 +149,7 @@ The container automatically generates an ecosystem.config.js file from your pack
 #### PM2 Configuration Notes:
 - The auto-generated PM2 config uses **fork mode** (not cluster mode) for simplicity and compatibility
 - `wait_ready` is set to `false` by default - your app doesn't need to send any special signals to PM2
+- PM2 runs as the specified user (not root) for security - ensure your `uid` and `user` match your host system
 - If you need advanced PM2 features, you can provide your own `ecosystem.config.js` file
 
 **Advanced Usage**: If you want to use PM2's `wait_ready` feature for health checking:
@@ -212,8 +213,8 @@ When you place your app in `user/app/`, the container automatically:
 ## Environment Variables
 
 **Required:**
-- `uid` – User ID for file permissions
-- `user` – Username for file permissions
+- `uid` – User ID for file permissions (must match your host user ID)
+- `user` – Username for file permissions (must match your host username)
 - `domain` – Primary domain for configuration
 
 **Optional:**
@@ -268,4 +269,21 @@ The container is optimized for memory efficiency with automatic memory managemen
 - Check `/home/$user/logs/nodejs/error.log` for application errors
 - The health check endpoint `/ping` should return a 200 status when the application is running properly
 - **Memory issues**: Run `/scripts/memory-info.sh` inside container to check memory usage
-- **Process monitoring**: Use `pm2 monit` to watch application performance
\ No newline at end of file
+- **Process monitoring**: Use `pm2 monit` to watch application performance
+
+### Common Issues and Solutions
+
+**502 Bad Gateway errors:**
+- Check if your app is running on port 3000 (or the PORT environment variable)
+- Look at nginx error logs: `/home/$user/logs/nginx/error.log`
+- Verify PM2 status: `docker exec <container> su - <user> -c "pm2 status"`
+
+**Permission errors:**
+- Ensure `uid` and `user` environment variables match your host system
+- Use `$(id -u)` and `$(whoami)` in your docker run command
+- Files should be owned by your user, not root
+
+**App not starting:**
+- Check PM2 logs: `/home/$user/logs/nodejs/error.log`
+- Verify your package.json has correct `main` or `scripts.start` field
+- Ensure all dependencies are listed in package.json
\ No newline at end of file