Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Conversation

josecelano
Copy link
Member

Summary

This PR resolves issue #24 by implementing automatic waiting logic in deployment commands to prevent premature execution failures and improve user experience.

Problem Solved

Previously, the three-step deployment workflow would fail if commands were run too quickly:

make infra-apply ENVIRONMENT=local    # Would succeed
make app-deploy ENVIRONMENT=local     # Would fail if run immediately 
make app-health-check ENVIRONMENT=local # Would fail due to services not ready

Users had to manually wait and guess timing, leading to poor UX and unreliable deployments.

Solution Implemented

Solution 1: Default automatic waiting with SKIP_WAIT option for advanced users.

Key Features

  • Automatic VM readiness waiting in make infra-apply
  • Automatic service health waiting in make app-deploy
  • SKIP_WAIT parameter for advanced users (SKIP_WAIT=true)
  • Clear progress feedback during operations
  • Bug fix: Resolved OpenTofu working directory issues
  • Comprehensive testing: Manual + E2E validation

Changes Made

Infrastructure Layer

  • shell-utils.sh: Added wait_for_vm_ip() and wait_for_cloud_init_completion() functions
  • provision-infrastructure.sh: Automatic VM readiness waiting + bug fixes
  • deploy-app.sh: Enhanced service health waiting with better logging

User Interface

  • Makefile: Added SKIP_WAIT parameter support for infra-apply and app-deploy
  • Documentation: Updated guides with new workflow and sudo cache management

Testing & Quality

  • test-e2e.sh: Updated to use centralized waiting functions
  • CI validation: All tests pass, including comprehensive E2E testing

Testing Results

✅ Manual Testing

make infra-apply ENVIRONMENT=local    # ✅ Waits for VM + cloud-init
make app-deploy ENVIRONMENT=local     # ✅ Waits for service health
make app-health-check ENVIRONMENT=local # ✅ 100% success rate

✅ E2E Testing

  • Total test time: 2m 40s
  • Health checks: 14/14 passed (100%)
  • Smoke tests: 0 failures
  • Clean workflow: Infrastructure → Application → Health → Cleanup

✅ Advanced User Workflow

make infra-apply ENVIRONMENT=local SKIP_WAIT=true    # ✅ Fast execution
make app-deploy ENVIRONMENT=local SKIP_WAIT=true     # ✅ No waiting

Impact

🎯 User Experience

  • Eliminates manual timing guesswork
  • Provides clear progress feedback
  • Maintains advanced user flexibility
  • Fixes confusing warning messages

🏗️ Technical Benefits

  • Robust deployment workflow
  • Better error handling and logging
  • Centralized waiting logic
  • Improved twelve-factor compliance

Documentation

Updated documentation includes:

  • Contributor guide: Sudo cache management, workflow improvements
  • Cloud deployment guide: Updated with new parameters
  • Testing coverage: Both manual and automated scenarios

Breaking Changes

None - This is a pure UX improvement that maintains backward compatibility.

Related Issues

Review Notes

  • All CI tests pass ✅
  • E2E testing validates complete workflow ✅
  • Manual testing confirms UX improvements ✅
  • Documentation updated ✅
  • No breaking changes ✅

The three-step deployment workflow now works seamlessly without manual intervention, while preserving advanced user capabilities.

- Add documentation for intelligent sudo cache management functions
- Document ensure_sudo_cached(), is_sudo_cached(), run_with_sudo() functions
- Explain automatic prompting and cache preparation to improve UX
- Add testing information for sudo cache functionality
- Update contributor guidelines for infrastructure operations
…ands

Add intelligent waiting logic to prevent premature command execution:

Infrastructure improvements:
- Add wait_for_vm_ip() and wait_for_cloud_init_completion() to shell-utils.sh
- Enhance provision-infrastructure.sh with automatic VM readiness waiting
- Fix tofu output command working directory issue causing warning messages
- Add SKIP_WAIT parameter support for advanced users who want faster execution

Application improvements:
- Enhance deploy-app.sh with conditional service health waiting
- Improve deployment logging and progress feedback
- Maintain existing wait_for_services functionality with better UX

Makefile integration:
- Add SKIP_WAIT parameter support to infra-apply and app-deploy targets
- Provide user-friendly messaging about waiting behavior
- Enable advanced users to bypass waiting with SKIP_WAIT=true

Testing updates:
- Update E2E tests to use centralized waiting functions
- Ensure tests validate both default waiting and skip-wait scenarios
- Maintain comprehensive test coverage for improved workflow

User experience impact:
- Eliminates manual waiting between make infra-apply → make app-deploy → make app-health-check
- Provides clear progress feedback during deployment operations
- Preserves advanced user workflow with optional skip functionality
- Fixes confusing output messages caused by working directory bug

This resolves the poor UX where deployment commands would fail if run too quickly,
implementing Solution 1 from the GitHub issue analysis.
@josecelano josecelano requested a review from da2ce7 July 31, 2025 15:39
@josecelano
Copy link
Member Author

ACK ad974e0

@josecelano josecelano self-assigned this Jul 31, 2025
@josecelano josecelano added Code Cleanup / Refactoring Tidying and Making Neat - Developer - Torrust Improvement Experience - Admin - Enjoyable to Install and Setup our Software Enhancement / Feature Request Something New and removed - Developer - Torrust Improvement Experience labels Jul 31, 2025
@josecelano josecelano merged commit 49aa4f8 into main Jul 31, 2025
1 check passed
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

- Admin - Enjoyable to Install and Setup our Software Code Cleanup / Refactoring Tidying and Making Neat Enhancement / Feature Request Something New

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve UX: Add automatic waiting to infra-apply and app-deploy commands

1 participant