Skip to content

QUICKSTART.md

Latest commit

 

History

History
593 lines (430 loc) · 15.8 KB

QUICKSTART.md

File metadata and controls

593 lines (430 loc) · 15.8 KB

📦 PowerContainers - Quick Reference Guide

🚀 Your Fast-Track Guide to Development Containers 🚀

🎯 What is PowerContainers?

PowerContainers is a curated collection of production-ready development containers for modern software development. Think of it as your instant development environment in a box! 📦

✨ What Makes It Special?

  • 🐳 Multi-stage Dockerfiles - Optimized for speed and size
  • 💻 Complete VS Code Integration - Extensions pre-installed
  • 🛠️ Pre-configured Tooling - Linters, formatters, debuggers ready
  • 📚 Comprehensive Documentation - In English with helpful emojis
  • ⚡ Lightning Fast - From zero to coding in minutes
  • 🌍 Cross-Platform - Works on Windows, macOS, and Linux

📊 Available Containers at a Glance

Icon Container Key Features Path
🔧 C++ CMake GCC/Clang • CMake/Ninja • GDB/LLDB • Google Test containers/cpp-cmake/
📱 Flutter Flutter SDK • Dart • Desktop/Web • Android SDK containers/flutter/
🟣 .NET .NET 8 • Aspire • MAUI • Blazor • EF Core containers/dotnet/
🐍 Python Python 3.12 • FastAPI • Django • pytest • poetry containers/python/
⚛️ React Node.js 20 • Vite/CRA • TypeScript • ESLint containers/react/
🅰️ Angular Node.js 20 • Angular CLI • TypeScript • Material containers/angular/
⚡ Ionic Angular Ionic CLI • Angular • Cordova/Capacitor • Live Reload containers/ionic-angular/
⚡ Ionic React Ionic CLI • React • TypeScript • Vite • Capacitor containers/ionic-react/

🔧 C++ CMake Container

Path: containers/cpp-cmake/

🛠️ Toolchain:

  • ⚙️ Compilers: GCC & Clang
  • 🔨 Build System: CMake & Ninja
  • 🐛 Debuggers: GDB & LLDB
  • 🔍 Analysis: clang-tidy, cppcheck
  • ✅ Testing: Google Test
  • 📚 Libraries: Boost

📱 Flutter Container

Path: containers/flutter/

🛠️ Toolchain:

  • 🎯 Flutter SDK (stable channel)
  • 🎪 Dart SDK
  • 💻 Linux desktop support
  • 🌐 Web support
  • 📱 Optional Android SDK
  • 🔄 State management extensions

🟣 .NET Container

Path: containers/dotnet/

🛠️ Toolchain:

  • 🎯 .NET 8 SDK
  • ☁️ Aspire (cloud-native apps)
  • 📱 MAUI (cross-platform UI)
  • 🌐 Blazor (WebAssembly & Server)
  • 💾 Entity Framework Core
  • 🔒 Identity & Authentication

🐍 Python Container

Path: containers/python/

🛠️ Toolchain:

  • 🐍 Python 3.12
  • ⚡ FastAPI (pre-installed)
  • 🌐 Django & Flask support
  • 🎨 Code formatters: Black, isort
  • 🔍 Linters: flake8, pylint
  • ✅ Testing: pytest
  • 📦 Package management: poetry, pip

⚛️ React Container

Path: containers/react/

🛠️ Toolchain:

  • 🟢 Node.js 20 LTS
  • ⚡ Vite (ultra-fast bundler)
  • 📦 Create React App support
  • 📘 TypeScript support
  • ✨ ESLint & Prettier
  • 📦 Package managers: npm, yarn, pnpm

🅰️ Angular Container

Path: containers/angular/

🛠️ Toolchain:

  • 🟢 Node.js 20 LTS
  • 🔺 Angular CLI (latest)
  • 📘 TypeScript support
  • ✨ ESLint & Prettier
  • 🎨 Angular Material ready
  • 🔥 Hot Module Replacement

