docs: instructions for how to set up a server+client development environment

[billchurch]

via @israel-tsadok-silk from billchurch/webssh2#368

I am not a node.js developer, so I don't know how trivial this is, but maybe have some instructions for how to set up a server+client development environment that allows working on both components together without having to build a client package every time.

peer issue: billchurch/webssh2#370

[billchurch]

WebSSH2 Development Guide

This guide explains how to set up and run the WebSSH2 client and server components for development.

Prerequisites

• Node.js (>= 6.9.1)
• npm
• Git
• Two terminal windows/sessions

Project Setup

1. Create a development directory and clone both repositories:

mkdir webssh2-dev
cd webssh2-dev

# Clone the client repository
git clone https://github.com/billchurch/webssh2_client.git

# Clone the server repository
git clone https://github.com/billchurch/webssh2.git webssh2_server

2. Install dependencies for both projects:

# Install client dependencies
cd webssh2_client
npm install

# Install server dependencies
cd ../webssh2_server
npm install

Development Workflow

Starting the Server Component

1. In your first terminal window, navigate to the server directory:

cd webssh2_server

2. Start the server in development mode:

npm run watch

This will:

• Start the WebSSH2 server on port 2222
• Enable automatic reloading when server files change
• Allow CORS for the development client

Starting the Client Component

1. In your second terminal window, navigate to the client directory:

cd webssh2_client

2. Start the client in development mode:

npm run watch

This will:

• Start a development server on port 3000
• Run NODE_ENV=development npm-run-all --parallel start watch:build
• Watch for file changes and rebuild automatically
• Inject development configuration into the client HTML

The development configuration is automatically injected through webpack.common.js when NODE_ENV=development:

webssh2Config: {
  socket: { 
    url: 'http://localhost:2222', 
    path: '/ssh/socket.io' 
  },
  ssh: { 
    port: 22 
  }
}

Accessing the Development Environment

1. Open your web browser and navigate to:

http://localhost:3000

2. The client will automatically connect to the development server at localhost:2222

Development Architecture

sequenceDiagram
    participant Browser as Browser<br/>(localhost:3000)
    participant Client as WebSSH2 Client<br/>(Port 3000)
    participant Server as WebSSH2 Server<br/>(Port 2222)
    participant SSH as SSH Server<br/>(Port 22)

    Note over Browser,SSH: Development Data Flow
    
    Browser->>+Client: HTTP Request
    Client->>-Browser: Serve Client Files
    
    Browser->>+Client: WebSocket Connection
    Client->>+Server: Socket.IO Connection
    Server->>+SSH: SSH Connection
    
    Note over Browser,SSH: Bidirectional Communication
    
    SSH-->>-Server: SSH Data
    Server-->>-Client: Socket.IO Events
    Client-->>-Browser: WebSocket Events

Loading

File Watching and Auto-Reload

Both client and server components support file watching and automatic reloading:

• Client changes will trigger webpack to rebuild
• Server changes will trigger nodemon to restart

Important Notes

1. The server and client components must use Socket.IO v2.2.0 due to current Node.js v6.9.1 compatibility requirements
2. Client development server (3000) and WebSSH2 server (2222) must run simultaneously
3. CORS is automatically handled in development mode
4. The development configuration is only injected in development mode

Troubleshooting

If you encounter issues:

1. Ensure both servers are running (npm run watch in both directories)
2. Check the browser console for client-side errors
3. Check terminal output for server-side errors
4. Verify the ports (3000 and 2222) are available
5. Clear browser cache if changes aren't reflecting

Building for Production

When ready to build for production:

cd webssh2_client
npm run build

This will create production-ready files in the client/public directory without the development configuration injection.