jknapp
2989cd590a
- Add Dockerfile with AlmaLinux 9 base, Nginx reverse proxy, and PM2 - Support Node.js versions 18, 20, 22 with automated installation - Implement memory-optimized configuration (256MB minimum, 512MB recommended) - Add Memcached session storage for development environments - Create comprehensive documentation (README, USER-GUIDE, MEMORY-GUIDE, CLAUDE.md) - Include example applications (simple website and REST API) - Add Gitea CI/CD pipeline for automated multi-version builds - Provide local development script with helper utilities - Implement health monitoring, log rotation, and backup systems 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Cloud Node Container (CNC) is a Docker-based Node.js hosting environment that supports multiple Node.js versions (18, 20, 22) with Nginx reverse proxy, designed for both local development and production deployment.
|
|
|
|
## Common Development Commands
|
|
|
|
### Local Development Setup
|
|
```bash
|
|
# Quick start with automated setup (creates helper scripts and default app)
|
|
./local-dev.sh -n local-dev
|
|
|
|
# With specific Node.js version
|
|
./local-dev.sh -n myproject -a 22 # Node.js 22
|
|
|
|
# Helper scripts created by local-dev.sh:
|
|
./instance_start # Start container
|
|
./instance_stop # Stop container
|
|
./instance_logs # View container logs
|
|
./instance_shell # Access container shell
|
|
```
|
|
|
|
### Building and Testing
|
|
```bash
|
|
# Build container locally
|
|
docker build -t cloud-node-container:latest .
|
|
|
|
# Build with specific Node.js version
|
|
docker build --build-arg NODEVER=22 -t cnc:node22 .
|
|
|
|
# Run container manually
|
|
docker run -d -p 80:80 -p 443:443 \
|
|
-e NODEVER=20 -e environment=DEV \
|
|
-e uid=$(id -u) -e user=$(whoami) -e domain=localhost \
|
|
-v"$(pwd)/user":/home/$(whoami) \
|
|
--name test-container cloud-node-container:latest
|
|
```
|
|
|
|
### Server Deployment
|
|
- Production git directory: `/root/whp`
|
|
- After `git pull`, sync web files: `rsync -av web-files/ /docker/whp/web/`
|
|
|
|
## Architecture and Key Components
|
|
|
|
### Directory Structure
|
|
- `/scripts/` - Container setup scripts (entrypoint, Node.js installers, nginx config)
|
|
- `/configs/` - Nginx, PM2, and default application configurations
|
|
- User applications go in `/home/$user/app/`
|
|
|
|
### Container Behavior
|
|
1. **Entrypoint Flow** (`scripts/entrypoint.sh`):
|
|
- Creates user with specified UID
|
|
- Sets up directory structure (/home/$user/app/, logs/)
|
|
- Configures Nginx reverse proxy based on environment variables
|
|
- In DEV mode: starts Memcached for session storage
|
|
- Starts Nginx and PM2-managed Node.js application
|
|
|
|
2. **Environment Modes**:
|
|
- **DEV** (`environment=DEV`): Local Memcached, automatic backups, verbose logging
|
|
- **PROD** (default): Expects external services, optimized for production
|
|
|
|
3. **Node.js Version Management**:
|
|
- Controlled via `NODEVER` environment variable (18, 20, 22)
|
|
- Each version has dedicated install script in `/scripts/`
|
|
- PM2 ecosystem configuration adapts to user paths
|
|
|
|
### Key Environment Variables
|
|
- `uid` (required): User ID for file permissions
|
|
- `user` (required): Username for container user
|
|
- `domain` (required): Primary domain for Nginx configuration
|
|
- `serveralias`: Additional domains (comma-separated)
|
|
- `NODEVER`: Node.js version to use (default: 20)
|
|
- `environment`: DEV or PROD mode
|
|
|
|
## Important Technical Details
|
|
|
|
1. **Health Check**: Available at `/ping` endpoint (Node.js app must implement)
|
|
2. **Logs Location**: `/home/$user/logs/nginx/` and `/home/$user/logs/nodejs/`
|
|
3. **Application Backups** (DEV mode): Every 30 minutes to `/home/$user/_backups/`
|
|
4. **Log Rotation**: Compress after 3 days, delete after 7 days
|
|
5. **SSL**: Self-signed certificate auto-generated, Nginx handles SSL termination
|
|
6. **Static Files**: Nginx serves from `/home/$user/app/public/` at `/static/` path
|
|
7. **Process Management**: PM2 handles Node.js application lifecycle
|
|
|
|
## Application Requirements
|
|
|
|
User applications in `/home/$user/app/` should include:
|
|
- `package.json` with dependencies and scripts
|
|
- Main application file (default: `index.js`)
|
|
- Optional: `ecosystem.config.js` for PM2 configuration
|
|
- Optional: `public/` directory for static assets
|
|
|
|
The container provides a default Express.js application with health endpoints and Memcached session support if no user application is found. |