Skip to content

Troubleshooting

Solutions to common issues with DataSci Homelab.

Quick Diagnostics

Run these commands to diagnose issues:

# Check container status
docker-compose ps

# View recent logs
docker-compose logs --tail=100

# Check container health
docker inspect datasci-homelab --format='{{.State.Health.Status}}'

# Test services inside container
docker-compose exec homelab curl -s http://localhost:8787 | head
docker-compose exec homelab curl -s http://localhost:8888 | head

Container Issues

Container Won't Start

Symptom: docker-compose up fails or container exits immediately.

Check logs: 

docker-compose logs

Common causes:

Error: bind: address already in use

Fix: Change ports in .env: 

RSTUDIO_PORT=8780
JUPYTER_PORT=8880


Error: cannot allocate memory

Fix: Increase Docker memory allocation: - Docker Desktop → Settings → Resources → Memory → Increase to 8GB+

Error: permission denied

Fix: 

chmod -R 755 volumes/
chmod +x scripts/*.sh


Error: manifest unknown

Fix: 

docker-compose pull

Container Keeps Restarting

Check why it's failing: 

docker-compose logs --tail=50

Common causes:

  • Service crash inside container
  • Health check failing
  • Resource exhaustion

Fix: Try running without health check: 

docker-compose run --rm --no-healthcheck homelab

Container Running But Services Not Accessible

Verify services are listening: 

docker-compose exec homelab ss -tlnp

Expected output shows ports 8787 and 8888 listening.

Check port mapping: 

docker port datasci-homelab

RStudio Issues

RStudio Login Fails

Symptom: Correct password rejected.

Reset password: 

docker-compose exec homelab bash -c 'echo "$RSTUDIO_USER:newpassword" | sudo chpasswd'

Check current user: 

docker-compose exec homelab whoami
docker-compose exec homelab echo $RSTUDIO_USER

RStudio Blank Screen

Clear session data: 

rm -rf volumes/home/.local/share/rstudio/sessions/*
rm -rf volumes/home/.rstudio/
docker-compose restart

RStudio "Unable to Connect to Service"

Check RStudio process: 

docker-compose exec homelab pgrep -a rserver

Restart RStudio only: 

docker-compose exec -u root homelab pkill rserver
docker-compose exec homelab sudo /usr/lib/rstudio-server/bin/rserver &

Package Installation Fails

Missing system dependency: 

# Error message like:
# ERROR: configuration failed for package 'xxx'
# package 'xxx' requires 'libyyy'

Fix: 

docker-compose exec -u root homelab apt-get update
docker-compose exec -u root homelab apt-get install -y libyyy-dev

Then retry installation in R.

Packages Not Persisting

Check volume mount: 

docker-compose exec homelab ls -la /usr/local/lib/R/site-library/

Verify .libPaths() includes the volume: 

.libPaths()
# Should include: /usr/local/lib/R/site-library

Jupyter Issues

Jupyter Token Not Working

Get current token: 

docker-compose exec homelab jupyter server list

Or check logs: 

docker-compose logs homelab | grep -i token

Set a new token: Update JUPYTER_TOKEN in .env and restart: 

docker-compose down
docker-compose up -d

Kernel Not Starting

List available kernels: 

docker-compose exec homelab jupyter kernelspec list

Reinstall Python kernel: 

docker-compose exec homelab python -m ipykernel install --user --name python3

Reinstall R kernel: 

docker-compose exec homelab Rscript -e "IRkernel::installspec(user = TRUE)"

Jupyter Extensions Not Loading

Rebuild JupyterLab: 

docker-compose exec homelab jupyter lab build

Check extension status: 

docker-compose exec homelab jupyter labextension list

Notebook Won't Save

Check permissions: 

docker-compose exec homelab ls -la /home/rstudio/

Fix permissions: 

docker-compose exec -u root homelab chown -R rstudio:rstudio /home/rstudio/

Volume Issues

Data Disappeared

Volumes only deleted with -v flag: 

docker-compose down    # Data persists
docker-compose down -v # Data deleted!

Check volumes exist: 

ls -la volumes/

Recover from backup: 

tar -xzf backup.tar.gz

Volume Permissions Wrong

Symptom: "Permission denied" when accessing files.

Fix: 

docker-compose exec -u root homelab chown -R rstudio:rstudio /home/rstudio/
docker-compose exec -u root homelab chown -R rstudio:rstudio /usr/local/lib/R/site-library/

Volume Mount Not Working

Verify mount points: 

docker-compose exec homelab df -h
docker-compose exec homelab mount | grep volumes

Check docker-compose.yml syntax: 

volumes:
  - ./volumes/home:/home/rstudio  # Note the ./ prefix

Network Issues

Can't Access from Other Devices

By default, only accessible from localhost.

Allow LAN access: Edit .env: 

RSTUDIO_PORT=0.0.0.0:8787:8787

Or modify docker-compose.yml: 

ports:
  - "0.0.0.0:8787:8787"

Firewall Blocking Access

macOS: - System Preferences → Security → Firewall → Allow Docker

Linux: 

sudo ufw allow 8787
sudo ufw allow 8888

Slow Connection

Check if health checks are failing: 

docker inspect datasci-homelab --format='{{json .State.Health}}'

Reduce logging: 

docker-compose logs --tail=10  # Fewer lines

Performance Issues

RStudio/Jupyter Slow

Check resource usage: 

docker stats datasci-homelab

Increase resources in Docker Desktop: - Memory: 8GB minimum, 16GB recommended - CPUs: 4+ recommended

Check for runaway processes: 

docker-compose exec homelab top

High Disk Usage

Check volume sizes: 

du -sh volumes/*

Clean package cache: 

# R package cache
docker-compose exec homelab rm -rf /tmp/Rtmp*

# Python package cache
docker-compose exec homelab pip cache purge

Recovery Procedures

Complete Reset (Last Resort)

This Deletes All Data

Only use if nothing else works.

# Stop everything
docker-compose down -v

# Remove volumes directory
rm -rf volumes/

# Re-run setup
./scripts/setup.sh

# Pull fresh image
docker-compose pull

# Start fresh
docker-compose up -d

Partial Reset (Keep Data)

# Stop container
docker-compose down

# Remove container (not volumes)
docker rm datasci-homelab

# Pull fresh image
docker-compose pull

# Start fresh container with existing volumes
docker-compose up -d

Export Data Before Reset

# Backup everything
tar -czf full-backup.tar.gz volumes/

# Backup just home directory
tar -czf home-backup.tar.gz volumes/home/

# Backup package lists
./scripts/backup-packages.sh

Getting Help

Information to Include

When asking for help, include:

  1. Docker version: docker --version
  2. Compose version: docker-compose --version
  3. OS and architecture: uname -a
  4. Container logs: docker-compose logs --tail=100
  5. Container status: docker-compose ps
  6. Error messages: Exact text, not paraphrased

Where to Get Help

  • GitHub Issues
  • Search existing issues first
  • Provide reproduction steps

Debug Mode

Run container in foreground to see all output:

docker-compose up  # No -d flag

Run a shell inside the container:

docker-compose exec homelab bash

Run as root for debugging:

docker-compose exec -u root homelab bash