{"id":19722229,"url":"https://github.com/kzamanbd/browser-terminal","last_synced_at":"2026-05-16T05:13:40.250Z","repository":{"id":251791667,"uuid":"838457971","full_name":"kzamanbd/browser-terminal","owner":"kzamanbd","description":"📝 Web SSH Client using ssh2, socket.io, xterm.js, and express. ⚡️","archived":false,"fork":false,"pushed_at":"2024-09-07T15:21:35.000Z","size":1311,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-10T16:25:05.599Z","etag":null,"topics":["socket-io","ssh","ssh-client","ssh2"],"latest_commit_sha":null,"homepage":"https://terminal-zit.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kzamanbd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-05T17:20:17.000Z","updated_at":"2024-09-07T15:21:38.000Z","dependencies_parsed_at":"2024-08-05T20:34:42.040Z","dependency_job_id":"6711d7a0-48e9-4497-8ef7-5583a0c56571","html_url":"https://github.com/kzamanbd/browser-terminal","commit_stats":null,"previous_names":["kzamanbd/browser-terminal"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kzamanbd%2Fbrowser-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kzamanbd%2Fbrowser-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kzamanbd%2Fbrowser-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kzamanbd%2Fbrowser-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kzamanbd","download_url":"https://codeload.github.com/kzamanbd/browser-terminal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241044281,"owners_count":19899491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["socket-io","ssh","ssh-client","ssh2"],"created_at":"2024-11-11T23:16:45.945Z","updated_at":"2026-05-16T05:13:40.242Z","avatar_url":"https://github.com/kzamanbd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌐 Browser Terminal\n\nA modern, full-stack web-based SSH terminal client that enables secure connections to remote servers through your browser. This is a full stack application with React and Node.js, built with NestJS, Socket.IO, and xterm.js for a seamless terminal experience.\n\n## 🚀 Features\n\n- **SSH Terminal**: Connect to remote servers through your browser\n- **Real-time Communication**: Socket.IO powered terminal interface\n- **Theme Support**: Multiple terminal themes with xterm.js addons\n- **Authentication**: Username/password and SSH key support\n- **Responsive Design**: Works on desktop and mobile devices\n- **Docker Ready**: Single image deployment with Nginx reverse proxy\n- **Hot Reload**: Development environment with live code updates\n\n## 🏗️ Architecture\n\n**Monorepo Structure:**\n\n- `apps/api` - NestJS backend with Socket.IO and SSH2\n- `apps/client` - React frontend with xterm.js terminal\n- Single Docker image with Nginx reverse proxy for production\n- Docker Compose setup for local development\n\n## 🛠️ Tech Stack\n\n**Frontend:** React 18, TypeScript, Vite, Tailwind CSS, xterm.js  \n**Backend:** NestJS, Socket.IO, ssh2, Node.js 22+  \n**DevOps:** Docker, pnpm, Turborepo, Nginx\n\n## 🚀 Quick Start\n\n### Using Docker Hub Image (Recommended)\n\n```bash\n# Run the complete application with a single command\ndocker run -p 8080:80 -p 8081:8081 kzamanbd/terminal:latest\n```\n\n- **Client Application**: `http://localhost:8080`\n- **API Server**: `http://localhost:8081`\n- **Health Check**: `http://localhost:8080/health`\n\n### Local Development\n\n1. **Clone and install**\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd browser-terminal\n   pnpm install\n   ```\n\n2. **Start development servers**\n\n   ```bash\n   # Option 1: Direct development (recommended)\n   pnpm dev    # Start both API (8081) and client (5173)\n   \n   # Option 2: Docker Compose development\n   pnpm docker:up     # Start with Docker Compose\n   ```\n\n3. **Access the application**\n\n   - **Client**: `http://localhost:5173` (Vite dev server)\n   - **API**: `http://localhost:8081` (NestJS server)\n   - **Health Check**: `http://localhost:8081/health`\n\n## 🐳 Docker Development\n\nThe project includes a complete Docker Compose setup for local development with hot reload:\n\n```bash\n# Start development environment\ndocker-compose up --build\n\n# Start in background\ndocker-compose up -d --build\n\n# Stop services\ndocker-compose down\n\n# View logs\ndocker-compose logs -f\n```\n\n**Development Services:**\n\n- **API**: `http://localhost:8081` (NestJS with watch mode)\n- **Client**: `http://localhost:5173` (Vite dev server)\n- **Health Check**: `http://localhost:8081/health`\n\n## 🚀 Usage\n\n1. **Connect to SSH Server**\n   - Enter server details (host, port, username)\n   - Provide authentication (password or SSH key)\n   - Click connect to start terminal session\n\n2. **Use the Terminal**\n   - Execute commands as in a regular terminal\n   - Switch themes and customize experience\n   - Real-time output with Socket.IO\n\n## 📋 Scripts\n\n### Root Level Scripts\n\n- `pnpm dev` - Start development servers (API + Client)\n- `pnpm build` - Build for production\n- `pnpm lint` - Run linting\n- `pnpm format` - Format code with Prettier\n- `pnpm docker:up` - Start with Docker Compose\n- `pnpm docker:down` - Stop Docker Compose services\n- `pnpm docker:build` - Build and push to Docker Hub\n\n### API Scripts (`apps/api`)\n\n- `pnpm dev` - Start with watch mode\n- `pnpm start` - Start production build\n- `pnpm build` - Build for production\n- `pnpm test` - Run tests\n\n### Client Scripts (`apps/client`)\n\n- `pnpm dev` - Start Vite dev server\n- `pnpm build` - Build for production\n- `pnpm preview` - Preview production build\n- `pnpm lint` - Run ESLint\n\n## 🐳 Docker Hub\n\n**Image:** `kzamanbd/terminal:latest`\n\n### Production Deployment\n\n```bash\n# Run in production (single container)\ndocker run -d \\\n  --name browser-terminal \\\n  -p 80:80 \\\n  -p 8081:8081 \\\n  kzamanbd/terminal:latest\n\n# With custom ports\ndocker run -d \\\n  --name browser-terminal \\\n  -p 8080:80 \\\n  -p 8081:8081 \\\n  kzamanbd/terminal:latest\n```\n\n### Build and Push\n\n```bash\n# Build and push new version\n./scripts/docker-build-push.sh v1.0.0\n\n# Or use npm script\npnpm docker:build\n```\n\n### Production Features\n\n- **Single Image**: Contains both API and client\n- **Nginx Reverse Proxy**: Serves client and proxies API requests\n- **Health Monitoring**: Built-in health check endpoint\n- **Optimized Build**: Multi-stage Docker build for minimal size\n- **Process Management**: Uses tini for proper signal handling\n\n## 🚀 Deployment Guide\n\n### Docker Compose Deployment\n\nCreate a `docker-compose.prod.yml` file:\n\n```yaml\nservices:\n  browser-terminal:\n    image: kzamanbd/terminal:latest\n    container_name: browser-terminal\n    restart: unless-stopped\n    ports:\n      - \"80:80\"      # Client (nginx)\n      - \"8081:8081\"  # API (direct access)\n    environment:\n      - NODE_ENV=production\n    healthcheck:\n      test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:80/health\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n    networks:\n      - app-network\n\nnetworks:\n  app-network:\n    driver: bridge\n```\n\nDeploy with:\n\n```bash\ndocker-compose -f docker-compose.prod.yml up -d\n```\n\n### Kubernetes Deployment\n\nCreate `k8s-deployment.yaml`:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: browser-terminal\nspec:\n  replicas: 2\n  selector:\n    matchLabels:\n      app: browser-terminal\n  template:\n    metadata:\n      labels:\n        app: browser-terminal\n    spec:\n      containers:\n      - name: browser-terminal\n        image: kzamanbd/terminal:latest\n        ports:\n        - containerPort: 80\n        - containerPort: 8081\n        env:\n        - name: NODE_ENV\n          value: \"production\"\n        livenessProbe:\n          httpGet:\n            path: /health\n            port: 80\n          initialDelaySeconds: 30\n          periodSeconds: 10\n        readinessProbe:\n          httpGet:\n            path: /health\n            port: 80\n          initialDelaySeconds: 5\n          periodSeconds: 5\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: browser-terminal-service\nspec:\n  selector:\n    app: browser-terminal\n  ports:\n    - name: http\n      port: 80\n      targetPort: 80\n    - name: api\n      port: 8081\n      targetPort: 8081\n  type: LoadBalancer\n```\n\nDeploy with:\n\n```bash\nkubectl apply -f k8s-deployment.yaml\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `NODE_ENV` | Environment mode | `production` |\n| `PORT` | API server port | `8081` |\n\n### Health Checks\n\nThe application provides health check endpoints:\n\n- **Client Health**: `GET /health` - Returns \"healthy\"\n- **API Health**: `GET /health` - Returns `{\"status\":\"ok\"}`\n\n### Monitoring\n\nMonitor your deployment:\n\n```bash\n# Check container health\ndocker ps\ndocker logs browser-terminal\n\n# Check API health\ncurl http://localhost:8081/health\n\n# Check client health\ncurl http://localhost/health\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n1. **Port Conflicts**\n\n   ```bash\n   # Check what's using the ports\n   lsof -i :80\n   lsof -i :8081\n   \n   # Use different ports\n   docker run -p 8080:80 -p 8081:8081 kzamanbd/terminal:latest\n   ```\n\n2. **Container Won't Start**\n\n   ```bash\n   # Check logs\n   docker logs browser-terminal\n   \n   # Check container status\n   docker ps -a\n   ```\n\n3. **API Not Responding**\n\n   ```bash\n   # Test API directly\n   curl http://localhost:8081\n   \n   # Check if container is running\n   docker exec -it browser-terminal ps aux\n   ```\n\n4. **Client Not Loading**\n\n   ```bash\n   # Check nginx status\n   docker exec -it browser-terminal nginx -t\n   \n   # Check if files are served\n   curl -I http://localhost\n   ```\n\n### Development Issues\n\n1. **Dependencies Not Installing**\n\n   ```bash\n   # Clear Docker cache\n   docker system prune -a\n   \n   # Rebuild without cache\n   docker-compose build --no-cache\n   ```\n\n2. **Hot Reload Not Working**\n\n   ```bash\n   # Ensure volume mounts are correct\n   docker-compose config\n   \n   # Check file permissions\n   docker-compose exec api ls -la /app/apps/api\n   ```\n\n## 📝 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 👨‍💻 Author\n\nKamruzzaman\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkzamanbd%2Fbrowser-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkzamanbd%2Fbrowser-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkzamanbd%2Fbrowser-terminal/lists"}