Implement Shells.com OS Creation Tutorial with automated template generation system

.github/workflows/generate-templates.yml

@@ -0,0 +1,92 @@
+name: Generate Shells Image Templates
+
+on:
+  # Trigger on push to main branch when official_images.txt changes
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'official_images.txt'
+      - 'generate_templates.sh'
+      - '.github/workflows/generate-templates.yml'
+
+  # Allow manual trigger
+  workflow_dispatch:
+
+  # Run weekly to keep templates up to date
+  schedule:
+    - cron: '0 0 * * 0'  # Every Sunday at midnight UTC
+
+jobs:
+  generate-templates:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Git
+      run: |
+        git config --local user.email "action@github.com"
+        git config --local user.name "GitHub Action"
+
+    - name: Make generate_templates.sh executable
+      run: chmod +x generate_templates.sh
+
+    - name: Generate templates
+      run: |
+        echo "Starting template generation..."
+        ./generate_templates.sh
+        echo "Template generation completed"
+
+    - name: Check for changes
+      id: verify-changed-files
+      run: |
+        if [ -n "$(git status --porcelain)" ]; then
+          echo "changed=true" >> $GITHUB_OUTPUT
+        else
+          echo "changed=false" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Show generated files
+      if: steps.verify-changed-files.outputs.changed == 'true'
+      run: |
+        echo "Generated/modified files:"
+        git status --porcelain
+        echo "Templates directory structure:"
+        find templates -type f -name "*.md" | sort
+
+    - name: Commit and push changes
+      if: steps.verify-changed-files.outputs.changed == 'true'
+      run: |
+        git add templates/
+        git commit -m "Auto-generate image configuration templates
+
+        - Generated templates for all configurations in official_images.txt
+        - Updated template structure and documentation
+        - Templates organized by distribution
+
+        This commit was automatically generated by the GitHub Action."
+        git push
+
+    - name: Create summary
+      if: always()
+      run: |
+        echo "## Template Generation Summary" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        if [ "${{ steps.verify-changed-files.outputs.changed }}" == "true" ]; then
+          echo "✅ Templates were updated and committed" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Generated Templates:" >> $GITHUB_STEP_SUMMARY
+          find templates -type f -name "*.md" ! -name "README.md" | wc -l | xargs echo "- Total configurations:" >> $GITHUB_STEP_SUMMARY
+          for distro in $(find templates -mindepth 1 -maxdepth 1 -type d -exec basename {} \;); do
+            count=$(find templates/$distro -name "*.md" | wc -l)
+            echo "- $distro: $count templates" >> $GITHUB_STEP_SUMMARY
+          done
+        else
+          echo "ℹ️ No changes detected - templates are up to date" >> $GITHUB_STEP_SUMMARY
+        fi
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "### Available Distributions:" >> $GITHUB_STEP_SUMMARY
+        find templates -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort | sed 's/^/- /' >> $GITHUB_STEP_SUMMARY

README.md

