Troubleshooting

Common issues and solutions for Dockhand

Common Issues

Installation Issues

Docker Socket Permission Denied

Problem: Cannot connect to Docker daemon.

Solution:

# Add user to docker group
sudo usermod -aG docker $USER

# Restart session or run
newgrp docker

# Verify docker socket permissions
ls -la /var/run/docker.sock

Port Already in Use

Problem: Default port 3000 is already occupied.

Solution:

# Change the port mapping
docker run -d \
  -p 8080:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  --name dockhand \
  fnsys/dockhand:latest

Connection Issues

Cannot Connect to Remote Docker Host

Problem: Remote environment fails to connect.

Solution:

1. Verify SSH access:
   ssh user@remote-host docker ps
   
2. Check Docker daemon is listening on TCP:
   # On remote host
   sudo systemctl status docker
   
3. Ensure firewall allows connections
4. Use SSH tunnel if direct access is blocked:
   ssh -L 2375:localhost:2375 user@remote-host
   

WebSocket Connection Failed

Problem: Real-time updates not working.

Solution:

• Check browser console for errors
• Verify reverse proxy WebSocket support (nginx/traefik)
• For nginx, add:
  location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
  

Container Management

Container Won’t Start

Problem: Container fails to start or immediately exits.

Solution:

1. Check container logs in Dockhand
2. Verify port conflicts:
   docker ps -a
   netstat -tulpn | grep <port>
   
3. Check resource limits (CPU/memory)
4. Verify volume mount paths exist

Stack Deployment Fails

Problem: Docker Compose stack fails to deploy.

Solution:

1. Validate compose file syntax:
   docker compose -f compose.yml config
   
2. Check for:
   • Missing environment variables
   • Invalid volume paths
   • Network conflicts
   • Image availability
3. Review stack logs in Activity tab

Git Integration

Git Clone Fails

Problem: Cannot clone repository for stack deployment.

Solution:

1. For private repos, add SSH key or credentials
2. Verify Git URL format:
   • SSH: [e-mail]:user/repo.git
   • HTTPS: https://github.com/user/repo.git
3. Check network connectivity from container
4. For self-signed certificates:
   git config --global http.sslVerify false
   

Webhook Not Triggering

Problem: Git webhook doesn’t update stack.

Solution:

1. Verify webhook URL is accessible from Git provider
2. Check webhook secret matches
3. Review Activity logs for webhook events
4. Ensure Dockhand is accessible via public URL/domain

Database Issues

SQLite Database Locked

Problem: Database operations fail with “database is locked” error.

Solution:

# Restart Dockhand container
docker restart dockhand

# If persists, check for stale locks
sqlite3 /data/dockhand.db "PRAGMA busy_timeout=30000;"

Migration Fails

Problem: Database migration errors on startup.

Solution:

1. Backup database before attempting fix
2. Check logs for specific migration error
3. For corrupted database:
   # Backup first
   cp /data/dockhand.db /data/dockhand.db.backup
   
   # Check integrity
   sqlite3 /data/dockhand.db "PRAGMA integrity_check;"
   

Authentication Issues

Forgot Admin Password

Problem: Cannot login to Dockhand.

Solution:

# Reset admin password via container
docker exec -it dockhand bun scripts/reset-password.js admin

OIDC Login Fails

Problem: SSO authentication not working.

Solution:

1. Verify OIDC configuration:
   • Client ID and secret
   • Redirect URI matches: https://your-domain/auth/callback
   • Scopes include openid, profile, email
2. Check provider configuration
3. Review browser console and Dockhand logs

Performance Issues

High Memory Usage

Problem: Dockhand container consuming excessive memory.

Solution:

1. Check number of containers being monitored
2. Reduce log retention period in Settings
3. Set memory limits:
   docker update --memory=512m --memory-swap=1g dockhand
   

Slow UI Response

Problem: Interface is sluggish or unresponsive.

Solution:

1. Check Docker daemon performance
2. Reduce polling intervals in Settings
3. Clear browser cache
4. For remote hosts, check network latency

Data Persistence

Data Lost After Restart

Problem: Settings and configurations don’t persist.

Solution:

# Ensure volume is mounted correctly
docker run -d \
  -p 3000:3000 \
  -v dockhand_data:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name dockhand \
  fnsys/dockhand:latest

# Verify volume exists
docker volume ls | grep dockhand

Getting Help

If you’re still experiencing issues:

1. Check the FAQ for additional answers
2. Review logs:
   docker logs dockhand
   
3. Enable debug mode:
   docker run -e DEBUG=true ...
   
4. Search existing GitHub Issues
5. Create a new issue with:
   • Dockhand version
   • Docker version
   • Host OS
   • Complete error messages
   • Steps to reproduce

Diagnostic Commands

Useful commands for troubleshooting:

# Check Dockhand status
docker ps -f name=dockhand

# View logs
docker logs -f dockhand

# Inspect container
docker inspect dockhand

# Check resource usage
docker stats dockhand

# Verify Docker socket
docker version

# Test Docker API
curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers/json

# Check network connectivity
docker exec dockhand ping -c 4 8.8.8.8

# Database integrity (SQLite)
docker exec dockhand sqlite3 /data/dockhand.db "PRAGMA integrity_check;"