⚡ Ionic Angular Container

Path: containers/ionic-angular/

🛠️ Toolchain:

  • ⚡ Ionic CLI
  • 🅰️ Angular CLI
  • 📱 Cordova & Capacitor
  • 🔌 Native app support
  • 🔄 Live reload server
  • 🎨 Ionic components

⚡ Ionic React Container

Path: containers/ionic-react/

🛠️ Toolchain:

  • ⚡ Ionic CLI
  • ⚛️ React with TypeScript
  • 📱 Cordova & Capacitor
  • ⚡ Vite bundler
  • 🔌 Native app support
  • 🎨 Ionic components

🚀 Getting Started in 5 Minutes

📋 Prerequisites Checklist

Before starting, make sure you have these installed:

# Tool Status Link
1️⃣ Docker Desktop ☐ Download
2️⃣ Visual Studio Code ☐ Download
3️⃣ Dev Containers Extension ☐ Install

💡 Linux users: You can use Docker Engine instead of Docker Desktop

🎯 Quick Start Steps

Step 1️⃣: Clone the Repository

git clone https://github.com/yourusername/PowerContainers.git
cd PowerContainers

Step 2️⃣: Navigate to Your Container

cd containers/cpp-cmake  # Choose any container you need

Step 3️⃣: Open in VS Code

code .

Step 4️⃣: Launch Dev Container

  • Press F1 or Ctrl+Shift+P (macOS: Cmd+Shift+P)
  • Type: Dev Containers: Reopen in Container
  • Hit Enter ⏎

Step 5️⃣: Wait for Setup ⏳

The container will build automatically (first time takes 2-5 minutes)

Step 6️⃣: Start Coding! 🎉

Your development environment is fully configured and ready!

🎬 Alternative: Quick Container Selection

# C++ Development
cd containers/cpp-cmake && code .

# Flutter Development
cd containers/flutter && code .

# .NET Development
cd containers/dotnet && code .

# Python Development
cd containers/python && code .

# React Development
cd containers/react && code .

# Angular Development
cd containers/angular && code .

# Ionic Angular Development
cd containers/ionic-angular && code .

# Ionic React Development
cd containers/ionic-react && code .

🎨 Customization Guide

🏗️ Multi-Stage Architecture

Each container uses a multi-stage Dockerfile for optimal flexibility:

# 🔹 Stage 1: Base - Minimal base image
FROM ubuntu:22.04 AS base

# 🔹 Stage 2: Build Tools - Essential build tools
FROM base AS build-tools

# 🔹 Stage 3: Dev Tools - Development utilities
FROM build-tools AS dev-tools

# 🔹 Stage 4: Libraries - Additional libraries (⭐ CUSTOMIZE HERE!)
FROM dev-tools AS libraries

# 🔹 Stage 5: Development - Final dev environment
FROM libraries AS development

# 🔹 Stage 6: Production - Minimal runtime (optional)
FROM base AS production

➕ Adding Your Dependencies

1️⃣ System Packages:

