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 (CNOC) is a Docker-based Node.js hosting environment that supports multiple Node.js versions (18, 20, 22, 24, 26) with Nginx reverse proxy, designed for both local development and production deployment.

Common Development Commands

Local Development Setup

# 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

# Build container locally
docker build -t cnoc:latest .

# Build with specific Node.js version
docker build --build-arg NODEVER=22 -t cnoc: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 cnoc: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, 24, 26)
   • 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.