Add comprehensive troubleshooting section and clarify user permissions
- 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>
This commit is contained in:
24
README.md
24
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
|
||||
- **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
|
Reference in New Issue
Block a user