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

…ronment #370

DEVELOPMENT.md

@@ -0,0 +1,161 @@
+# 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:
+
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+cd webssh2_server
+```
+
+2. Start the server in development mode:
+
+```bash
+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:
+
+```bash
+cd webssh2_client
+```
+
+2. Start the client in development mode:
+
+```bash
+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`:
+
+```javascript
+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
+
+```mermaid
+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
+```
+
+## 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:
+
+```bash
+cd webssh2_client
+npm run build
+```
+
+This will create production-ready files in the `client/public` directory without the development configuration injection.

README.md

@@ -432,6 +432,7 @@ More to follow...
 - For security, use HTTPS when transmitting credentials via HTTP Basic Auth.
 - Terminal settings for `/ssh/host/:host` can be customized after login via `Menu | Settings` and persist across sessions.
 - You can enable debug from the console by passing the `DEBUG` environment variable to your start script: `DEBUG=webssh*,-webssh2:ssh2 npm run start`. The `webssh2:ssh2` namespace is very chatty and shows all of the SSH protocol information, the `-webssh2:ssh2` excludes that namespace from the line above, otherwise `DEBUG=webssh*` will capture all of the WebSSH2 specific bits. You may also debug Socket.IO and Express related events with `engine`, `socket` and `express` namespaces, or go for broke and debug everything with `DEBUG=*`.
+- For development information see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
 For more detailed information on configuration and usage, please refer to the full documentation or open an issue on GitHub.