@@ -18,6 +18,23 @@ For example:
 
 For list of currently available builds, take a look at [official_images.txt](https://github.com/Shells-com/linux-scripts/blob/master/official_images.txt).
 
+For detailed configuration information and templates, see the [templates directory](templates/).
+
+## OS Creation Tutorial
+
+For comprehensive guidance on creating Shells images, see our detailed tutorial:
+- [Shells.com OS Creation Tutorial](docs/shells-os-creation-tutorial.md)
+
+This tutorial covers:
+- Creating images from existing Shells
+- Moving from Virtual Machines
+- Running your own kernel
+- Available configurations and templates
+
+## Configuration Templates
+
+Each supported image configuration has a detailed template with build instructions, requirements, and testing guidance. Templates are automatically generated and organized by distribution in the [templates/](templates/) directory.
+
 # Submit/maintain your distribution
 
 Shells wants to help Linux community as much as it can, so if you would like to see your own distribution on the list, submit PR with it and we will gladly merge it. Be sure to read about some simple rules around how to build images for Shells at [os_requirements.md](https://github.com/Shells-com/linux-scripts/blob/master/os_requirements.md).

docs/shells-os-creation-tutorial.md

@@ -0,0 +1,82 @@
+# Shells.com OS Creation Tutorial
+
+**Source:** [https://www.shells.com/l/en-US/tutorial/Shells-com-OS-Creation-Tutorial](https://www.shells.com/l/en-US/tutorial/Shells-com-OS-Creation-Tutorial)
+
+This tutorial will show you how to create an image suitable for Shells either from your existing Shell™, from your existing Virtual Machine or building it on your own.
+
+## Create a Shells™ image from your existing Shell™
+
+**Head over [Shells™ Console](https://console.shells.com/) and toggle 'Advanced Mode' on the left side.**
+
+![Advanced Mode](https://cdn.shells.net/image/Ha_VjVQl--SPOiMV95yzVReYvDlHS3Xuv-Rq2dyixxr_6XMq0lqvWg3y1jG0Y7AA/e0273ee9f0e0c7f034aceceba0c13168fb9ff488)
+
+**Navigate to "My OS" on the left navbar.**
+
+![My OS](https://cdn.shells.net/image/xyMNO0DbbvCpt7SGxo2PlJGkjGGR_qoA3Jx4ZdUiHONIHDwNHOsW-v3MugKDy-q6/e0273ee9f0e0c7f034aceceba0c13168fb9ff488)
+
+**Select '+Create' on the new page.**
+
+**The first option will be 'CREATE FROM A SHELL'**
+
+You will be able to choose from which of your Shells you want to create an image.
+
+Fill in the rest of the information as needed.
+
+This image will contain all your changes and installed software that you have on the Shell you chose from. It will be a mirrored version of your setup.
+
+## Move from Virtual Machine
+
+If you're trying to move your existing VM to Shells, you need to have that VM installed in your local environment, retrieve the hard drive file from it, and use qemu-img (or similar to convert the hard drive to raw format).
+
+**Example for qcow2 format:**
+
+```bash
+qemu-img convert -f qcow2 -O raw in.qcow2 out.raw
+```
+
+Then, use the [Shells RBDCONV Tool](https://github.com/Shells-com/rbdconv) to convert the raw image to.shells and upload it to your Shells account by selecting the appropriate option.
+
+## Run your own kernel
+
+If you wish to run your own Kernel instead of Shells' provided one, be sure to have it in the image and make sure it is BIOS or UEFI ready and has disk resize capability integrated with it.
+
+To build a Linux image from scratch, follow our guidelines at:
+
+[https://github.com/Shells-com/linux-scripts](https://github.com/Shells-com/linux-scripts)
+
+And pay attention to requirements that make sure images will work well with Shells™ infrastructure:
+
+[https://github.com/Shells-com/linux-scripts/blob/master/os_requirements.md](https://github.com/Shells-com/linux-scripts/blob/master/os_requirements.md)
+
+***DISCLAIMER: ISO images are currently not supported.***
+
+## Available Image Configurations
+
+For a complete list of supported image configurations that can be built using this repository, see:
+
+- [Official Images List](../official_images.txt)
+- [OS Requirements](../os_requirements.md)
+- [Build Instructions](../README.md)
+
+## Building Custom Images
+
+To build any of the supported configurations:
+
+```bash
+./build_image.sh <configuration-name>
+```
+
+For example:
+```bash
+./build_image.sh ubuntu-focal-ubuntu-desktop
+```
+
+## Testing Images
+
+Test your built images before deployment:
+
+```bash
+./test-linux.sh generated-disk-image.qcow2
+```
+
+This will run the disk image inside qemu with a configuration similar to what is used on Shells.

generate_templates.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+# Script to generate templates for Shells image configurations
+# This script reads from official_images.txt and creates template files for each configuration
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATES_DIR="$SCRIPT_DIR/templates"
+OFFICIAL_IMAGES="$SCRIPT_DIR/official_images.txt"
+
+# Ensure templates directory exists
+mkdir -p "$TEMPLATES_DIR"
+
+# Function to extract distribution info from image name
+extract_distro_info() {
+    local image_name="$1"
+    local distro=$(echo "$image_name" | cut -d'-' -f1)
+    local version=$(echo "$image_name" | cut -d'-' -f2)
+    local variant=$(echo "$image_name" | cut -d'-' -f3-)
+
+    echo "$distro:$version:$variant"
+}
+
+# Function to create template for a specific image configuration
+create_template() {
+    local image_name="$1"
+    local distro_info=$(extract_distro_info "$image_name")
+    local distro=$(echo "$distro_info" | cut -d':' -f1)
+    local version=$(echo "$distro_info" | cut -d':' -f2)
+    local variant=$(echo "$distro_info" | cut -d':' -f3)
+
+    # Create distro-specific directory
+    local distro_dir="$TEMPLATES_DIR/$distro"
+    mkdir -p "$distro_dir"
+
+    # Template file path
+    local template_file="$distro_dir/${image_name}.md"
+
+    # Determine if it's a desktop or server image
+    local image_type="server"
+    if [[ "$variant" == *"desktop"* ]]; then
+        image_type="desktop"
+    fi
+
+    # Create template content
+    cat > "$template_file" << EOF
+# $image_name Configuration Template
+
+## Image Details
+- **Distribution:** $distro
+- **Version:** $version
+- **Variant:** $variant
+- **Type:** $image_type
+- **Full Name:** $image_name
+
+## Build Command
+\`\`\`bash
+./build_image.sh $image_name
+\`\`\`
+
+## Description
+This configuration builds a $distro $version system with $variant.
+
+EOF
+
+    # Add type-specific information
+    if [[ "$image_type" == "desktop" ]]; then
+        cat >> "$template_file" << EOF
+## Desktop Environment Features
+- GUI desktop environment
+- Pre-configured for Shells infrastructure
+- Optimized for remote desktop access
+- Includes necessary graphics drivers
+
+## Requirements
+- Spice-vdagent for enhanced graphics
+- QXL graphics driver support
+- Audio support configured
+- Screen locking disabled
+- Power management disabled
+
+EOF
+    else
+        cat >> "$template_file" << EOF
+## Server Features
+- Command-line interface
+- Minimal resource footprint
+- SSH access configured
+- Essential server tools included
+
+## Requirements
+- SSH server enabled
+- Network configuration ready
+- Basic system utilities
+
+EOF
+    fi
+
+    # Add common configuration information
+    cat >> "$template_file" << EOF
+## Common Configuration
+- Passwordless sudo enabled
+- Auto-login configured
+- QEMU guest agent installed
+- Latest system updates applied
+- Shells helper tools included
+
+## Testing
+Test the built image with:
+\`\`\`bash
+./test-linux.sh $image_name-\$(date +%Y%m%d).qcow2
+\`\`\`
+
+## Related Files
+- Configuration script: \`oscfg/$distro.sh\`
+- Base scripts: \`scripts/\`
+- Requirements: [os_requirements.md](../os_requirements.md)
+
+## References
+- [Shells.com OS Creation Tutorial](../docs/shells-os-creation-tutorial.md)
+- [Official Images List](../official_images.txt)
+- [Build Instructions](../README.md)
+EOF
+
+    echo "Created template: $template_file"
+}
+
+# Main execution
+echo "Generating templates for Shells image configurations..."
+
+# Check if official_images.txt exists
+if [[ ! -f "$OFFICIAL_IMAGES" ]]; then
+    echo "Error: $OFFICIAL_IMAGES not found!"
+    exit 1
+fi
+
+# Create README for templates directory
+cat > "$TEMPLATES_DIR/README.md" << EOF
+# Shells Image Configuration Templates
+
+This directory contains template documentation for all supported Shells image configurations.
+
+## Directory Structure
+- Each distribution has its own subdirectory
+- Template files are named after their configuration (e.g., \`ubuntu-focal-ubuntu-desktop.md\`)
+
+## Available Distributions
+EOF
+
+# Read official_images.txt and process each image
+while IFS= read -r image_name || [[ -n "$image_name" ]]; do
+    # Skip empty lines and comments
+    [[ -z "$image_name" || "$image_name" =~ ^[[:space:]]*# ]] && continue
+
+    # Create template for this image
+    create_template "$image_name"
+done < "$OFFICIAL_IMAGES"
+
+# Update README with available distributions
+distributions=$(find "$TEMPLATES_DIR" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort | uniq)
+for distro in $distributions; do
+    echo "- **$distro**: $(find "$TEMPLATES_DIR/$distro" -name "*.md" | wc -l) configurations" >> "$TEMPLATES_DIR/README.md"
+done
+
+cat >> "$TEMPLATES_DIR/README.md" << EOF
+
+## Usage
+Each template contains:
+- Build commands
+- Configuration details
+- Requirements
+- Testing instructions
+- Related files and references
+
+To build any configuration:
+\`\`\`bash
+./build_image.sh <configuration-name>
+\`\`\`
+
+For more information, see the [Shells.com OS Creation Tutorial](../docs/shells-os-creation-tutorial.md).
+EOF
+
+echo "Template generation completed!"
+echo "Generated templates in: $TEMPLATES_DIR"
+echo "Total configurations: $(find "$TEMPLATES_DIR" -name "*.md" ! -name "README.md" | wc -l)"