From 451b3d064244614a3199c3d1d09e488c4db187f3 Mon Sep 17 00:00:00 2001
From: harris1111 <minhan112001@gmail.com>
Date: Wed, 25 Mar 2026 16:51:57 +0700
Subject: [PATCH] docs: update files_to_copy examples to newline separator

Align documentation with actions repo change from space to newline
separated files_to_copy using YAML block scalar.
---
 README-2.md                  | 292 ++++++++++++++++++++++++
 docs/dockerfile-generator.md | 414 +++++++++++++++++++++++++++++++++++
 2 files changed, 706 insertions(+)
 create mode 100644 README-2.md
 create mode 100644 docs/dockerfile-generator.md

diff --git a/README-2.md b/README-2.md
new file mode 100644
index 0000000..47935dc
--- /dev/null
+++ b/README-2.md
@@ -0,0 +1,292 @@
+# dev-off
+
+DevOps toolchain for Orochi Network — Dockerfile generation, GPG commit verification, local infrastructure, and developer environment setup.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Dockerfile Generator](#dockerfile-generator)
+- [GPG Commit Verification](#gpg-commit-verification)
+- [Local Infrastructure](#local-infrastructure)
+- [NPM/Yarn Configuration](#npmyarn-configuration)
+- [Claude Code Setup (Z.AI)](#claude-code-setup-zai)
+- [Security & Checksums](#security--checksums)
+- [Repository Structure](#repository-structure)
+- [Contributing](#contributing)
+
+## Overview
+
+`dev-off` provides shared DevOps utilities used across Orochi Network repositories:
+
+| Tool | Description |
+|------|-------------|
+| `dockerfile.sh` | Generate multi-stage Dockerfiles from templates |
+| `check-gpg.sh` | Verify GPG signatures on PR commits |
+| `docker-compose.yaml` | Local dev infrastructure (Postgres, Redis, RabbitMQ) |
+| `generate-yarn-npm.sh` | Configure `.npmrc` and `.yarnrc.yml` for private packages |
+| `claude_code_zai_env.sh` | Install and configure Claude Code with Z.AI API |
+| `security.sh` | Merge GPG keys and update checksums |
+
+Scripts can be run locally or fetched remotely via `curl`. Pin a specific revision with `BASE_REVISION`:
+
+```bash
+BASE_REVISION="main" curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/<script> | bash
+```
+
+## Dockerfile Generator
+
+Generate optimized multi-stage Dockerfiles for Node.js, Next.js, and Nginx projects.
+
+### Quick Start
+
+```bash
+# Remote usage
+curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/dockerfile.sh | bash -- -t node -f package.json -f build
+
+# Local usage
+./dockerfile.sh -t next -f .next -f package.json -f node_modules -f public
+```
+
+### Templates
+
+| Template | Runner Image | Use Case |
+|----------|-------------|----------|
+| `node` | `node:24-alpine` | Node.js backend apps |
+| `next` | `node:24-alpine` | Next.js apps (adds `NEXT_TELEMETRY_DISABLED=1`) |
+| `nginx` | `nginx:stable-alpine` | Static sites (React, Vue, HTML); exposes port 80 |
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-t, --template TYPE` | Template: `node`, `nginx`, `next` | Required |
+| `-f, --file FILE` | File/dir to copy (repeatable). Use `"src;dst"` for custom paths | — |
+| `-c, --command CMD` | Container CMD | `["npm", "start"]` |
+| `-b, --build CMD` | Custom build command | Auto-detected |
+| `-r, --runner-image IMAGE` | Custom runner image | Template default |
+| `-e, --env-file FILE` | Copy .env file before build | — |
+| `--run CMD` | Extra RUN in runner stage (repeatable) | — |
+| `--dry-run` | Print to stdout instead of writing file | `false` |
+| `-l, --list` | List templates | — |
+
+### File Copy Formats
+
+**Simple** — copies between builder and runner workdirs:
+
+```bash
+-f package.json     # /home/ubuntu/app/package.json → ./package.json
+```
+
+**Custom paths** — semicolon-separated `src;dst`:
+
+```bash
+-f "nginx.conf;/etc/nginx/conf.d/default.conf"
+```
+
+### Build Command Priority
+
+1. `-b "custom command"` (highest)
+2. Local `scripts/build-prod.sh` if exists
+3. Remote `build-prod-{template}.sh` (lowest)
+
+### Examples
+
+```bash
+# Node.js with custom runner
+./dockerfile.sh -t node -r node:24-trixie-slim -f build -f package.json \
+  -c '["node", "server.js"]'
+
+# Nginx with custom config
+./dockerfile.sh -t nginx -f "nginx.conf;/etc/nginx/conf.d/default.conf"
+
+# Next.js with env file and dry-run
+./dockerfile.sh -t next -e .env.production -f .next -f package.json --dry-run
+
+# Post-copy RUN commands
+./dockerfile.sh -t node -f build -f package.json \
+  --run "chmod +x /home/node/app/run-service.sh"
+```
+
+### Building the Image
+
+```bash
+# Basic
+docker build -t myapp:latest .
+
+# With NPM token for private packages
+echo "$NPM_ACCESS_TOKEN" > npm_access_token
+docker build --secret id=npm_access_token,src=./npm_access_token -t myapp:latest .
+```
+
+### GitHub Actions
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: orochi-network/actions/build-docker-template@main
+        with:
+          template: next
+          docker_repo: myorg/myapp
+          files_to_copy: |
+            .next
+            package.json
+            node_modules
+            public
+          platform: linux/amd64
+        secrets: inherit
+```
+
+Full action inputs and reusable workflow docs: see [docs/dockerfile-generator.md](./docs/dockerfile-generator.md).
+
+### Custom Templates
+
+Place a `Dockerfile.template` in your project root to override the remote template. Available placeholders: `{{builder_base_image}}`, `{{runner_base_image}}`, `{{build_command}}`, `{{copy_instructions}}`, `{{cmd}}`, etc.
+
+## GPG Commit Verification
+
+Verify all commits in a PR are GPG-signed by allowed team members.
+
+```bash
+curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/check-gpg.sh | bash
+```
+
+### How It Works
+
+1. Downloads and verifies `gpg-list.asc` against `checksum.sha256`
+2. Imports GPG keys and sets ultimate trust
+3. Builds allowlist of authorized key IDs
+4. For each commit in `BASE_SHA..HEAD_SHA`: checks signature status (`G` = good) and verifies key is in allowlist
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BASE_REVISION` | Script revision to use (default: `main`) |
+| `BASE_SHA` | Start of commit range to verify |
+| `HEAD_SHA` | End of commit range to verify |
+
+### Managing GPG Keys
+
+Team member keys live in `gpg/*.asc`. To add/update:
+
+1. Export public key: `gpg --armor --export <KEY_ID> > gpg/<name>.asc`
+2. Run `./security.sh` to merge keys into `gpg-list.asc` and update `checksum.sha256`
+3. Commit all changed files
+
+## Local Infrastructure
+
+Development services via Docker Compose (profile: `infra`):
+
+| Service | Image | Ports |
+|---------|-------|-------|
+| PostgreSQL 16 | `postgres:16` | `${POSTGRES_PORT}:5432` |
+| Redis | `redis:latest` | `7011:6379` |
+| RabbitMQ 4.0.6 | `rabbitmq:4.0.6-management` | `7012:5672` (AMQP), `7013:15672` (UI) |
+
+### Usage
+
+```bash
+# Create .env with required vars
+cat > .env << 'EOF'
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=password
+POSTGRES_DB=devdb
+POSTGRES_PORT=5432
+EOF
+
+# Start all services
+docker compose --profile infra up -d
+
+# Stop
+docker compose --profile infra down
+```
+
+All services include health checks and persistent volumes.
+
+## NPM/Yarn Configuration
+
+Generate `.npmrc` and `.yarnrc.yml` for private `@orochi-network` and `@zkdb` packages.
+
+```bash
+NPM_ACCESS_TOKEN="your-token" ./generate-yarn-npm.sh
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-s HOME_PATH` | Target directory (default: `/home/ubuntu`) |
+| `-f SCOPE` | Add npm scope (repeatable; currently unused — global auth) |
+
+Currently configures global npm authentication rather than per-scope.
+
+## Claude Code Setup (Z.AI)
+
+One-command setup for Claude Code with Z.AI API proxy.
+
+```bash
+curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/claude_code_zai_env.sh | bash
+```
+
+### What It Does
+
+1. Checks/installs Node.js >= 18 via nvm
+2. Installs `@anthropic-ai/claude-code` globally
+3. Prompts for Z.AI API key
+4. Writes `~/.claude/settings.json` with API base URL and auth token
+
+Get your API key at: https://z.ai/manage-apikey/apikey-list
+
+## Security & Checksums
+
+`security.sh` maintains integrity of shared assets:
+
+1. Merges all `gpg/*.asc` files into `gpg-list.asc`
+2. Generates `checksum.sha256` covering `gpg-list.asc`, `configs/*`, and `scripts/*`
+
+Run after any change to GPG keys, configs, or build scripts:
+
+```bash
+./security.sh
+```
+
+## Repository Structure
+
+```
+dev-off/
+├── check-gpg.sh              # GPG commit signature verification
+├── dockerfile.sh              # Dockerfile generator CLI
+├── Dockerfile.template        # Template used by dockerfile.sh
+├── DOCKERFILE.md              # Detailed Dockerfile generator docs
+├── docker-compose.yaml        # Local dev infrastructure
+├── generate-yarn-npm.sh       # NPM/Yarn auth config generator
+├── claude_code_zai_env.sh     # Claude Code + Z.AI setup
+├── security.sh                # GPG key merger + checksum updater
+├── checksum.sha256            # SHA256 checksums for verified files
+├── gpg-list.asc               # Merged GPG public keys
+├── gpg/                       # Individual team member GPG keys
+│   └── *.asc
+├── configs/
+│   └── nginx.conf             # Default nginx configuration
+├── scripts/
+│   ├── build-prod-node.sh     # Default Node.js build script
+│   ├── build-prod-next.sh     # Default Next.js build script
+│   └── build-prod-nginx.sh    # Default Nginx build script
+├── list-dockerfile/            # Example/reference Dockerfiles
+├── .env                        # Local env vars (not committed)
+└── LICENSE                     # Apache 2.0
+```
+
+## Contributing
+
+1. Fork and create a feature branch
+2. All commits must be GPG-signed (enforced by CI)
+3. If modifying GPG keys, configs, or scripts — run `./security.sh` before committing
+4. Open a PR against `main`
+
+## License
+
+[Apache License 2.0](./LICENSE)
diff --git a/docs/dockerfile-generator.md b/docs/dockerfile-generator.md
new file mode 100644
index 0000000..cafe7e7
--- /dev/null
+++ b/docs/dockerfile-generator.md
@@ -0,0 +1,414 @@
+# Dockerfile Generator
+
+A bash script that automatically generates optimized, multi-stage Dockerfiles for Node.js, Next.js, and Nginx projects.
+
+## Overview
+
+Instead of writing Dockerfiles manually, this tool generates them based on templates and command-line options. It follows Docker best practices including:
+
+- **Multi-stage builds** - Separate builder and runner stages for smaller final images
+- **Non-root users** - Runs applications as non-privileged users for security
+- **Optimized layers** - Efficient COPY instructions with proper ownership
+- **NPM token handling** - Secure mounting of NPM access tokens as Docker secrets
+
+## Quick Start
+
+```bash
+# Download the script
+curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/dockerfile.sh -o dockerfile.sh
+chmod +x dockerfile.sh
+
+# Generate a Dockerfile for a Next.js project
+./dockerfile.sh -t next -f .next -f package.json -f node_modules -f public
+
+# Preview without writing to file
+./dockerfile.sh -t node -f build -f package.json --dry-run
+```
+
+## Installation
+
+### Option 1: Download directly
+
+```bash
+curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/dockerfile.sh -o dockerfile.sh
+chmod +x dockerfile.sh
+```
+
+### Option 2: Use with specific revision
+
+```bash
+# Pin to a specific commit/tag for reproducibility
+BASE_REVISION="main" curl -sL https://raw.githubusercontent.com/orochi-network/dev-off/main/dockerfile.sh | bash -s -- -t next -f .next
+```
+
+### Option 3: Use via GitHub Actions
+
+See [GitHub Actions Integration](#github-actions-integration) section below.
+
+## Available Templates
+
+| Template | Runner Image | Use Case |
+|----------|--------------|----------|
+| `node` | `node:24-alpine` | Node.js backend applications |
+| `next` | `node:24-alpine` | Next.js applications (SSR/SSG) |
+| `nginx` | `nginx:stable-alpine` | Static websites (React, Vue, HTML) |
+
+List all templates with details:
+
+```bash
+./dockerfile.sh -l
+```
+
+## Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --template TYPE` | Template type: `node`, `nginx`, `next` | Required |
+| `-f, --file FILE` | File/directory to copy (repeatable) | None |
+| `-c, --command CMD` | Container CMD command | `["npm", "start"]` |
+| `-b, --build CMD` | Custom build command | Auto-detected |
+| `-r, --runner-image IMAGE` | Custom runner image | Template default |
+| `--run CMD` | Extra RUN command in runner (repeatable) | None |
+| `--dry-run` | Print to stdout instead of file | `false` |
+| `-l, --list` | List available templates | - |
+| `-h, --help` | Show help message | - |
+
+## File Copy Behavior
+
+The `-f` option supports two formats:
+
+### Single Argument (Simple)
+
+Copies from builder workdir to runner workdir automatically.
+
+```bash
+./dockerfile.sh -t node -f package.json -f build -f node_modules
+```
+
+Generated output:
+
+```dockerfile
+COPY --from=builder --chown=node:node /home/ubuntu/app/package.json ./package.json
+COPY --from=builder --chown=node:node /home/ubuntu/app/build ./build
+COPY --from=builder --chown=node:node /home/ubuntu/app/node_modules ./node_modules
+```
+
+### Two Arguments with Semicolon (Custom Paths)
+
+For cases where source and destination paths differ.
+
+```bash
+./dockerfile.sh -t nginx -f "nginx.conf;/etc/nginx/conf.d/default.conf" -f "build;/usr/share/nginx/html"
+```
+
+Generated output:
+
+```dockerfile
+COPY --from=builder --chown=nginx:nginx nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=builder --chown=nginx:nginx build /usr/share/nginx/html
+```
+
+## Examples
+
+### Node.js Backend
+
+```bash
+./dockerfile.sh -t node \
+  -f package.json \
+  -f build \
+  -f node_modules
+```
+
+### Node.js with Custom Runner Image
+
+```bash
+./dockerfile.sh -t node \
+  -r node:22-trixie-slim \
+  -f package.json \
+  -f dist \
+  -f node_modules \
+  -c '["node", "dist/server.js"]'
+```
+
+### Next.js Application
+
+```bash
+./dockerfile.sh -t next \
+  -f .next \
+  -f package.json \
+  -f node_modules \
+  -f next.config.ts \
+  -f public
+```
+
+### Nginx Static Website
+
+```bash
+./dockerfile.sh -t nginx \
+  -f "nginx.conf;/etc/nginx/conf.d/default.conf" \
+  -f "build;/usr/share/nginx/html"
+```
+
+### Nginx with Extra RUN Commands
+
+```bash
+./dockerfile.sh -t nginx \
+  -f "build;/usr/share/nginx/html" \
+  --run "chown -R nginx:nginx /var/cache/nginx" \
+  --run "touch /run/nginx.pid && chown nginx:nginx /run/nginx.pid"
+```
+
+### Complex Example with All Options
+
+```bash
+./dockerfile.sh -t node \
+  -r node:22-alpine \
+  -f package.json \
+  -f tsconfig.json \
+  -f migrations \
+  -f seeds \
+  -f node_modules \
+  -f build \
+  -b "yarn install --frozen-lockfile && yarn build" \
+  -c '["node", "build/index.js"]' \
+  --run "chmod +x /home/node/app/build/index.js"
+```
+
+### Preview Without Writing (Dry Run)
+
+```bash
+./dockerfile.sh -t next -f .next -f package.json --dry-run
+```
+
+## Build Command Priority
+
+The script determines the build command in this order:
+
+1. **Custom command** (`-b` option) - If provided, uses this command
+2. **Local script** - If `scripts/build-prod.sh` exists in your project
+3. **Remote script** - Downloads from `build-prod-{template}.sh`
+
+```
+Priority:
+┌─────────────────────────────────────────┐
+│ 1. -b "custom command"                  │  ← Highest
+├─────────────────────────────────────────┤
+│ 2. ./scripts/build-prod.sh (local)      │
+├─────────────────────────────────────────┤
+│ 3. Remote build-prod-{template}.sh      │  ← Lowest
+└─────────────────────────────────────────┘
+```
+
+## Generated Dockerfile Structure
+
+The generated Dockerfile follows this structure:
+
+```dockerfile
+# ============ BUILDER STAGE ============
+FROM orochinetwork/ubuntu:node AS builder
+
+ARG BUILDER_WORKDIR=/home/ubuntu/app
+
+# Setup NPM/Yarn credentials (mounted as secret)
+RUN --mount=type=secret,id=npm_access_token ...
+
+WORKDIR ${BUILDER_WORKDIR}
+COPY --chown=ubuntu:ubuntu . .
+USER ubuntu:ubuntu
+
+# Build command (custom, local, or remote script)
+RUN ...
+
+# ============ RUNNER STAGE ============
+FROM node:24-alpine AS runner
+
+ARG RUNNER_WORKDIR=/home/node/app
+
+# Create app directory with proper permissions
+RUN mkdir -p ${RUNNER_WORKDIR} && ...
+
+WORKDIR ${RUNNER_WORKDIR}
+
+# Copy built artifacts from builder
+COPY --from=builder --chown=node:node ...
+
+# Extra RUN commands (if any)
+RUN ...
+
+USER node:node
+
+CMD ["npm", "start"]
+```
+
+## Template Configuration
+
+### Default Values
+
+| Setting | Builder | Runner (node/next) | Runner (nginx) |
+|---------|---------|-------------------|----------------|
+| Base Image | `orochinetwork/ubuntu:node` | `node:24-alpine` | `nginx:stable-alpine` |
+| User | `ubuntu` | `node` | `nginx` |
+| Group | `ubuntu` | `node` | `nginx` |
+| Workdir | `/home/ubuntu/app` | `/home/node/app` | `/usr/share/nginx/html` |
+
+### Template-Specific Features
+
+#### Node.js (`-t node`)
+- Standard Node.js runtime
+- Default CMD: `["npm", "start"]`
+
+#### Next.js (`-t next`)
+- Includes `ENV NEXT_TELEMETRY_DISABLED=1`
+- Default CMD: `["npm", "start"]`
+
+#### Nginx (`-t nginx`)
+- Includes `EXPOSE 80`
+- Default CMD: `["nginx", "-g", "daemon off;"]`
+- Auto-defaults to copying `build/` to `/usr/share/nginx/html` if no files specified
+
+## GitHub Actions Integration
+
+### Using the Composite Action
+
+```yaml
+name: Build Docker Image
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker Image
+        uses: orochi-network/actions/build-docker-template@main
+        with:
+          template: next
+          docker_repo: myorg/myapp
+          files_to_copy: |
+            .next
+            package.json
+            node_modules
+            public
+          platform: linux/amd64
+        secrets: inherit
+```
+
+### Action Inputs
+
+| Input | Description | Required | Default |
+|-------|-------------|----------|---------|
+| `template` | Template type | Yes | - |
+| `docker_repo` | Docker repository name | Yes | - |
+| `image_tag` | Docker image tag | No | `${{ github.sha }}` |
+| `files_to_copy` | Newline-separated files (use `src;dst` for custom paths) | No | - |
+| `command` | Container CMD | No | `["npm", "start"]` |
+| `build_command` | Custom build command | No | Auto |
+| `runner_image` | Custom runner image | No | Template default |
+| `runner_commands` | Extra RUN commands (newline-separated) | No | - |
+| `platform` | Build platform | No | `linux/amd64` |
+| `npm_access_token` | NPM token (secret) | No | - |
+| `env_file_content` | Content for .env file | No | - |
+| `base_revision` | Script revision | No | `main` |
+
+### Using Reusable Workflow
+
+```yaml
+name: Build and Deploy
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    uses: orochi-network/actions/.github/workflows/test-docker-gen-build.yml@main
+    with:
+      template: next
+      docker_repo: myorg/myapp
+      image_tag: ${{ github.ref_name }}
+      files_to_copy: |
+        .next
+        package.json
+        node_modules
+        next.config.ts
+        public
+    secrets: inherit
+```
+
+## Building the Docker Image
+
+After generating the Dockerfile:
+
+```bash
+# Basic build
+docker build -t myapp:latest .
+
+# With NPM access token (for private packages)
+echo "$NPM_ACCESS_TOKEN" > npm_access_token
+docker build \
+  --secret id=npm_access_token,src=./npm_access_token \
+  -t myapp:latest .
+
+# Multi-platform build
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --secret id=npm_access_token,src=./npm_access_token \
+  -t myapp:latest \
+  --push .
+```
+
+## Customizing the Template
+
+If you need to customize the Dockerfile template, create a `Dockerfile.template` file in your project root. The script will use local template over remote one.
+
+### Available Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{{builder_base_image}}` | Builder stage base image |
+| `{{builder_user}}` | Builder user name |
+| `{{builder_group}}` | Builder group name |
+| `{{runner_base_image}}` | Runner stage base image |
+| `{{runner_user}}` | Runner user name |
+| `{{runner_group}}` | Runner group name |
+| `{{build_command}}` | Build command(s) |
+| `{{copy_instructions}}` | COPY instructions |
+| `{{runner_commands}}` | Extra RUN commands |
+| `{{extra_env}}` | Extra ENV variables |
+| `{{expose_port}}` | EXPOSE instruction |
+| `{{cmd}}` | CMD instruction |
+
+## Troubleshooting
+
+### Script not found
+
+```bash
+# Make sure the script is executable
+chmod +x dockerfile.sh
+```
+
+### Template not generating correctly
+
+```bash
+# Use --dry-run to preview output
+./dockerfile.sh -t node -f build --dry-run
+
+# Check if local template exists (might override remote)
+ls -la Dockerfile.template
+```
+
+### Build fails with permission errors
+
+Ensure your build outputs are owned by the correct user. The script sets up proper ownership, but your build process should not change file ownership.
+
+### NPM packages not installing
+
+Make sure to mount the NPM access token as a Docker secret:
+
+```bash
+docker build --secret id=npm_access_token,src=./npm_access_token -t myapp .
+```
\ No newline at end of file