Common Issues and Solutions

Quick solutions to the most frequent problems encountered with NazDocker Lab.

🚨 Container Won’t Start

Check Logs 

# View detailed logs
docker-compose -f docker-compose.ubuntu.yml logs

# Follow logs in real-time
docker-compose -f docker-compose.ubuntu.yml logs -f

# Check specific container logs
docker-compose -f docker-compose.ubuntu.yml logs lab-environment-ubuntu

Common Causes and Solutions

1. Port Already in Use 

# Check if port 2222 is in use
netstat -tulpn | grep :2222
lsof -i :2222

# Kill process using the port
sudo kill -9 <PID>

# Or change port in docker-compose.ubuntu.yml
# ports:
#   - "2223:22"  # Use different port

2. Insufficient Disk Space 

# Check disk space
df -h

# Clean up Docker
docker system prune -a

# Remove unused images
docker image prune -a

3. Docker Service Not Running 

# Check Docker service status
sudo systemctl status docker

# Start Docker service
sudo systemctl start docker

# Enable Docker service
sudo systemctl enable docker

🔌 SSH Connection Issues

Connection Refused 

# Check if container is running
docker-compose -f docker-compose.ubuntu.yml ps

# Check SSH service
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh status

# Restart SSH service
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh restart

# Check port mapping
docker port student-lab-ubuntu

Authentication Failed 

# Check user accounts
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu bash -c "
cat /etc/passwd | grep -E ':(/bin/bash|/bin/sh)$'
"

# Reset password
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu bash -c "
echo 'admin:admin123' | chpasswd
"

# Check SSH configuration
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu cat /etc/ssh/sshd_config

Wrong Port 

# Check which port is mapped
docker port student-lab-ubuntu

# Connect to correct port
ssh admin@localhost -p <CORRECT_PORT>

🌐 Network Connectivity Issues

Container Can’t Reach Internet 

# Test network connectivity
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu ping google.com

# Check DNS resolution
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu nslookup google.com

# Check network interfaces
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu ifconfig

Playit.gg Tunnel Issues 

# Check if secret key is loaded
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu env | grep PLAYIT

# Restart playit.gg service
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu pkill playit-agent

# Check tunnel logs
docker-compose -f docker-compose.ubuntu.yml logs lab-environment-ubuntu | grep -i "playit"

⚙️ Environment Variable Issues

Variables Not Loading 

# Check if .env file exists
ls -la .env

# Verify .env file syntax
cat .env | grep -v "^#" | grep -v "^$"

# Check if variables are loaded
docker-compose -f docker-compose.ubuntu.yml config | grep -E "(PLAYIT_SECRET_KEY|ADMIN_PASSWORD|USER_PASSWORD|ROOT_PASSWORD)"

# Recreate .env file if corrupted
cp .env.example .env

Invalid Configuration 

# Validate configuration
docker-compose -f docker-compose.ubuntu.yml config

# Check specific variables
docker-compose -f docker-compose.ubuntu.yml config | grep PLAYIT_SECRET_KEY

# Export configuration for review
docker-compose -f docker-compose.ubuntu.yml config > resolved-config.yml

💾 Data Persistence Issues

User Data Not Persisting 

# Check volume mounts
docker inspect student-lab-ubuntu | grep -A 10 "Mounts"

# Check data directory permissions
ls -la data/alpine/
ls -la data/ubuntu/

# Recreate data directories
mkdir -p data/{alpine,ubuntu}/{admin,user1,user2,user3,user4,user5}
chmod 755 data/

Permission Issues 

# Fix data directory permissions
sudo chown -R $USER:$USER data/
chmod 755 data/

# Fix container permissions
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu bash -c "
chown -R admin:admin /home/admin
chown -R user1:user1 /home/user1
# ... repeat for all users
"

🏥 Health Check Issues

Container Shows as Unhealthy 

# Check health status
docker ps --format "table \t\t"

# View health check logs
docker inspect student-lab-ubuntu | grep -A 20 "Health"

# Test SSH service manually
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh status

# Restart SSH service
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh restart

Health Check Configuration 

# View health check configuration
docker inspect student-lab-ubuntu | grep -A 10 "Healthcheck"

# Test health check command
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh status

🔧 Performance Issues

High Resource Usage 

# Check resource usage
docker stats student-lab-ubuntu

# Check container performance
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu top

# Check disk usage
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu df -h

Slow Startup 

# Check startup logs
docker-compose -f docker-compose.ubuntu.yml logs lab-environment-ubuntu | grep -i "start"

