Add custom docker-based appliance creation tutorials #89
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- CREATE_APPLIANCE_TUTORIAL.md: Complete step-by-step guide for creating Docker-based appliances - QUICK_START.md: Quick reference for experienced developers Features: - Full appliance.sh template with OpenNebula contextualization - Packer build configuration examples - Deployment and testing instructions - PR submission workflow - Best practices and troubleshooting tips
pablodelarco
changed the title
- generate-docker-appliance.sh: Script to generate complete appliances from config files - tools/README.md: Documentation for the generator - tools/examples/: Example configuration files (nginx, nodered, postgres, redis) The generator creates appliances using the simplified Phoenix RTOS/Node-RED structure: - Direct container startup (no systemd service) - Uses msg function for logging - Includes password and serial console configuration - Generates all necessary files (appliance.sh, metadata, packer configs, tests)
- Tutorial now teaches how to use the Docker Appliance Generator - Removed manual file creation steps - Added step-by-step generator usage guide - Includes configuration examples (NGINX, Node-RED) - Covers building, testing, and marketplace submission - Much simpler and faster (15-30 min vs 30-45 min)
- Tutorial now clearly explains the .env file approach - Shows how to create configuration files with Docker container details - Includes 4 complete examples (NGINX, Node-RED, PostgreSQL, Redis) - Explains what each variable does - Much simpler: just create .env file and run generator - Removed complex manual file creation steps - Added clear variable reference table
- CREATE_APPLIANCE_TUTORIAL.md now serves as index with both options - automatic-appliance-tutorial/ contains generator-based approach - README.md: Tutorial for using .env files with generator - generate-docker-appliance.sh: The generator script - GENERATOR_README.md: Generator documentation - examples/: 4 example configurations (nginx, nodered, postgres, redis) - manual-appliance-tutorial/ contains step-by-step manual approach - README.md: Complete manual creation guide Users can now choose between: - Automatic (5 min, easy, recommended) - Manual (30-45 min, advanced, full control)
- Replaced automatic/generator content with true manual approach - Added detailed instructions for creating each file manually - Includes templates for metadata.yaml, appliance.sh, README.md, etc. - Step-by-step guide for all 13+ files - Explains bash scripting, YAML configuration, Packer setup - For advanced users who want full control and understanding
…ructure - Now uses exact structure from working Phoenix RTOS and Node-RED appliances - Includes proper ONE_SERVICE_PARAMS format with 'O|text' - Uses msg info/error/warn for logging (OpenNebula framework) - No systemd service - direct container startup - Console auto-login with getty@tty1 and serial-getty@ttyS0 - Root password 'opennebula' with systemctl enable - Welcome message in /etc/profile.d/ - Separate setup_myapp_container() function - Uses --restart unless-stopped and oneapp labels - Matches proven production pattern
- Changed QUICK_START_GUIDE.md references to README.md - The QUICK_START_GUIDE.md file doesn't exist - README.md in automatic-appliance-tutorial/ is the actual tutorial
- tools/ folder was completely duplicated in docs/automatic-appliance-tutorial/ - All files (generator script, examples, README) already exist in docs/ - Keeping everything in docs/ for self-contained documentation - No functionality lost - everything is in docs/automatic-appliance-tutorial/
- Replaced multiple separate guides with ONE comprehensive tutorial - CREATE_APPLIANCE_TUTORIAL.md now contains everything: - Introduction explaining what OpenNebula appliances are - Approach 1: Automatic (with generator script) - Approach 2: Manual (step-by-step) - Building, testing, and submission instructions - All in one place, easy to follow - Removed redundant files: - QUICK_START.md (redundant) - automatic-appliance-tutorial/README.md (merged) - automatic-appliance-tutorial/GENERATOR_README.md (merged) - manual-appliance-tutorial/README.md (merged) - Kept only essentials: - CREATE_APPLIANCE_TUTORIAL.md (complete guide) - automatic-appliance-tutorial/generate-docker-appliance.sh (generator) - automatic-appliance-tutorial/examples/ (4 example configs) Much simpler and cleaner!
- Added detailed 'Deploying to OpenNebula' section: * Step-by-step: Copy QCOW2 to frontend * Create OpenNebula image with oneimage command * Create VM template with context variables and user inputs * Instantiate VM and get IP address * Complete testing procedures (SSH, Docker, console, web UI) - Added detailed 'Submitting to Marketplace' section: * Fork repository on GitHub * Clone and create feature branch * Add all required files (with checklist) * Commit with proper message format * Push and create Pull Request * PR description template with all sections * How to update PR based on review feedback - Both sections work for automatic AND manual approaches - Complete end-to-end workflow from QCOW2 to merged PR - Real-world commands and examples throughout
- Added Option A (using GitHub banner) - easiest method - Added Option B (manual PR creation) - step-by-step - Explained what users should see (Able to merge, commits, files) - Added note about conflicts and syncing with upstream
- Fix docker run command: Remove backslashes to prevent 'invalid reference format' errors - Add automatic build functionality: Prompt user to build image after generation - Fix Makefile: Support appliance names with numbers (e.g., n8n) by checking SERVICES list - Simplify build instructions: Always use 'make' command for consistency - Fix volume ownership: Automatically set ownership to 1000:1000 for non-root containers These fixes ensure: 1. Generated appliances bootstrap correctly without docker errors 2. Build process works for all appliance names including those with numbers 3. Containers running as non-root users have correct permissions 4. Complete workflow from generation to built image in one command
- Remove combined CREATE_APPLIANCE_TUTORIAL.md - Add AUTOMATIC_APPLIANCE_GUIDE.md (5 min quick start) - Add MANUAL_APPLIANCE_GUIDE.md (full control, 30-45 min) - Add docs/README.md with guide comparison and selection help Benefits: - Clearer separation of concerns - Easier to navigate and find relevant information - Better for beginners (automatic guide is simpler) - Better for advanced users (manual guide has full details) - Comparison table helps users choose the right approach
pablodelarco
force-pushed
the
docs/add-appliance-creation-tutorial-clean
branch
from
8c43a80 to
8651e50
Compare
The script now uses ubuntu2204min instead of ubuntu2204 to avoid disk space issues during initramfs generation. The full Ubuntu image has a partition layout where /boot is too small for modern initramfs. Changes: - Updated Packer ISO URL to use ubuntu2204min.qcow2 - Updated base image check to look for ubuntu2204min.qcow2 - Updated make command to build ubuntu2204min - Added automatic Makefile.config SERVICES list update - Added automatic git submodule initialization - Added automatic base image build if missing - Reduced estimated build time from 10-30 min to 3-5 min (minimal image) This makes the script fully automated - no manual steps required.
pablodelarco
force-pushed
the
docs/add-appliance-creation-tutorial-clean
branch
from
ed0cc9f to
aab7e36
Compare
added 8 commits
November 3, 2025 11:35
…clarification, and OpenNebula deployment steps - Add git checkout instruction for dcos/add-appliance-automation-script branch - Clarify that appliance.sh changes require rebuild (scripts run during Packer build) - Add comprehensive OpenNebula deployment section with: - Step-by-step image creation with oneimage create - VM template creation with proper OpenNebula syntax - VM instantiation instructions - SSH port forwarding for remote access - Verification checklist for successful deployment - Remove redundant sed command from template creation - Make all commands generic and adaptable for any appliance
- Changed heredoc delimiter from 'WELCOME_EOF' (single quotes) to WELCOME_EOF (no quotes) to allow variable expansion during Packer build - Removed incorrect cat >> commands that were appending to appliance.sh - Consolidated welcome message into single heredoc - Variables like $APP_NAME, $DOCKER_IMAGE, $DEFAULT_CONTAINER_NAME now properly expand during build instead of remaining as literal strings - Fixes error: 'EOF: command not found' and 'here-document delimited by end-of-file' that appeared on VM login
- Added new '📤 Next Steps' section before Troubleshooting - Step 1: Add a logo (256x256 PNG requirements) - Step 2: Submit to marketplace with complete workflow: - Fork and branch creation - Adding files and committing - Creating Pull Request with template - Includes PR description template with checklist - Helps users complete the full appliance submission process
- Downloaded official Nextcloud logo from GitHub - Resized to 256x256 PNG with transparent background - Ready for OpenNebula marketplace display
- Add step-by-step instructions for creating/downloading logos - Explain how to resize logos to 256x256 PNG - Document FireEdge assets directory deployment - Show how to update OpenNebula images and templates with logo path - Include verification steps in Sunstone UI - Add complete Nextcloud example
…appliance.sh Fix bootstrap error when mounting Docker socket as volume: 'mkdir: cannot create directory /var/run/docker.sock: File exists' The script now checks if the host path exists before attempting to create it as a directory. This prevents errors when mounting socket files or device files as volumes. Changes: - Add existence check: if [ ! -e "$host_path" ] - Only create directory if path doesn't exist - Prevents mkdir errors on socket files like /var/run/docker.sock
- Added Nextcloud configuration example with Docker socket volume mount - Included note about web interface access on port 8080 - Shows proper volume configuration for AIO mastercontainer
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add Appliance Creation Documentation
Description
This PR adds documentation for creating OpenNebula marketplace appliances from Docker containers.
Files Added
docs/CREATE_APPLIANCE_TUTORIAL.md- Complete step-by-step tutorialdocs/QUICK_START.md- Quick reference guideWhat's Included
CREATE_APPLIANCE_TUTORIAL.md:
QUICK_START.md: