This document contains the rules and best practices for Ubuntu autoinstall configurations that I've learned through our work together.
- Ubuntu Version: 24.04 LTS
- Installation Type: ubuntu-desktop (NOT ubuntu-server)
- Target System: Desktop installation with LVM
- ALWAYS research and provide evidence before making any configuration changes
- NEVER change settings multiple times without clear justification
- ALWAYS show the source of your information (documentation, official guides, etc.)
- If uncertain, ASK instead of guessing
- Time is valuable - avoid trial and error approaches
Examples of required evidence:
- Official Ubuntu/Curtin documentation links
- Error message analysis with clear cause-effect relationship
- Tested configurations with proven results
- Community consensus from reliable sources
## Change Justification
- **What**: Specific change being made
- **Why**: Evidence-based reason for the change
- **Source**: Documentation or error analysis supporting this change
- **Expected Result**: What this change will fix/improve
All scripts MUST be idempotent - they should produce the same result whether run once or multiple times.
- Check before create:
if [[ ! -f "$file" ]]; then
create_file "$file"
fi
- Check before modify:
if ! grep -q "pattern" "$file"; then
echo "content" >> "$file"
fi
- Use state detection:
if systemctl is-enabled service 2>/dev/null; then
echo "Service already enabled"
else
systemctl enable service
fi
- Handle existing resources:
# Check for existing recovery keys
if ls /root/.luks-recovery-key-*.txt 2>/dev/null; then
read -p "Use existing recovery key? (y/N): " response
fi
YOU MUST validate all shell scripts before committing:
# Check syntax without executing
bash -n script.sh
# Must pass with no output (success) before proceeding
# Install shellcheck if not available
sudo apt-get install -y shellcheck
# Run shellcheck
shellcheck script.sh
# Fix all warnings except those explicitly documented as false positives
Invalid brace expansions:
# ❌ WRONG - Syntax error
for i in {1..5} {7..9}; do
# ✅ CORRECT - Valid alternatives
for i in {1..5} 7 8 9; do
for i in 1 2 3 4 5 7 8 9; do
Unquoted variables:
# ❌ WRONG - Breaks with spaces
if [ $var = "value" ]; then
# ✅ CORRECT - Always quote
if [ "$var" = "value" ]; then
Echo vs Printf:
# ❌ RISKY - Can fail with special characters
echo -n "$password" | command
# ✅ SAFE - Always works correctly
printf '%s' "$password" | command
Recovery keys and passwords MUST be safe for shell use:
- Use URL-safe Base64 for generated keys:
# Generate safe recovery key
openssl rand -base64 48 | tr -d '\n' | tr '+/' '-_'
- Validate input:
# Check for safe characters only
if ! [[ "$RECOVERY_KEY" =~ ^[A-Za-z0-9_=-]+$ ]]; then
print_error "Invalid characters in recovery key"
return 1
fi
- Use printf for safety:
# Always use printf instead of echo -n
printf '%s' "$variable" | cryptsetup command
Every script must include:
#!/usr/bin/env bash
set -euo pipefail
# Script description
# Usage: script.sh [options]
# Dependencies: list required tools
- ALWAYS run validation before attempting installation
- NEVER trust that valid YAML means valid autoinstall config
- ALWAYS check for known problematic packages (systemd-cryptenroll)
- USE the pre-install-check.sh script to catch issues early
- Run
bash -n script.sh
- MUST pass
- Run
shellcheck script.sh
- MUST pass or have documented exceptions
- Test idempotency - run twice, verify same result
- Test edge cases - empty variables, missing files, etc.
- Verify error handling - script should fail gracefully
Do what has been asked; nothing more, nothing less.
NEVER create files unless they're absolutely necessary for achieving your goal.
ALWAYS prefer editing an existing file to creating a new one.
NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.