# Monitor startup process
docker-compose -f docker-compose.ubuntu.yml logs -f lab-environment-ubuntu

🧹 Cleanup Issues

Container Won’t Remove 

# Force remove container
docker rm -f student-lab-ubuntu

# Remove with volumes
docker-compose -f docker-compose.ubuntu.yml down -v

# Remove all related resources
docker-compose -f docker-compose.ubuntu.yml down -v --remove-orphans --rmi all

Image Cleanup 

# Remove unused images
docker image prune -a

# Remove all images
docker rmi $(docker images -q)

# Clean up everything
docker system prune -a --volumes

🔐 Alpine Sudo Issues

Admin User Can’t Use Sudo 

# Check if admin is in wheel group (Alpine)
docker-compose -f docker-compose.alpine.yml exec lab-environment-alpine groups admin

# Check sudoers configuration
docker-compose -f docker-compose.alpine.yml exec lab-environment-alpine cat /etc/sudoers

# Fix sudo configuration for Alpine (if needed)
docker-compose -f docker-compose.alpine.yml exec lab-environment-alpine bash -c "
if ! grep -q '%wheel ALL=(ALL) ALL' /etc/sudoers; then
    echo '%wheel ALL=(ALL) ALL' >> /etc/sudoers
    echo 'Sudo configuration fixed for Alpine'
else
    echo 'Sudo configuration already correct'
fi
"

# Test sudo access
docker-compose -f docker-compose.alpine.yml exec lab-environment-alpine bash -c "
sudo whoami
"

Alpine vs Ubuntu Sudo Differences

  • Alpine: Uses wheel group, requires %wheel ALL=(ALL) ALL in sudoers
  • Ubuntu: Uses sudo group, requires %sudo ALL=(ALL:ALL) ALL in sudoers

Permanent Fix: Rebuild Alpine Container 

# The fix is already in Dockerfile.alpine - rebuild to apply
docker-compose -f docker-compose.alpine.yml down
docker-compose -f docker-compose.alpine.yml build --no-cache
docker-compose -f docker-compose.alpine.yml up -d

# Test sudo access after rebuild
docker-compose -f docker-compose.alpine.yml exec lab-environment-alpine bash -c "
sudo whoami && echo 'Sudo access confirmed'
"

Root Cause

The issue was in the Alpine Dockerfile - while the admin user was correctly added to the wheel group, the sudoers file wasn’t configured to allow the wheel group to use sudo. This has been fixed in Dockerfile.alpine by adding:

RUN addgroup admin wheel && \
    echo "%wheel ALL=(ALL) ALL" >> /etc/sudoers

🔍 Diagnostic Commands

Quick Health Check 

#!/bin/bash
# quick-diagnostic.sh

echo "=== Quick Diagnostic ==="
echo ""

echo "1. Container Status:"
docker-compose -f docker-compose.ubuntu.yml ps
echo ""

echo "2. Health Status:"
docker ps --format "table \t\t"
echo ""

echo "3. Recent Logs:"
docker-compose -f docker-compose.ubuntu.yml logs --tail=10 lab-environment-ubuntu
echo ""

echo "4. Resource Usage:"
docker stats --no-stream student-lab-ubuntu
echo ""

echo "5. SSH Service:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh status
echo ""

echo "6. Network Connectivity:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu ping -c 1 google.com
echo ""

Comprehensive Diagnostic 

#!/bin/bash
# comprehensive-diagnostic.sh

echo "=== Comprehensive Diagnostic ==="
echo ""

echo "1. System Information:"
docker version
docker-compose --version
echo ""

echo "2. Container Details:"
docker inspect student-lab-ubuntu | grep -E "(State|Health|Mounts|NetworkSettings)"
echo ""

echo "3. Environment Variables:"
docker-compose -f docker-compose.ubuntu.yml config | grep -E "(PLAYIT_SECRET_KEY|ADMIN_PASSWORD|USER_PASSWORD|ROOT_PASSWORD)"
echo ""

echo "4. User Accounts:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu bash -c "cat /etc/passwd | grep -E ':(/bin/bash|/bin/sh)$'"
echo ""

echo "5. Disk Usage:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu df -h
echo ""

echo "6. Memory Usage:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu free -h
echo ""

echo "7. Network Interfaces:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu ifconfig
echo ""

echo "8. SSH Configuration:"
docker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu cat /etc/ssh/sshd_config | grep -E "(PasswordAuthentication|PermitRootLogin|PubkeyAuthentication)"
echo ""

🔗 Related Topics