PSK-Proxy-Tunnel/BUILD.md

PSK-Proxy-Tunnel Build Guide

This guide explains how to build single executable binaries for the PSK-Proxy-Tunnel project using the pkg tool.

Prerequisites

• Node.js: Version 18.0.0 or higher
• npm: Usually comes with Node.js
• Git: To clone the repository

Quick Start

1. Install Dependencies

npm install

2. Build for Current Platform

# macOS/Linux: auto-detect current platform via script
./build.sh

# Windows: auto-detect Windows via script
build.bat

# Or run a specific platform via npm
npm run build:macos      # macOS
npm run build:linux      # Linux
npm run build:windows    # Windows

3. Build for All Platforms

npm run build

Build Scripts

Using the Build Scripts

Unix/Linux/macOS

# Make the script executable
chmod +x build.sh

# Build for current platform
./build.sh

# Build for specific platform
./build.sh --platform macos
./build.sh --platform linux
./build.sh --platform windows

# Build for all platforms
./build.sh --all

# Clean build artifacts
./build.sh --clean

# Show help
./build.sh --help

Windows

# Build for Windows (default)
build.bat

# Build for all platforms
build.bat --all

# Clean build artifacts
build.bat --clean

# Show help
build.bat --help

Using npm Scripts Directly

# Build for specific platform
npm run build:macos
npm run build:linux
npm run build:windows

# Build for all platforms
npm run build

# Clean build artifacts
npm run clean

Build Output

After building, you'll find the executables in the dist/ directory:

dist/
├── psk-proxy-server-macos      # macOS server executable
├── psk-proxy-client-macos      # macOS client executable
├── psk-proxy-server-linux      # Linux server executable
├── psk-proxy-client-linux      # Linux client executable
├── psk-proxy-server-windows.exe # Windows server executable
└── psk-proxy-client-windows.exe # Windows client executable

Platform-Specific Builds

macOS

npm run build:macos
# Creates: psk-proxy-server-macos, psk-proxy-client-macos

Linux

npm run build:linux
# Creates: psk-proxy-server-linux, psk-proxy-client-linux

Windows

npm run build:windows
# Creates: psk-proxy-server-windows.exe, psk-proxy-client-windows.exe

Cross-Platform Building

You can build for other platforms from any operating system:

# Build for all platforms from macOS
npm run build

# Build for all platforms from Linux
npm run build

# Build for all platforms from Windows
npm run build

Using the Built Executables

Server

# macOS/Linux
./dist/psk-proxy-server-macos --tunnel-port 8443 --tcp-port 8080 --host 0.0.0.0 --psk-file /path/to/psk.key

# Windows
.\dist\psk-proxy-server-windows.exe --tunnel-port 8443 --tcp-port 8080 --host 0.0.0.0 --psk-file C:\path\to\psk.key

Client

# macOS/Linux
./dist/psk-proxy-client-macos --server-host server.example.com --server-port 8443 --origin-host 127.0.0.1 --origin-port 8080 --psk-file /path/to/psk.key --identity client1

# Windows
.\dist\psk-proxy-client-windows.exe --server-host server.example.com --server-port 8443 --origin-host 127.0.0.1 --origin-port 8080 --psk-file C:\path\to\psk.key --identity client1

Build Configuration

The build configuration is defined in package.json under the pkg section:

{
  "pkg": {
    "assets": [],
    "scripts": [],
    "targets": [
      "node18-macos-x64",
      "node18-linux-x64", 
      "node18-win-x64"
    ]
  }
}

Available Targets

• node18-macos-x64: macOS 64-bit
• node18-linux-x64: Linux 64-bit
• node18-win-x64: Windows 64-bit

You can modify these targets to support different Node.js versions or architectures.

Troubleshooting

Common Issues

1. "pkg command not found"

   npm install -g pkg
   # or use the local version
   npx pkg proxy-server.js
   

2. Build fails with permission errors

   # Make sure the build script is executable
   chmod +x build.sh
   
   # Or run with sudo if needed
   sudo npm run build
   

3. Executable doesn't run on target platform

   • Ensure you're building for the correct target platform
   • Check that the target platform supports the Node.js version you're using
   • Verify the executable has proper permissions

4. Missing dependencies in built executable

   • The pkg tool automatically bundles Node.js built-in modules
   • External dependencies are included automatically
   • If you have custom assets, add them to the pkg.assets array

Performance Considerations

• File Size: Single executables are larger than the source code because they include Node.js runtime
• Startup Time: Slightly slower startup compared to running with node directly
• Memory Usage: Similar to running with Node.js directly

Security Notes

• Built executables contain your source code (though it's compiled)
• The pkg tool doesn't obfuscate or encrypt your code
• Consider this when distributing executables with sensitive information

Advanced Configuration

Custom pkg Options

You can customize the build process by modifying the pkg section in package.json:

{
  "pkg": {
    "assets": [
      "config/*.json",
      "templates/*.html"
    ],
    "scripts": [
      "scripts/**/*.js"
    ],
    "targets": [
      "node18-macos-x64",
      "node18-linux-x64",
      "node18-win-x64"
    ],
    "outputPath": "custom-dist"
  }
}

Environment Variables

You can set environment variables to customize the build:

# Set custom output directory
PKG_OUTPUT_PATH=./my-dist npm run build

# Set custom Node.js version
PKG_NODE_VERSION=16 npm run build

Contributing

When adding new build targets or modifying the build process:

1. Update the package.json scripts
2. Update the build scripts (build.sh and build.bat)
3. Test builds on all target platforms
4. Update this documentation

License

This build system is part of the PSK-Proxy-Tunnel project and follows the same license terms.