cloud-node-container/CLAUDE.md

# 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.