feat: Enhance Docker environment handling and add comprehensive tests

[roble]

This pull request introduces significant improvements to the Saucebase installation workflow, focusing on robust handling of the application's domain/hostname, improved module compatibility checks, and enhanced failure recovery. The changes ensure that the app's domain is consistently captured, validated, and written to the environment file, and that users are guided through module compatibility and installation failures with clear prompts and resume instructions.

Domain/hostname handling:

• Added a --domain option to both InstallCommand and NewCommand, with interactive prompts and validation to ensure the app's hostname is captured, normalized, and stored in .env as APP_HOST. The domain is used for SSL certificate and web server configuration, and users are warned if the domain does not resolve locally. ([[1]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R27), [[2]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R156-R226), [[3]](https://github.com/saucebase-dev/installer/pull/20/files#diff-2bde8d3b845e6edd8ea70ad566edcf41f7193b3d3a4acd956ca3f273f15b6307R36), [[4]](https://github.com/saucebase-dev/installer/pull/20/files#diff-2bde8d3b845e6edd8ea70ad566edcf41f7193b3d3a4acd956ca3f273f15b6307R79-R80), [[5]](https://github.com/saucebase-dev/installer/pull/20/files#diff-2bde8d3b845e6edd8ea70ad566edcf41f7193b3d3a4acd956ca3f273f15b6307R137-R160), [[6]](https://github.com/saucebase-dev/installer/pull/20/files#diff-2bde8d3b845e6edd8ea70ad566edcf41f7193b3d3a4acd956ca3f273f15b6307L219-R252))

App identity and environment file updates:

• The installer now automatically sets APP_NAME, APP_SLUG, and APP_HOST in .env based on the app directory and chosen domain, replacing only default or empty values to avoid overwriting user edits. For native installs, APP_URL is also updated if needed. ([[1]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R390-R470), [[2]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R333-R334))

Module compatibility enforcement:

• Added a check to ensure that explicitly requested modules (via --modules) are compatible with the selected frontend stack. If incompatible modules are detected, the installation halts with a clear error message listing unsupported modules and their compatible stacks. ([[1]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R261-R296), [[2]](https://github.com/saucebase-dev/installer/pull/20/files#diff-b5ff597dd8114f9bca99d69eb3e0cd3ffda9a09c8fff431f90746330ade4645dR36-R77))

Failure handling and resume support:

• On installation failure, a callout is displayed with the failed step, guidance, and an exact, idempotent resume command that includes all user choices and options, allowing users to easily retry after fixing issues. ([[1]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R732-R814), [[2]](https://github.com/saucebase-dev/installer/pull/20/files#diff-b5ff597dd8114f9bca99d69eb3e0cd3ffda9a09c8fff431f90746330ade4645dR9-R11), [[3]](https://github.com/saucebase-dev/installer/pull/20/files#diff-b5ff597dd8114f9bca99d69eb3e0cd3ffda9a09c8fff431f90746330ade4645dR36-R77))

Utility and codebase robustness:

• Added utility methods such as optionOrNull for safer option retrieval, and improved code structure for reading and updating environment variables, quoting paths, and normalizing domains. ([[1]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166L73-R92), [[2]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R156-R226), [[3]](https://github.com/saucebase-dev/installer/pull/20/files#diff-24b2cabf7676cce3456251ae1ef517978994a79fd07642e97b0623743be6b166R390-R470))

These changes collectively make the installation process more user-friendly, reliable, and maintainable.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 50e43ebb-b111-4856-8b0c-a6c6900420d3

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}