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) 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)
   • 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.