feat: Add various tools for document processing and management
- Introduced `docx-extractor` for extracting content and metadata from Word .docx files. - Added `docx2md` for converting Word .docx files to Markdown format. - Implemented `gpt` for generating text using OpenAI's GPT models. - Created `html2text` for converting HTML content to plain text. - Developed `mbox2eml` for converting MBOX mailbox files to individual .eml files. - Added `md2pdf` for converting Markdown files to PDF format. - Introduced `mdscraper` for combining text files into a single markdown document. - Created `pdf-extractor` for extracting content and metadata from PDF files. - Developed `pdf2md` for converting PDF files to Markdown format. - Implemented `protonmail` for managing ProtonMail emails via Bridge. - Added `schedule` for managing systemd timers and services. - Introduced `search` for managing searchable collections of files. - Added `text-extractor` for extracting content and metadata from text files. - Removed outdated recommendations document.
This commit is contained in:
219
components/devbox-connect/README.md
Normal file
219
components/devbox-connect/README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# devbox-connect
|
||||
|
||||
SSH tunnel manager for connecting local ports to your devbox.
|
||||
|
||||
## Features
|
||||
|
||||
- **Simple YAML configuration** - Define tunnels in a readable config file
|
||||
- **Auto-reconnect** - Automatically reconnects with exponential backoff when connections drop
|
||||
- **Multiple tunnels** - Manage many port forwards to one or more hosts
|
||||
- **Windows service support** - Run as a background service with auto-start
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Install with uv
|
||||
uv tool install git+https://github.com/YOUR_USERNAME/devbox-connect
|
||||
|
||||
# Or install from local directory
|
||||
cd devbox-connect
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Create a configuration file `tunnels.yaml`:
|
||||
|
||||
```yaml
|
||||
user: your-username
|
||||
key_file: ~/.ssh/id_rsa
|
||||
|
||||
tunnels:
|
||||
- name: web-dev
|
||||
host: devbox.example.com
|
||||
remote_port: 8080
|
||||
|
||||
- name: database
|
||||
host: devbox.example.com
|
||||
remote_port: 5432
|
||||
```
|
||||
|
||||
2. Start the tunnels:
|
||||
|
||||
```bash
|
||||
devbox-connect -c tunnels.yaml start
|
||||
```
|
||||
|
||||
3. Access your devbox services locally:
|
||||
- `localhost:8080` → devbox:8080
|
||||
- `localhost:5432` → devbox:5432
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
devbox-connect [-c CONFIG] COMMAND
|
||||
|
||||
Commands:
|
||||
start Start tunnels and keep running (default)
|
||||
status Show configured tunnels
|
||||
validate Validate configuration file
|
||||
|
||||
Options:
|
||||
-c, --config PATH Path to config file (default: tunnels.yaml)
|
||||
-v, --verbose Enable verbose output
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
See `tunnels.example.yaml` for a complete example.
|
||||
|
||||
### Simple Format (single host)
|
||||
|
||||
```yaml
|
||||
user: username
|
||||
key_file: ~/.ssh/id_rsa # Optional
|
||||
|
||||
tunnels:
|
||||
- name: web
|
||||
host: devbox.example.com
|
||||
remote_port: 8080
|
||||
local_port: 8080 # Optional, defaults to remote_port
|
||||
|
||||
- name: jupyter
|
||||
host: devbox.example.com
|
||||
remote_port: 8888
|
||||
local_port: 9999 # Use different local port
|
||||
```
|
||||
|
||||
### Grouped Format (multiple hosts)
|
||||
|
||||
```yaml
|
||||
hosts:
|
||||
- host: devbox1.example.com
|
||||
user: username
|
||||
tunnels:
|
||||
- name: web
|
||||
remote_port: 8080
|
||||
|
||||
- host: devbox2.example.com
|
||||
user: username
|
||||
tunnels:
|
||||
- name: api
|
||||
remote_port: 3000
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `user` | SSH username | (required) |
|
||||
| `host` | Remote hostname | (required) |
|
||||
| `key_file` | Path to SSH private key | SSH agent/default |
|
||||
| `remote_port` | Port on remote host | (required) |
|
||||
| `local_port` | Local port to listen on | Same as remote_port |
|
||||
| `remote_host` | Host on remote side | `localhost` |
|
||||
| `reconnect_delay` | Initial reconnect delay (seconds) | `5` |
|
||||
| `max_reconnect_delay` | Max reconnect delay | `60` |
|
||||
|
||||
### Forwarding Through Devbox
|
||||
|
||||
You can access services on other hosts through your devbox:
|
||||
|
||||
```yaml
|
||||
tunnels:
|
||||
- name: internal-db
|
||||
host: devbox.example.com
|
||||
remote_port: 5432
|
||||
remote_host: internal-db.corp # Accessed via devbox
|
||||
```
|
||||
|
||||
## Windows Service
|
||||
|
||||
To run devbox-connect as a Windows service that starts automatically:
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Install NSSM (Non-Sucking Service Manager):
|
||||
```powershell
|
||||
winget install nssm
|
||||
```
|
||||
|
||||
2. Install devbox-connect:
|
||||
```powershell
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
### Install Service
|
||||
|
||||
Run PowerShell as Administrator:
|
||||
|
||||
```powershell
|
||||
.\service\install-service.ps1 -ConfigPath C:\path\to\tunnels.yaml
|
||||
```
|
||||
|
||||
### Manage Service
|
||||
|
||||
```powershell
|
||||
# Check status
|
||||
Get-Service DevboxConnect
|
||||
|
||||
# Start/Stop
|
||||
Start-Service DevboxConnect
|
||||
Stop-Service DevboxConnect
|
||||
|
||||
# View logs
|
||||
Get-Content $env:LOCALAPPDATA\devbox-connect\service.log -Tail 50
|
||||
|
||||
# Uninstall
|
||||
.\service\install-service.ps1 -Uninstall
|
||||
```
|
||||
|
||||
### Manual Run (without service)
|
||||
|
||||
```batch
|
||||
service\run-manual.bat C:\path\to\tunnels.yaml
|
||||
```
|
||||
|
||||
## SSH Key Setup
|
||||
|
||||
devbox-connect uses SSH key authentication. Ensure your key is set up:
|
||||
|
||||
1. Generate a key (if needed):
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -f ~/.ssh/devbox_key
|
||||
```
|
||||
|
||||
2. Copy to devbox:
|
||||
```bash
|
||||
ssh-copy-id -i ~/.ssh/devbox_key user@devbox.example.com
|
||||
```
|
||||
|
||||
3. Reference in config:
|
||||
```yaml
|
||||
key_file: ~/.ssh/devbox_key
|
||||
```
|
||||
|
||||
Or use SSH agent (key_file not needed if agent has your key loaded).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection refused
|
||||
- Check the remote service is running on the specified port
|
||||
- Verify you can SSH to the host manually: `ssh user@devbox`
|
||||
|
||||
### Permission denied
|
||||
- Check your SSH key is correct and has proper permissions
|
||||
- On Windows, ensure key file isn't world-readable
|
||||
|
||||
### Port already in use
|
||||
- Change `local_port` to an unused port
|
||||
- Check what's using the port: `netstat -an | findstr :8080`
|
||||
|
||||
### Tunnels disconnect frequently
|
||||
- Check network stability
|
||||
- Increase `reconnect_delay` and `max_reconnect_delay`
|
||||
- Some networks/firewalls drop idle connections; the remote service may need keepalive
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user