{"id":29995192,"url":"https://github.com/nazdridoy/nazdocker-lab","last_synced_at":"2026-05-04T13:38:05.810Z","repository":{"id":308155460,"uuid":"1031504734","full_name":"nazdridoy/nazdocker-lab","owner":"nazdridoy","description":"NazDocker Lab - Containerized dev environment with SSH \u0026 multi-user support","archived":false,"fork":false,"pushed_at":"2025-08-05T19:32:06.000Z","size":180,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T11:39:43.147Z","etag":null,"topics":["docker","docker-compose","lab","linux","playit-gg","ssh","ubuntu"],"latest_commit_sha":null,"homepage":"https://nazdridoy.github.io/nazdocker-lab/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nazdridoy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-03T22:04:45.000Z","updated_at":"2025-08-08T18:45:27.000Z","dependencies_parsed_at":"2025-08-04T15:57:01.493Z","dependency_job_id":null,"html_url":"https://github.com/nazdridoy/nazdocker-lab","commit_stats":null,"previous_names":["nazdridoy/nazdocker-lab"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/nazdridoy/nazdocker-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nazdridoy%2Fnazdocker-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nazdridoy%2Fnazdocker-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nazdridoy%2Fnazdocker-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nazdridoy%2Fnazdocker-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nazdridoy","download_url":"https://codeload.github.com/nazdridoy/nazdocker-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nazdridoy%2Fnazdocker-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32610257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","lab","linux","playit-gg","ssh","ubuntu"],"created_at":"2025-08-05T01:31:13.954Z","updated_at":"2026-05-04T13:38:05.780Z","avatar_url":"https://github.com/nazdridoy.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NazDocker Lab\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Docker](https://img.shields.io/badge/Docker-Required-blue.svg)](https://www.docker.com/)\n[![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04-orange.svg)](https://ubuntu.com/)\n[![Alpine](https://img.shields.io/badge/Alpine-3.22-lightblue.svg)](https://alpinelinux.org/)\n[![Documentation](https://img.shields.io/badge/Documentation-Complete-brightgreen.svg)](https://nazdridoy.github.io/nazdocker-lab/)\n\nA secure, containerized development environment for educational and development purposes. This project provides a Docker-based lab environment with SSH access, multiple user accounts, and development tools, designed for learning, testing, and development workflows.\n\n## 🚀 Features\n\n- **🔐 Multi-User Environment**: 6 pre-configured user accounts (admin + 5 regular users)\n- **🌐 Public SSH Access**: Secure remote access via playit.gg tunneling\n- **🛠️ Development Tools**: Python 3.x, Node.js, Git, and essential utilities\n- **💾 Persistent Storage**: User data persists across container restarts with separate volumes for Alpine and Ubuntu\n- **⚙️ Runtime Configuration**: Environment-based configuration management\n- **🔒 Security Focused**: Proper user isolation and SSH key support\n- **🔑 SSH Key Synchronization**: Shared SSH host keys between Alpine and Ubuntu containers\n- **🏥 Health Monitoring**: Built-in health checks for SSH service availability\n- **🏔️ Alpine \u0026 Ubuntu Support**: Choose between lightweight Alpine (173MB) or full Ubuntu (968MB)\n\n## 📋 Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/) (version 20.10 or higher)\n- [Docker Compose](https://docs.docker.com/compose/install/) (version 2.0 or higher)\n- [Git](https://git-scm.com/downloads) for cloning the repository\n\n## 🏃‍♂️ Quick Start\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/nazdridoy/nazdocker-lab.git\ncd nazdocker-lab\n```\n\n### 2. Set Up Environment\n```bash\n# Create separate data directories for Alpine and Ubuntu\nmkdir -p data/{alpine,ubuntu}/{admin,user1,user2,user3,user4,user5}\nmkdir -p logs/{alpine,ubuntu}\n\n# Generate SSH host keys (optional - will be auto-generated if missing)\n./scripts/manage-ssh-keys.sh generate\n\n# Configure environment variables\ncp .env.example .env\n# Edit .env with your configuration\n```\n\n### 3. Start the Environment\n\nChoose your preferred version:\n\n**Ubuntu Version (Recommended for Development):**\n```bash\ndocker-compose -f docker-compose.ubuntu.yml up -d\n```\n\n**Alpine Version (Recommended for Production - 82% smaller):**\n```bash\ndocker-compose -f docker-compose.alpine.yml up -d\n```\n\n### 4. Access the Lab\n```bash\n# Local SSH access\nssh admin@localhost -p 2222\n# Password: admin123\n```\n\n## 👥 User Accounts\n\n| Username | Default Password | Sudo Access | Purpose |\n|----------|------------------|-------------|---------|\n| `admin` | `admin123` | ✅ Yes | Administrative tasks |\n| `user1` | `user123` | ❌ No | Regular development |\n| `user2` | `user123` | ❌ No | Regular development |\n| `user3` | `user123` | ❌ No | Regular development |\n| `user4` | `user123` | ❌ No | Regular development |\n| `user5` | `user123` | ❌ No | Regular development |\n| `root` | `root123` | ✅ Yes | System administration |\n\n## 🔧 Configuration\n\n### SSH Key Management\n\nThe lab environment uses shared SSH host keys between Alpine and Ubuntu containers to ensure consistent SSH connections:\n\n```bash\n# Generate new SSH host keys\n./scripts/manage-ssh-keys.sh generate\n\n# Check SSH key fingerprints\n./scripts/manage-ssh-keys.sh check\n\n# Backup SSH keys\n./scripts/manage-ssh-keys.sh backup\n\n# Restore SSH keys from backup\n./scripts/manage-ssh-keys.sh restore backup/ssh-20231201-143022\n```\n\n**Benefits:**\n- ✅ Same SSH host keys across both containers\n- ✅ No SSH host key warnings when switching containers\n- ✅ Centralized key management\n- ✅ Easy key rotation and backup\n\n### Environment Variables\n\nThe lab uses environment variables for secure configuration. Copy `.env.example` to `.env` and customize:\n\n```bash\n# Required: Playit.gg secret key for public access\nPLAYIT_SECRET_KEY=your_playit_secret_key_here\n\n# User passwords (change these!)\nADMIN_PASSWORD=your_admin_password_here\nUSER_PASSWORD=your_user_password_here\nROOT_PASSWORD=your_root_password_here\n\n# Optional: SSH port mapping\nSSH_PORT=2222\n```\n\n### Security Best Practices\n\n- **Change default passwords** immediately after first login\n- **Use SSH keys** instead of password authentication when possible\n- **Never commit** your `.env` file to version control\n- **SSH host keys are automatically ignored** by `.gitignore` for security\n- **Regular updates** of the base image and installed packages\n\n## 🌐 Remote Access\n\n### Local Access\n```bash\n# SSH to any user\nssh admin@localhost -p 2222\nssh user1@localhost -p 2222\n# ... etc\n```\n\n### Public Access via Playit.gg\n\nThe environment includes playit.gg tunneling for public SSH access:\n\n1. **Configure playit.gg**: Set your secret key in `.env`\n2. **Check tunnel status**: Monitor container logs for tunnel URL\n3. **Connect remotely**: Use the provided public URL\n\n```bash\n# Check tunnel status\ndocker-compose -f docker-compose.ubuntu.yml logs lab-environment-ubuntu | grep -i \"playit\\|tunnel\"\n\n# Connect via public URL (example)\nssh admin@your-tunnel-url.playit.gg -p 12345\n```\n\n## 🛠️ Available Tools\n\n### Development Tools\n- **Python 3.x** with pip package manager\n- **uv** - Fast Python package manager (replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv)\n- **uvx** - Run Python tools in ephemeral environments\n- **Node.js** with npm package manager\n- **Git** for version control\n- **SSH** server for remote access\n\n### System Utilities\n- **curl** for HTTP requests\n- **jq** for JSON processing\n- **ping** for network testing\n- **ifconfig** for network configuration\n- **apt** package manager (Ubuntu) / **apk** package manager (Alpine)\n\n## 📁 Project Structure\n\n```\nnazdocker-lab/\n├── Dockerfile.ubuntu       # Ubuntu container definition with health checks\n├── Dockerfile.alpine       # Alpine container definition (189MB)\n├── start.sh               # Cross-platform startup script\n├── docker-compose.ubuntu.yml # Ubuntu Docker Compose orchestration\n├── docker-compose.alpine.yml # Alpine Docker Compose orchestration\n├── .env.example           # Environment variables template\n├── README.md              # This file\n├── docs/                 # Modular documentation\n├── LICENSE                # GPL v3 license\n├── config/               # Configuration files\n│   └── ssh/              # Shared SSH host keys (gitignored)\n│       ├── ssh_host_rsa_key\n│       ├── ssh_host_rsa_key.pub\n│       ├── ssh_host_ecdsa_key\n│       ├── ssh_host_ecdsa_key.pub\n│       ├── ssh_host_ed25519_key\n│       └── ssh_host_ed25519_key.pub\n├── scripts/              # Utility scripts\n│   └── manage-ssh-keys.sh # SSH key management script\n├── data/                  # Persistent user data (separated by container type)\n│   ├── alpine/           # Alpine container data\n│   │   ├── admin/        # Admin home directory (Alpine)\n│   │   ├── user1/        # User1 home directory (Alpine)\n│   │   ├── user2/        # User2 home directory (Alpine)\n│   │   ├── user3/        # User3 home directory (Alpine)\n│   │   ├── user4/        # User4 home directory (Alpine)\n│   │   └── user5/        # User5 home directory (Alpine)\n│   └── ubuntu/           # Ubuntu container data\n│       ├── admin/        # Admin home directory (Ubuntu)\n│       ├── user1/        # User1 home directory (Ubuntu)\n│       ├── user2/        # User2 home directory (Ubuntu)\n│       ├── user3/        # User3 home directory (Ubuntu)\n│       ├── user4/        # User4 home directory (Ubuntu)\n│       └── user5/        # User5 home directory (Ubuntu)\n└── logs/                 # Application logs (separated by container type)\n    ├── alpine/           # Alpine container logs\n    └── ubuntu/           # Ubuntu container logs\n```\n\n## 🔄 Development Workflow\n\n### Ubuntu Version (Recommended for Development)\n```bash\n# Start Ubuntu environment\ndocker-compose -f docker-compose.ubuntu.yml up -d\n\n# SSH into lab\nssh admin@localhost -p 2222\n\n# Develop in your persistent home directory\n# Install packages: sudo apt-get install (admin only)\n\n# Use uv for Python development\nuv init myproject          # Create new Python project\nuv add requests            # Add dependency\nuv run myproject/main.py   # Run Python script\nuvx ruff check            # Run linter in ephemeral environment\n\n# Stop when done\ndocker-compose -f docker-compose.ubuntu.yml down\n```\n\n### Alpine Version (Recommended for Production)\n```bash\n# Start Alpine environment (82% smaller)\ndocker-compose -f docker-compose.alpine.yml up -d\n\n# SSH into lab (same commands)\nssh admin@localhost -p 2222\n\n# Develop in your persistent home directory\n# Install packages: sudo apk add (admin only)\n\n# Use uv for Python development\nuv init myproject          # Create new Python project\nuv add requests            # Add dependency\nuv run myproject/main.py   # Run Python script\nuvx ruff check            # Run linter in ephemeral environment\n\n# Stop when done\ndocker-compose -f docker-compose.alpine.yml down\n```\n\n### Building Images\n```bash\n# Build Ubuntu image\ndocker-compose -f docker-compose.ubuntu.yml build\n\n# Build Alpine image\ndocker-compose -f docker-compose.alpine.yml build\n\n# Build both images\ndocker-compose -f docker-compose.ubuntu.yml build \u0026\u0026 docker-compose -f docker-compose.alpine.yml build\n```\n\n### Running Both Containers Simultaneously\n\nWith separate volumes, you can run both Alpine and Ubuntu containers at the same time:\n\n```bash\n# Start both environments\ndocker-compose -f docker-compose.ubuntu.yml up -d\ndocker-compose -f docker-compose.alpine.yml up -d\n\n# Access Ubuntu lab (port 2222)\nssh admin@localhost -p 2222\n\n# Access Alpine lab (port 2223 - you'll need to modify SSH_PORT in .env)\nssh admin@localhost -p 2223\n\n# Both containers use the same SSH host keys, so no key warnings when switching\n# Stop both environments\ndocker-compose -f docker-compose.ubuntu.yml down\ndocker-compose -f docker-compose.alpine.yml down\n```\n\n## 🛡️ Security Considerations\n\n### Default Configuration\n- All users have password authentication enabled\n- SSH keys are not configured by default\n- Default passwords should be changed immediately\n\n### Recommended Security Measures\n1. **Change all default passwords** after first login\n2. **Configure SSH key authentication** for better security\n3. **Use strong, unique passwords** for each user\n4. **Regular security updates** of the base image\n5. **Monitor access logs** for suspicious activity\n\n## 🏥 Health Monitoring\n\nBoth Ubuntu and Alpine versions include built-in health checks that monitor SSH service availability:\n\n- **Health Check Interval**: 30 seconds\n- **Timeout**: 10 seconds per check\n- **Start Period**: 40 seconds grace period after container startup\n- **Retries**: 3 consecutive failures before marking as unhealthy\n\n### Health Status\n- **Healthy**: SSH service is running and accepting connections\n- **Unhealthy**: SSH service is stopped or not responding\n- **Starting**: Container is in the grace period after startup\n\n### Monitoring Health Status\n```bash\n# Check container health status\ndocker ps\n\n# View detailed health information\ndocker inspect student-lab-ubuntu | grep -A 20 \"Health\"\n\n# Monitor health check logs\ndocker inspect student-lab-ubuntu | grep -A 10 \"Healthcheck\"\n```\n\n## 💾 Volume Management\n\n### Separate Volume Structure\n\nThe lab environment uses separate volumes for Alpine and Ubuntu containers to ensure complete isolation and prevent data conflicts:\n\n```\ndata/\n├── alpine/           # Alpine container data\n│   ├── admin/        # Admin user data (Alpine)\n│   ├── user1/        # User1 data (Alpine)\n│   ├── user2/        # User2 data (Alpine)\n│   ├── user3/        # User3 data (Alpine)\n│   ├── user4/        # User4 data (Alpine)\n│   └── user5/        # User5 data (Alpine)\n└── ubuntu/           # Ubuntu container data\n    ├── admin/        # Admin user data (Ubuntu)\n    ├── user1/        # User1 data (Ubuntu)\n    ├── user2/        # User2 data (Ubuntu)\n    ├── user3/        # User3 data (Ubuntu)\n    ├── user4/        # User4 data (Ubuntu)\n    └── user5/        # User5 data (Ubuntu)\n\nlogs/\n├── alpine/           # Alpine container logs\n└── ubuntu/           # Ubuntu container logs\n```\n\n### Benefits of Separate Volumes\n\n- **🔒 Complete Isolation**: Alpine and Ubuntu containers have completely separate data storage\n- **🚀 Concurrent Operation**: Both container types can run simultaneously without conflicts\n- **📦 Easy Management**: Backup, restore, or manage data for each container type separately\n- **🧹 Clean Organization**: Clear separation makes it obvious which data belongs to which container\n- **🔄 Independent Scaling**: Scale Alpine and Ubuntu environments independently\n\n### Volume Usage\n\n- **Alpine Container**: Stores data in `./data/alpine/` and logs in `./logs/alpine/`\n- **Ubuntu Container**: Stores data in `./data/ubuntu/` and logs in `./logs/ubuntu/`\n\n## 🏔️ Alpine vs Ubuntu Comparison\n\n### Image Size Comparison\n| Version | Base Image | Final Size | Size Reduction |\n|---------|------------|------------|----------------|\n| **Ubuntu** | `ubuntu:24.04` | 1.05GB | - |\n| **Alpine** | `alpine:3.22` | 189MB | **82% smaller** |\n\n### When to Use Each Version\n\n**Use Alpine When:**\n- Resource constraints are a concern\n- Fast deployments are needed\n- Security is a priority\n- Production environments where size matters\n\n**Use Ubuntu When:**\n- Maximum compatibility is needed\n- Familiar environment is preferred\n- Specific Ubuntu packages are required\n- Development/testing environments\n\n### Key Differences\n- **Package Management**: `apt` (Ubuntu) vs `apk` (Alpine)\n- **Service Management**: `service` (Ubuntu) vs direct commands (Alpine)\n- **User Groups**: `sudo` (Ubuntu) vs `wheel` (Alpine)\n- **Build Time**: Alpine builds ~50% faster\n- **Startup Time**: Alpine starts ~30% faster\n- **SSH Keys**: Both containers use identical SSH host keys for consistency\n\n### Resource Limits\nBoth versions are configured with optimized resource limits:\n- **CPU**: Maximum 2 cores, minimum 1 core reserved\n- **Memory**: Maximum 2GB, minimum 1GB reserved\n- **Network**: Standard bridge networking\n- **Storage**: Persistent volumes for user data\n\n## 📚 Documentation\n\n- **[Documentation Index](docs/index.md)**: Complete modular documentation\n- **[Quick Start Guide](docs/getting-started/quick-start.md)**: Get up and running in minutes\n- **[Project Structure](docs/getting-started/project-structure.md)**: Complete project overview\n- **[Container Management](docs/administration/container-management.md)**: Docker container operations\n- **[User Management](docs/user-management/user-accounts.md)**: User account management\n- **[Remote Access](docs/remote-access/ssh-access.md)**: SSH access and tunneling\n- **[Troubleshooting](docs/troubleshooting/common-issues.md)**: Common issues and solutions\n- **[Docker Documentation](https://docs.docker.com/)**: Docker basics\n- **[SSH Documentation](https://www.openssh.com/manual.html)**: SSH configuration\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our contributing guidelines:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Setup\n```bash\n# Clone your fork\ngit clone https://github.com/your-username/nazdocker-lab.git\ncd nazdocker-lab\n\n# Add upstream remote\ngit remote add upstream https://github.com/nazdridoy/nazdocker-lab.git\n\n# Create feature branch\ngit checkout -b feature/your-feature-name\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Container won't start:**\n```bash\n# Check logs\ndocker-compose logs\n\n# Validate configuration\ndocker-compose config\n```\n\n**SSH connection refused:**\n```bash\n# Check container status\ndocker-compose ps\n\n# Check SSH service\ndocker-compose -f docker-compose.ubuntu.yml exec lab-environment-ubuntu service ssh status\n```\n\n**Environment variables not loading:**\n```bash\n# Verify .env file exists\nls -la .env\n\n# Check variable resolution\ndocker-compose config | grep -E \"(PLAYIT_SECRET_KEY|ADMIN_PASSWORD)\"\n```\n\nFor more detailed troubleshooting, see [Troubleshooting Guide](docs/troubleshooting/common-issues.md).\n\n## 📄 License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Docker](https://www.docker.com/) for containerization technology\n- [Ubuntu](https://ubuntu.com/) for the base operating system\n- [Playit.gg](https://playit.gg/) for tunneling services\n- [OpenSSH](https://www.openssh.com/) for secure shell access\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/nazdridoy/nazdocker-lab/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/nazdridoy/nazdocker-lab/discussions)\n- **Documentation**: [Documentation Index](docs/index.md)\n\n---\n\n**Note**: This is a development and educational tool. Always follow security best practices and change default credentials before use in production environments. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnazdridoy%2Fnazdocker-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnazdridoy%2Fnazdocker-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnazdridoy%2Fnazdocker-lab/lists"}