Beginner's Guides (2 articles: ESPHome on Docker Desktop & Adding Devices) #4411
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
WalkthroughThis pull request introduces two new beginner guides: one for adding devices to ESPHome and another for installing ESPHome on Docker Desktop. The first guide provides a comprehensive step-by-step approach for beginners, covering device setup, Wi-Fi configuration, and YAML customization. The second guide details the installation and management of ESPHome within a Docker Desktop environment. Additionally, a hyperlink in the Changes
Suggested reviewers
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Outside diff range and nitpick comments (9)
guides/beginners_guide_docker_desktop.rst (6)
4-7: Consider enhancing the SEO metadata.The SEO description could be more descriptive to improve search engine visibility. Consider expanding it to include key benefits or the target audience.
.. seo:: - :description: Installing ESPHome On Docker Desktop (For Beginners) + :description: A step-by-step beginner's guide to installing and running ESPHome on Docker Desktop, with detailed instructions for Windows, Mac, and Linux users. :image: docker-mark-blue.svg
13-18: Add system requirements section.Consider adding specific system requirements for running Docker Desktop effectively, such as:
- Minimum CPU/RAM requirements
- Supported Windows/Mac versions
- Required disk space (beyond the general mention in later sections)
23-26: Add platform-specific path examples.Consider using tabs to show recommended paths for different operating systems:
.. tabs:: .. tab:: Windows Example path: ``D:\Docker\esphome`` .. tab:: Linux Example path: ``/home/user/docker/esphome`` .. tab:: MacOS Example path: ``~/docker/esphome``
34-37: Add common troubleshooting steps.Consider adding a troubleshooting section addressing common installation issues:
- WSL installation failures on Windows
- Virtualization not enabled in BIOS
- Common permission issues
75-80: Add security considerations.Consider adding security best practices:
- Avoid using default ports (6052) to reduce exposure
- Mention firewall configuration if needed
- Discuss the implications of volume mounting and file permissions
196-201: Enhance navigation section.Consider adding:
- A "Prerequisites" section at the start
- A "Next Steps" section with more specific guides
- Links to troubleshooting resources
guides/beginners_guide_adding_devices.rst (2)
24-26: Consider enhancing security recommendationsWhile the guide correctly emphasizes using secrets, consider adding:
- A note about not sharing YAML files with secrets
- Best practices for securing the web server component
- Recommendations for strong password policies
116-116: Update the future date referenceThe note references November 4, 2024, which is a future date. Consider using a more current date or removing the specific date reference to avoid confusion.
index.rst (1)
31-32: Consider adding a link to the Docker Desktop guide.Since the PR introduces both an "Adding Devices" guide and a "Docker Desktop" guide for beginners, consider adding a link to the Docker Desktop guide in the "Getting started" section as well. This would provide clear visibility to both beginner-friendly paths.
Example addition:
<a class="reference" href="/guides/beginners_guide_adding_devices.html"> adding devices (for beginners) </a> </li> <li> + <a class="reference" href="/guides/beginners_guide_docker_desktop.html"> + Docker Desktop (for beginners) + </a> + </li> + <li>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
⛔ Files ignored due to path filters (36)
guides/images/noob_dashboard_1a.pngis excluded by!**/*.pngguides/images/noob_dashboard_1b.pngis excluded by!**/*.pngguides/images/noob_dashboard_1c.pngis excluded by!**/*.pngguides/images/noob_dashboard_2a.pngis excluded by!**/*.pngguides/images/noob_dashboard_2b.pngis excluded by!**/*.pngguides/images/noob_dashboard_2c.pngis excluded by!**/*.pngguides/images/noob_dashboard_2d.pngis excluded by!**/*.pngguides/images/noob_dashboard_2e.pngis excluded by!**/*.pngguides/images/noob_dashboard_2f.pngis excluded by!**/*.pngguides/images/noob_dashboard_2g.pngis excluded by!**/*.pngguides/images/noob_dashboard_3a.pngis excluded by!**/*.pngguides/images/noob_dashboard_3b.pngis excluded by!**/*.pngguides/images/noob_dashboard_3c.pngis excluded by!**/*.pngguides/images/noob_dashboard_3d.gifis excluded by!**/*.gifguides/images/noob_dashboard_3d.pngis excluded by!**/*.pngguides/images/noob_dashboard_3e.pngis excluded by!**/*.pngguides/images/noob_dashboard_3f.pngis excluded by!**/*.pngguides/images/noob_dashboard_3g.pngis excluded by!**/*.pngguides/images/noob_dashboard_4a.pngis excluded by!**/*.pngguides/images/noob_dashboard_4b.pngis excluded by!**/*.pngguides/images/noob_dashboard_4c.pngis excluded by!**/*.pngguides/images/noob_dashboard_4d.pngis excluded by!**/*.pngguides/images/noob_dashboard_4e.pngis excluded by!**/*.pngguides/images/noob_docker_1.pngis excluded by!**/*.pngguides/images/noob_docker_2.pngis excluded by!**/*.pngguides/images/noob_docker_3.pngis excluded by!**/*.pngguides/images/noob_docker_4.pngis excluded by!**/*.pngguides/images/noob_docker_4b.pngis excluded by!**/*.pngguides/images/noob_docker_5.pngis excluded by!**/*.pngguides/images/noob_docker_6.pngis excluded by!**/*.pngguides/images/noob_docker_7.pngis excluded by!**/*.pngguides/images/noob_docker_8.pngis excluded by!**/*.pngguides/images/noob_docker_9.pngis excluded by!**/*.pngguides/images/noob_docker_9b.pngis excluded by!**/*.pngimages/docker-mark-blue.svgis excluded by!**/*.svgsvg2png/docker-mark-blue.pngis excluded by!**/*.png
📒 Files selected for processing (3)
guides/beginners_guide_adding_devices.rst(1 hunks)guides/beginners_guide_docker_desktop.rst(1 hunks)index.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
guides/beginners_guide_adding_devices.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
guides/beginners_guide_docker_desktop.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
index.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
🪛 Gitleaks
guides/beginners_guide_adding_devices.rst
69-69: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🔇 Additional comments (3)
guides/beginners_guide_adding_devices.rst (2)
1-7: Well-structured documentation with clear organization!
The document follows RST best practices with proper headings, sections, and image formatting.
1-621: Excellent beginner-friendly guide with comprehensive coverage!
The guide successfully achieves its goal of providing clear, step-by-step instructions for beginners. It includes:
- Well-structured content with clear explanations
- Proper use of examples and images
- Good security practices with secrets
- Helpful troubleshooting tips
Minor improvements suggested above will further enhance the guide's quality.
🧰 Tools
🪛 Gitleaks
69-69: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
index.rst (1)
31-32: LGTM! The link update improves navigation for beginners.
The change appropriately redirects users from the command-line guide to the new beginner-friendly guide for adding devices, which aligns well with making the documentation more accessible to new users.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (1)
guides/beginners_guide_docker_desktop.rst (1)
39-41: Consider highlighting disk space requirements.The disk space requirements are important information that could be lost in the paragraph. Consider making this a note or warning block for better visibility:
-Please note that although Docker Desktop is not particularly large, containers like ESPHome can be. And the compilation of ESPHome binaries -can take up a lot of space, too. You might be okay with 5GB free space but 10GB or more is highly recommended as a minimum since building -binaries can also take up space. +.. warning:: + + Ensure you have sufficient disk space: + - Docker Desktop installation: ~2GB + - ESPHome container and binaries: 5-10GB recommended minimum + - Additional space for compiled firmware
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
guides/beginners_guide_adding_devices.rst(1 hunks)guides/beginners_guide_docker_desktop.rst(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- guides/beginners_guide_adding_devices.rst
🧰 Additional context used
📓 Path-based instructions (1)
guides/beginners_guide_docker_desktop.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
🔇 Additional comments (4)
guides/beginners_guide_docker_desktop.rst (4)
27-46: LGTM!
The Docker Desktop installation instructions are clear and include appropriate links to official documentation for troubleshooting.
191-201: LGTM!
The navigation and reference links are well-organized and provide appropriate paths for users to continue their journey.
141-142:
Add security warning for third-party container.
The recommendation to use adamus1red/ouroboros should include:
- Security implications:
- Third-party container with access to Docker socket
- Potential security risks of automatic updates
- Container verification steps:
- Checking container signatures
- Verifying source code
- Alternative update methods:
- Manual updates
- Using Docker's native watchtower
4-7: Verify the Docker logo image path and licensing.
Please ensure that:
- The image file
docker-mark-blue.svgexists in the images directory - We have appropriate rights to use the Docker logo
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
guides/beginners_guide_docker_desktop.rst (3)
25-26: Add OS-specific path examples for Linux and Mac users.While the Windows path example is clear, consider adding examples for Linux and Mac users:
-I recommend something easy to find. The example below uses ``D:\Docker\esphome`` but anything easy to find will be good. +I recommend something easy to find. Here are examples for different operating systems: + +* Windows: ``D:\Docker\esphome`` +* Linux: ``~/docker/esphome`` or ``/home/username/docker/esphome`` +* Mac: ``~/docker/esphome`` or ``/Users/username/docker/esphome`` + +Choose any location that's easy for you to find and remember.
76-78: Add note about potential port conflicts.Consider adding a note about what to do if port 6052 is already in use:
Also, set the port to use to access the GUI. The default is ``6052``. + +.. note:: + + If port 6052 is already in use on your system, you can use a different port number. + Just remember to use the new port number when accessing the ESPHome dashboard in your browser.
186-191: Enhance the warning note about automatic updates.The current note could be more explicit about the potential risks:
- It is not actually best practice to perform updates automatically like this but it is a good way to automate the process if you are only running one container. - - You should probably check ESPHome's :doc:`Release Notes </changelog/index>` before, during, or after an update to see if there are any changes that affect your devices. + While automatic updates can be convenient, they come with risks: + + 1. Breaking changes in new versions could affect your devices + 2. Updates might occur at inconvenient times + 3. Rollback might be needed if issues occur + + It's recommended to: + + * Review ESPHome's :doc:`Release Notes </changelog/index>` before updates + * Consider manual updates for better control + * Keep backups of your configuration + + If you choose automatic updates, monitor your devices after updates for any issues.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (3)
guides/beginners_guide_adding_devices.rst(1 hunks)guides/beginners_guide_docker_desktop.rst(1 hunks)index.rst(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- guides/beginners_guide_adding_devices.rst
- index.rst
🧰 Additional context used
📓 Path-based instructions (1)
guides/beginners_guide_docker_desktop.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
📓 Learnings (1)
guides/beginners_guide_docker_desktop.rst (1)
Learnt from: trip5
PR: esphome/esphome-docs#4411
File: guides/beginners_guide_docker_desktop.rst:76-81
Timestamp: 2024-11-04T17:44:47.417Z
Learning: In the 'Beginner's Guide to Installing ESPHome on Docker Desktop' (`guides/beginners_guide_docker_desktop.rst`), when using Docker Desktop on Windows, it's unnecessary to add memory limits to the container, as Windows already handles resource limiting.
|
The nitpick suggestions were pretty good. I'll put them in. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
guides/beginners_guide_docker_desktop.rst (3)
15-15: Consider clarifying performance requirements.The statement about performance on "under-powered machines" is vague. Consider providing specific minimum system requirements (CPU, RAM) for running Docker Desktop with ESPHome smoothly.
-Docker Desktop can run Linux containers like ESPHome very well, although it may be slow on under-powered machines like "just for work" notebooks. +Docker Desktop can run Linux containers like ESPHome very well, although it may be slow on machines with less than 4GB RAM or dual-core processors. For optimal performance, we recommend at least 8GB RAM and a quad-core processor.
64-66: Add container image verification step.Consider adding instructions to verify the official ESPHome image. This helps users ensure they're pulling the correct, secure image.
-Type ``esphome`` in the search box. The official ESPHome image belongs to the DockerHub member ``esphome`` so it should appear at the top as ``esphome/esphome``. +Type ``esphome`` in the search box. The official ESPHome image belongs to the DockerHub member ``esphome`` so it should appear at the top as ``esphome/esphome``. You can verify this is the official image by checking for the "Official Image" or "Verified Publisher" badge on Docker Hub. -Next to that image, you can select the version but unless you have a specific problem, the ``latest`` is the best to use. Click ``Pull`` to download the image. +Next to that image, you can select the version but unless you have a specific problem, the ``latest`` is the best to use. Click ``Pull`` to download the image. The image will be verified automatically during download.
219-224: Add troubleshooting section.Consider adding a "Troubleshooting" section before "See Also" to help users resolve common issues they might encounter, such as:
- Container startup failures
- Network access issues
- Volume mounting problems
- Common error messages and their solutions
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
guides/beginners_guide_docker_desktop.rst(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
guides/beginners_guide_docker_desktop.rst (1)
Pattern **: - Do not generate or add any sequence diagrams
📓 Learnings (1)
guides/beginners_guide_docker_desktop.rst (1)
Learnt from: trip5
PR: esphome/esphome-docs#4411
File: guides/beginners_guide_docker_desktop.rst:76-81
Timestamp: 2024-11-04T17:44:47.417Z
Learning: In the 'Beginner's Guide to Installing ESPHome on Docker Desktop' (`guides/beginners_guide_docker_desktop.rst`), when using Docker Desktop on Windows, it's unnecessary to add memory limits to the container, as Windows already handles resource limiting.
This comment was marked as spam.
This comment was marked as spam.
|
Thank you @trip5 for this contribution, indeed it's a bit hard for beginners to grasp what steps are needed to set up esphome for the first time. |
|
A lot of minor edits, too. I think I had stuck to 140-150 character lines so I went through it and restructured so all but |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
guides/beginners_guide_docker_desktop.rst (3)
8-9: Approachable Introduction Text
The introductory sentence is friendly and approachable. Consider rephrasing "not so tech-orientated" to "not very tech-savvy" or "non-technical" to enhance clarity for the target audience.
16-22: Good Discussion of Performance Considerations
The guide mentions potential performance issues on under-powered machines. To further improve clarity, consider rephrasing the phrase “under-powered machines like ‘just for work’ notebooks” to a more standardized wording (e.g., “lower-performance laptops”).
104-109: Precise Volume and Environment Variable Setup
The directions for mapping volumes (notably using the exact container path “/config”) and setting the “TZ” environment variable are spot on. However, the phrase “Canonical-types are best” might benefit from clarification (e.g., “use standard TZ identifiers”).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
guides/beginners_guide_adding_devices.rst(1 hunks)guides/beginners_guide_docker_desktop.rst(1 hunks)index.rst(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- index.rst
- guides/beginners_guide_adding_devices.rst
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
guides/beginners_guide_docker_desktop.rst
🧠 Learnings (1)
guides/beginners_guide_docker_desktop.rst (1)
Learnt from: trip5
PR: esphome/esphome-docs#4411
File: guides/beginners_guide_docker_desktop.rst:76-81
Timestamp: 2024-11-12T12:41:58.692Z
Learning: In the 'Beginner's Guide to Installing ESPHome on Docker Desktop' (`guides/beginners_guide_docker_desktop.rst`), when using Docker Desktop on Windows, it's unnecessary to add memory limits to the container, as Windows already handles resource limiting.
🔇 Additional comments (30)
guides/beginners_guide_docker_desktop.rst (30)
1-7: Effective Title and SEO Block
The document’s title is clear and inviting, and the SEO metadata (description and image) is well defined. This helps with search engine visibility and informs users about the guide’s purpose.
10-15: Clear Docker Desktop Section Introduction
This section effectively introduces Docker Desktop as a simple entry point—especially for users unfamiliar with Home Assistant. The brief explanation sets the stage well for beginners.
24-35: Comprehensive Folder Setup Instructions
The steps for preparing directories for Docker and ESPHome files are clear and include relevant examples across Windows, Linux, and Mac. This practical guidance will surely help beginners.
38-45: Detailed Docker Desktop Installation Guidance
The instructions for downloading and installing Docker Desktop—including dependency notes for Windows (WSL) and Mac (Apple Virtualization Framework)—are thorough and helpful for newcomers.
47-51: Useful Troubleshooting and Reference Links
Providing direct links to the official Docker documentation for Windows, Linux, and Mac helps users resolve installation issues. The formatting of these links in reStructuredText is correct.
53-57: Reasonable Disk Space Recommendations
The guide sets clear expectations by recommending at least 10GB free space due to potential space usage from container binaries. This practical advice is useful for users who may be unaware of resource demands.
58-61: Clear Login and Reboot Instructions
The note about Docker login and potential reboot requirements is brief yet sufficient. It reassures users that these steps are normal parts of the setup process.
62-69: Straightforward Container Addition Instructions
The “Add the ESPHome container” section clearly explains how to download the official image through Docker Desktop. The step‐by‐step guidance—including clicking “Images” and “Search images to run”—is intuitive for beginners.
73-75: Clear Image Identification Process
Instructions to search for “esphome” and identify the official DockerHub image (esphome/esphome) are precise. Users should have no difficulty following these directions.
76-81: Concise Image Pulling Instructions
The guide’s directions to select a version (with “latest” suggested) and click “Pull” are straightforward. This ensures that users can quickly download the ESPHome image without confusion.
82-88: Clear Restart Instructions
The explanation on verifying the image download and proceeding to “Run” the container is well structured. The sequential presentation aids user understanding.
90-94: Effective Optional Settings Overview
The guidance on expanding optional settings (e.g., container name, port configuration) is detailed and easy to follow. This ensures even beginners can correctly set up their container environment.
95-103: Detailed Port Configuration and Run Options
These instructions clearly cover the need to set appropriate port values and mention alternatives if the default port is in use. The clarity in these steps is essential for avoiding common pitfalls.
111-124: Well-Illustrated Container Launch Steps
The steps to start the container—including handling Windows network access prompts—are clearly described. The accompanying figure (noob_docker_4) reinforces these instructions effectively.
125-131: Clear Container Status Confirmation
The guide shows users how to verify that the image is running by checking the “Images” and “Run” buttons. The descriptive alt texts for the figures add to overall clarity.
132-141: Helpful Docker Desktop Management Tips
The section covering Docker Desktop management (accessing settings via the gear icon) is succinct and informative, aiding users in navigating the interface.
142-148: Straightforward Update Instructions for Docker Desktop
Advice on updating Docker Desktop itself is clear and supported by figures, which helps maintain user confidence in managing their system.
149-156: Important Reminder on Container Recreation
Emphasizing that the old container must be stopped and deleted before an update is a crucial point and is communicated clearly. This helps prevent user confusion during the update process.
157-162: Clear Process for Updating the ESPHome Container
The walk-through for updating the container via the “Pull” option is concise, ensuring that users understand the steps required to keep their installation current.
163-167: Useful Visual Aid for Update Process
The figure provided here aids user comprehension of how to trigger container updates. Visual guides like this can greatly enhance the user experience.
168-171: Reassuring Reminder on Configuration Persistence
The guide reassures users that their configurations remain intact even after recreating the container. This is a very helpful reassurance for beginners.
172-176: Introduction to Automated Updates
The section introducing automated updates with Ouroboros is well demarcated and offers an advanced tip without overwhelming the primary guide.
177-179: Guidance on Using Ouroboros for Automatic Updates
The instructions for pulling and running the Ouroboros container are clear. Given previous discussions—where additional security details for third-party containers were considered unnecessary—this section aligns well with the overall guide.
181-185: Effective Use of Visuals for Ouroboros Setup
The figure illustrating the Ouroboros container option clearly supports the text and improves user understanding.
186-192: Concise Optional Settings for Ouroboros
The instructions for specifying optional settings when running the Ouroboros container are clear and appropriately detailed.
193-216: Well-Organized Docker Socket Configuration
Using tabs to provide OS-specific instructions for configuring the docker.sock path is an excellent approach. It neatly separates instructions for Windows, Linux, and macOS, which will help prevent common setup errors.
217-221: Clear Environment Variable Configuration for Automated Updates
Setting the necessary environment variables for the Ouroboros container is clearly instructed. This precision aids in avoiding misconfigurations during automation.
223-238: Thoughtful Disclaimer on Automatic Updates Risks
The risk warning is comprehensive and helps users understand that automatic updates, while convenient, come with potential downsides. This balanced view encourages informed decision-making.
239-244: Smooth Transition to Next Steps
The “What’s Next?” section creates an effective call-to-action by linking to the guide for adding devices. This helps maintain user engagement and guides them along the learning path.
245-250: Useful ‘See Also’ Section
The final “See Also” list provides additional navigational aids and related content links, reinforcing the guide’s role within the broader documentation.
Short & concise and link for issues. Good. Co-authored-by: Keith Burzinski <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
guides/beginners_guide_docker_desktop.rst (1)
95-111: Container Configuration Details Are Thorough and Unambiguous
The section explains how to expand optional settings, set a container name, choose a port, configure the volume mapping, and set theTZenvironment variable.
Note: There is a minor typo on line 109: "TZ indentifier" should be "TZ identifier."
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
guides/beginners_guide_adding_devices.rst(1 hunks)guides/beginners_guide_docker_desktop.rst(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- guides/beginners_guide_adding_devices.rst
🧰 Additional context used
📓 Path-based instructions (1)
`**`: - Do not generate or add any sequence diagrams
**: - Do not generate or add any sequence diagrams
guides/beginners_guide_docker_desktop.rst
🧠 Learnings (1)
guides/beginners_guide_docker_desktop.rst (1)
Learnt from: trip5
PR: esphome/esphome-docs#4411
File: guides/beginners_guide_docker_desktop.rst:76-81
Timestamp: 2024-11-12T12:41:58.692Z
Learning: In the 'Beginner's Guide to Installing ESPHome on Docker Desktop' (`guides/beginners_guide_docker_desktop.rst`), when using Docker Desktop on Windows, it's unnecessary to add memory limits to the container, as Windows already handles resource limiting.
🔇 Additional comments (15)
guides/beginners_guide_docker_desktop.rst (15)
1-7: Title and SEO Metadata are Clearly Defined
The title and the accompanying SEO directive are well-crafted to enhance discoverability and set the tone for the guide.
8-9: Introduction Sets the Guide’s Purpose Effectively
A brief introductory statement informs newcomers that this guide will help them start with ESPHome using Docker Desktop.
10-18: Docker Desktop Section Explains the Rationale Well
The text clearly explains why Docker Desktop is a good starting point for those unfamiliar with ESPHome and Home Assistant.
24-37: Preparation Instructions Are Detailed and Accessible
The step-by-step instructions for creating folders across Windows, Linux, and Mac are very beginner-friendly.
38-46: Installation Instructions Are Comprehensive
The guide provides clear, OS-specific installation steps and mentions necessary dependencies, which should help prevent common pitfalls.
47-56: Disk Space and Troubleshooting Guidance is Helpful
The note on disk space requirements and a pointer to Docker’s documentation for troubleshooting installation issues add valuable context for users.
57-61: Post-Installation Instructions Are Clear
The guidance on handling Docker’s login prompt and potential reboot requirements is concise and useful.
62-72: Container Addition Instructions Are Well-Documented
Steps to locate and download the ESPHome image through Docker Desktop, along with an illustrative figure, make this section clear and easy to follow.
73-81: Image Search and Pull Process is Well-Described
The instructions for searching for the image, verifying ownership via DockerHub, and pulling the image are straightforward.
82-89: Launching the Container is Clearly Illustrated
The step of confirming the image appears and then clicking the “Run” button is well-supported by figures and clear language.
112-124: Figures Enhance the Guide’s Clarity
The detailed figure directives (with alt text and sizing) provide clear visual guidance, which is especially beneficial for beginners.
125-162: Container Management and Update Workflow is Comprehensive
The guide explains how to manage the running container, including restarting and updating it. The note about stopping and deleting the container before updating the ESPHome image is highly useful.
171-220: Automation of Updates via Ouroboros is Well Explained
The step-by-step instructions for setting up Ouroboros—including OS-specific configuration for docker.sock and setting the required environment variables—are detailed and clear. Prior security concerns for third-party containers were noted in past reviews, but it’s clear the author has deemed them inapplicable here.
221-236: Risk Considerations for Automatic Updates are Clearly Communicated
The warning effectively outlines potential risks associated with automatic updates and provides recommendations for best practices, which is essential for ensuring user awareness.
237-248: Call-to-Action and Resource Links Are Concise and Effective
The concluding “What’s Next?” and “See Also” sections guide users to additional relevant resources, ensuring a seamless learning path.
Better explanation of secrets file Co-authored-by: Keith Burzinski <[email protected]>
|
@kbx81 Thanks a lot for helping out with this. Actually, I had a few users of my Clock firmware (which can use but doesn't require Home Assistant) ask numerous questions how to install, and I wanted to help ease the journey a bit. Do you actually have the ability to put this in ESPHome Docs? Is it alright that the main page will link to the "Beginner’s Guide to Adding Devices"? |
Happy to help -- thanks for putting in the effort! 🍻
We do need a friendly, detailed "beginner's guide" -- I think we have a bit of a gap there. Would we link to it from the main page? ...probably? We've been discussing various changes to our documentation, but nothing specific has come to mind yet and it's mostly just been kicking around ideas. |
|
Well, lol, I mean I already edited the main page as so: I'm no dummy at command line but putting "command line" on the front page as a "getting started" guide can be off-putting for new users... I tried (and failed) and I think only ESPHome OGs and hardcore users will go for it. But it might be useful (for everyone) to have both linked on the front? I just rechecked https://esphome.io/guides/getting_started_command_line and it's a little better than it was when I started this doc but... I think I glazed over when I saw "Go open that file in an editor of your choice." Maybe this one should be renamed to something to indicate it's for advanced users? |
All of the tooling is command-line based so it's pretty unavoidable once you get a bit deeper into ESPHome (beyond the EDB alone, that is)...and that's not to mention that the EDB is largely just showing you stuff you'd see if you were using the command line, anyway. EDIT: Sorry, didn't mean to express that we shouldn't move the command-line document elsewhere -- I agree, most new users tend to want an easier way to get started. 😅 We are working on bringing up some developer docs so maybe the CLI documentation can move there once that's a bit further along.
I recently re-worked the "from HA" guide and it's on my list to re-work the CLI guide, as well -- as I think you're suggesting, it could also use some work. haha |
|
EDB? Is that the WebUI for ESPHome? To be fair, I've managed quite well without resorting to command line (and from what I read, the Docker install doesn't even have it). Also, to be fair, Windows is "good enough" for most people and they think What reasons would there be to use the command line in ESPHome? -- I mean except esptool. BTW, I'm very willing to help out on the CLI guide if you'd like. I don't mind experimenting with it again! |
"ESPHome Device Builder" -- my informal name for the tool & saves a lot of typing. haha
Admittedly I'm sort of looking at this through the lens of a developer, so the EDB isn't really useful for me; I think if you have any desire at all to do development/poking around under the hood, the EDB starts to break down as it isn't particularly accommodating for that. It's a friendly front-end for editing YAML and getting it installed onto a device, but not so much a "real" development tool.
Literally all of the build tooling runs in a terminal. If you're doing anything more "advanced" than just editing YAML, compiling it and installing it onto a device, you end up in a terminal. haha A situation we see a lot of is people running the EDB as an add-on to an HA instance they've already set up on some SBC (Raspberry Pi, O-Droid or now even HA Yellow/Green). Compiling takes an eternity on most SBCs but we find a lot of people don't realize that there is "another way" and that you can run the ESPHome tooling locally and then compiling a config takes well under a minute as opposed to over an hour. Personal preference comes into the picture, too. I by far prefer to use VSCode as opposed to some other text editor running in my web browser -- it's not uncommon that I have many device configurations open simultaneously (in tabs) and am copy/pasting stuff between them. Doing that in the EDB is cumbersome at best. Keep in mind that I have nearly 60 ESPHome devices running here so I have a lot of configs...and that's not to mention all of the development work I do on a day-to-day basis. |
OK. This is true. Even compiling is a terminal. Usually non-interactive but terminal still.
Can confirm. Moved from a Pi 4 to an ODroid x86 for this exact reason. Never considered the compiler could be run locally.
Also true. I usually end up resorting to Notepad++ and VSStudio as well... and several tabs open as well. But for new users... they should figure out their own personal preference. And I think new users will (like me) start with 2 or 3 ESPHome devices. Some may never move past that. I myself still prefer Tasmota for switches and lights. The thought of having 20 more YAMLs - all of them almost the same - annoys me. But there's a tool in development |
|
There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. Thank you for your contributions. |
|
Not stale. |
Description: Two guides added
They are step-by-step guides with waaay too many pictures that should help people get their feet wet in ESPHome.
I think there are more than a few people out there who would love to get into ESPHome but the documentation is a bit dense.
Related issue (if applicable): None.
Pull request in esphome with YAML changes (if applicable): N/A
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/index.rstwhen creating new documents for new components or cookbook.Actually, I changed the link to "Getting Started with the ESPHome Command Line" to the new "Beginner’s Guide to Adding Devices" which contains links to the various methods of getting ESPHome running (just in case).