cloud-hosting-platform/cloud-node-container
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive troubleshooting section and clarify user permissions
All checks were successful
Cloud Node Container / Build-and-Push (18) (push) Successful in 1m48s
Details
Cloud Node Container / Build-and-Push (20) (push) Successful in 1m48s
Details
Cloud Node Container / Build-and-Push (22) (push) Successful in 1m51s
Details

Browse Source 
- 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:
jknapp
2025-07-24 10:24:42 -07:00
parent a9dd0573ca
commit 2029c8821e
1 changed files with 21 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@@ -149,6 +149,7 @@ The container automatically generates an ecosystem.config.js file from your pack
#### PM2 Configuration Notes: #### PM2 Configuration Notes:
- The auto-generated PM2 config uses **fork mode** (not cluster mode) for simplicity and compatibility - 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 - `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 - 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: **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 ## Environment Variables
**Required:** **Required:**
- `uid` – User ID for file permissions - `uid` – User ID for file permissions (must match your host user ID)
- `user` – Username for file permissions - `user` – Username for file permissions (must match your host username)
- `domain` – Primary domain for configuration - `domain` – Primary domain for configuration
**Optional:** **Optional:**
@@ -269,3 +270,20 @@ The container is optimized for memory efficiency with automatic memory managemen
- The health check endpoint `/ping` should return a 200 status when the application is running properly - 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 - **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