FROM dev-tools AS libraries
RUN apt-get update && apt-get install -y \
    your-library \
    another-dependency \
    custom-tool \
    && rm -rf /var/lib/apt/lists/*

2️⃣ VS Code Extensions: Edit .devcontainer/devcontainer.json:

{
  "customizations": {
    "vscode": {
      "extensions": [
        "your.extension-id",
        "another.extension"
      ]
    }
  }
}

3️⃣ Environment Variables:

ENV MY_VAR=value
ENV PATH="/custom/path:${PATH}"

📁 Container Structure

Each container follows this organized structure:

📦 container-name/
├── 📂 .devcontainer/
│   ├── 📄 devcontainer.json    # 🔧 VS Code dev container configuration
│   └── 📄 Dockerfile           # 🐳 Multi-stage container definition
├── 📂 .vscode/
│   ├── 📄 settings.json        # ⚙️ Editor preferences & formatting rules
│   ├── 📄 launch.json          # 🐛 Debug configurations
│   └── 📄 extensions.json      # 📦 Recommended extensions
├── 📂 src/                      # 💻 Your source code goes here
└── 📄 README.md                 # 📚 Comprehensive documentation

🗂️ Key Files Explained

File Purpose Edit Frequency
devcontainer.json 🔧 Container settings, ports, features 🟢 Often
Dockerfile 🐳 Image definition, tools installation 🟡 Sometimes
settings.json ⚙️ VS Code editor configuration 🟢 Often
launch.json 🐛 Debugging configurations 🟡 Sometimes
README.md 📚 Documentation and guides 🔴 Rarely

🔧 Common Commands Reference

🐳 Docker Commands

# 📋 List all running containers
docker ps

# 📋 List all containers (including stopped)
docker ps -a

# 🗑️ Remove a specific container
docker rm <container-id>

# 🗑️ Remove all stopped containers
docker container prune

# 🗑️ Remove all containers (⚠️ use with caution)
docker rm -f $(docker ps -aq)

# 🖼️ List all images
docker images

# 🗑️ Remove unused images
docker image prune

# 🗑️ Remove all images (⚠️ use with caution)
docker rmi -f $(docker images -q)

# 🧹 Clean up everything (⚠️ nuclear option)
docker system prune -a --volumes

# 📊 Check disk usage
docker system df

📦 Dev Container Commands (VS Code)

Command Shortcut Description
Dev Containers: Reopen in Container F1 → Type command 🚀 Open folder in container
Dev Containers: Rebuild Container F1 → Type command 🔄 Rebuild from scratch
Dev Containers: Rebuild Without Cache F1 → Type command 🔄 Force clean rebuild
Dev Containers: Show Container Log F1 → Type command 📋 View build logs
Dev Containers: Reopen Folder Locally F1 → Type command 🔙 Exit container mode
Dev Containers: Attach to Running Container F1 → Type command 🔗 Connect to existing container

📊 Quick Comparison Table

🏷️ Container 💬 Language 🔨 Build Tool 📦 Package Manager 🌐 Default Ports
🔧 C++ CMake C++17-20 CMake/Ninja apt -
📱 Flutter Dart Flutter CLI pub 8080
🟣 .NET C# / F# dotnet CLI NuGet 5000, 5001
🐍 Python Python 3.12+ pip pip/poetry 8000, 5000
⚛️ React TypeScript/JS Vite/CRA npm/yarn/pnpm 3000, 5173
🅰️ Angular TypeScript Angular CLI npm/yarn 4200
⚡ Ionic Angular TypeScript Ionic CLI npm 8100
⚡ Ionic React TypeScript/JS Ionic CLI npm/yarn/pnpm 8100

🎯 Best Use Cases

Container Perfect For Difficulty
🔧 C++ Systems programming, performance-critical apps 🔴🔴🔴 Advanced
📱 Flutter Cross-platform mobile apps 🟡🟡 Intermediate
🟣 .NET Enterprise apps, web APIs, cloud-native 🟡🟡 Intermediate
🐍 Python Data science, web APIs, automation 🟢 Beginner-friendly
⚛️ React Modern web UIs, SPAs 🟡 Intermediate
🅰️ Angular Enterprise web apps 🟡🟡 Intermediate
⚡ Ionic Angular Hybrid mobile apps with Angular 🟡🟡 Intermediate
⚡ Ionic React Hybrid mobile apps with React 🟡🟡 Intermediate

🐛 Troubleshooting Guide

❌ Container Won't Build

Symptoms: Build fails or hangs indefinitely

Solutions:

  1. ✅ Check Docker is running

    docker ps

  2. ✅ Review build logs

    • Press F1 → Dev Containers: Show Container Log
    • Look for error messages

  3. ✅ Try clean rebuild

    • Press F1 → Dev Containers: Rebuild Container
    • Or: F1 → Dev Containers: Rebuild Without Cache

  4. ✅ Check disk space

    docker system df

  5. ✅ Restart Docker Desktop

🔌 Port Already in Use

Symptoms: Error message about port conflicts

Solutions:

  1. ✅ Find what's using the port (example for port 3000)

    # Windows
netstat -ano | findstr :3000

# macOS/Linux
lsof -i :3000

  2. ✅ Stop the conflicting service

  3. ✅ Change port in devcontainer.json

    "forwardPorts": [3001]  // Instead of 3000

🐌 Slow Build Times

Symptoms: Container takes forever to build

Solutions:

  1. ✅ Enable BuildKit (faster builds)

    # Windows (PowerShell)
$env:DOCKER_BUILDKIT=1

# macOS/Linux
export DOCKER_BUILDKIT=1

  2. ✅ Use layer caching (automatically enabled with BuildKit)

  3. ✅ Close unnecessary applications to free up resources

  4. ✅ Increase Docker resources

    • Docker Desktop → Settings → Resources
    • Increase CPU and Memory allocation

  5. ✅ Clean up Docker

    docker system prune -a

🔒 Permission Issues

Symptoms: Cannot write files, access denied errors

Solutions:

  1. ✅ Check container user settings

    • Look for remoteUser in devcontainer.json

  2. ✅ Verify volume permissions

    # Inside container
ls -la /workspace

  3. ✅ Fix ownership (if needed)

    sudo chown -R $(whoami) /workspace

🌐 Network Issues

Symptoms: Cannot download packages or connect to internet

Solutions:

  1. ✅ Check Docker network

    docker network ls

  2. ✅ Verify DNS settings

    • Docker Desktop → Settings → Docker Engine
    • Add DNS servers if needed

  3. ✅ Try different DNS

    {
  "dns": ["8.8.8.8", "8.8.4.4"]
}

💡 Still Having Issues?

  • 📖 Check container-specific README
  • 🔍 Search existing GitHub Issues
  • 💬 Open a new issue with:
    • OS and Docker version
    • Container name
    • Full error message
    • Build logs

📚 Additional Resources

📖 Official Documentation

Resource Description Link
📦 Dev Containers Official VS Code documentation Read Docs
🐳 Docker Complete Docker documentation Read Docs
🏗️ Dockerfile Best Practices Official best practices guide Read Guide
🔧 Dev Container Spec Container specification details Read Spec

🎓 Learning Resources

  • 📺 Video Tutorials: Check container-specific READMEs
  • 💡 Blog Posts: Tips and tricks for each framework
  • 🎯 Sample Projects: Example implementations
  • 💬 Community Forums: Get help from other developers

🤝 Contributing

We welcome contributions! 🎉

How to Contribute:

  1. 🍴 Fork the repository
  2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
  3. ✍️ Make your changes
  4. ✅ Test thoroughly
  5. 📝 Commit with clear messages (git commit -m 'Add amazing feature')
  6. 📤 Push to your branch (git push origin feature/amazing-feature)
  7. 🔄 Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

🌟 Ways to Contribute:

  • 🐛 Report bugs
  • 💡 Suggest new features
  • 📝 Improve documentation
  • 🔧 Add new containers
  • ✨ Enhance existing containers
  • 🎨 Improve UI/UX

📄 License

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

💬 Support & Community

  • 🐛 Bug Reports: Open an Issue
  • 💡 Feature Requests: Start a Discussion
  • 💬 Questions: Check existing issues or open a new one
  • 📧 Enterprise Support: Contact us for custom solutions

🌟 Show Your Support

If PowerContainers helps you, please:

⭐ Star this repository | 🔄 Share with your team | 💬 Give feedback

Made with ❤️ for developers worldwide

🚀 Happy Coding! 🚀