czyt/virtualhere-server repository overview

⁠VirtualHere USB Server Docker

A Docker container for running VirtualHere USB Server with pre-downloaded binaries, supporting multiple architectures with dedicated Dockerfiles.

⁠Features

• 🚀 Pre-downloaded binaries - Architecture-specific binaries downloaded during build
• 🏗️ Multi-architecture support - Separate Dockerfiles for AMD64, ARM64, ARM
• 🔄 Automated builds - GitHub Actions CI/CD pipeline
• 📦 Multi-registry publishing - Docker Hub and GitHub Container Registry
• 🔒 Security scanning - Automated vulnerability scanning with Trivy
• 📊 Health checks - Built-in container health monitoring
• 🏷️ Simple tagging - Only latest and release tags

⁠Quick Start

⁠Architecture-Specific Images

Choose the appropriate image for your system:

# For AMD64/x86_64 systems
docker run -d --name virtualhere --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  -v virtualhere-data:/data \
  -p 7575:7575 \
  yourusername/virtualhere-server:latest-amd64

# For ARM64 systems (Raspberry Pi 4, Apple Silicon, etc.)
docker run -d --name virtualhere --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  -v virtualhere-data:/data \
  -p 7575:7575 \
  yourusername/virtualhere-server:latest-arm64

# For ARM systems (Raspberry Pi 3 and older)
docker run -d --name virtualhere --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  -v virtualhere-data:/data \
  -p 7575:7575 \
  yourusername/virtualhere-server:latest-arm

⁠Multi-Architecture Image (Recommended)

The multi-arch manifest automatically selects the correct image:

docker run -d --name virtualhere --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  -v virtualhere-data:/data \
  -p 7575:7575 \
  yourusername/virtualhere-server:latest

⁠Available Tags

⁠Docker Hub & GitHub Container Registry

⁠Registry URLs

• Docker Hub: yourusername/virtualhere-server:latest
• GitHub Container Registry: ghcr.io/yourusername/virtualhere-server:latest

⁠Architecture Detection

The system automatically selects the appropriate image based on your architecture:

• x86_64 → latest-amd64 (Intel/AMD 64-bit)
• aarch64 → latest-arm64 (ARM 64-bit)
• armv7l → latest-arm (ARM 32-bit)

⁠Project Structure

.
├── Dockerfile.amd64          # AMD64 specific build
├── Dockerfile.arm64          # ARM64 specific build
├── Dockerfile.arm            # ARM specific build
├── start-virtualhere.sh      # Startup script (shared)
├── docker-compose.yml        # Docker Compose config
├── .github/
│   └── workflows/
│       └── build.yml         # CI/CD pipeline
└── README.md

⁠Building from Source

⁠Prerequisites

• Docker with BuildKit support
• Git

⁠Build Commands

# Clone the repository
git clone https://github.com/yourusername/virtualhere-docker.git
cd virtualhere-docker

# Build for specific architecture
docker build -f Dockerfile.amd64 -t virtualhere-server:amd64 .
docker build -f Dockerfile.arm64 -t virtualhere-server:arm64 .
docker build -f Dockerfile.arm -t virtualhere-server:arm .

# Build for current architecture (auto-detect)
ARCH=$(uname -m)
case "$ARCH" in
  x86_64) docker build -f Dockerfile.amd64 -t virtualhere-server . ;;
  aarch64) docker build -f Dockerfile.arm64 -t virtualhere-server . ;;
  armv7l) docker build -f Dockerfile.arm -t virtualhere-server . ;;
esac

⁠GitHub Actions Setup

To enable automated builds, configure these secrets in your GitHub repository:

The workflow will automatically:

• Build multi-architecture images on push to main branch
• Create releases on git tags
• Perform weekly builds to get latest VirtualHere binaries
• Run security scans with Trivy

⁠Troubleshooting

⁠Container won't start

1. Check if the container has USB access:

   docker exec virtualhere lsusb
   

   Copy

2. Verify USB devices are mounted:

   ls -la /dev/bus/usb/
   

   Copy

⁠No USB devices detected

1. Ensure the host has USB devices connected
2. Check container is running with --privileged or proper device access
3. Verify udev rules on the host system

⁠Connection issues

1. Check if port 7575 is accessible:

   netstat -tuln | grep 7575
   

   Copy

2. Verify firewall settings on the host

3. Test connection from VirtualHere client

⁠Logs and Debugging

# View container logs
docker logs virtualhere

# Interactive shell access
docker exec -it virtualhere /bin/bash

# Check running processes
docker exec virtualhere ps aux

⁠Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test them
4. Submit a pull request

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Acknowledgments

• VirtualHere⁠ for the excellent USB sharing software
• The Docker community for best practices and tools

⁠Support

• 📖 VirtualHere Documentation⁠
• 🐛 Report Issues⁠
• 💬 Discussions⁠