diff --git a/portainer/DOCS.md b/portainer/DOCS.md index 1c97e2ab0..2e68caf15 100644 --- a/portainer/DOCS.md +++ b/portainer/DOCS.md @@ -1,145 +1,32 @@ -# Home Assistant Community Add-on: Portainer - -Portainer is an open-source lightweight management UI which allows you to +Portainer can be used to execute custom commands in a docker container. It is an open-source lightweight management UI which allows you to easily manage a Docker host(s) or Docker swarm clusters. -It has never been so easy to manage Docker. Portainer provides a detailed -overview of Docker and allows you to manage containers, images, networks and -volumes. +# Quick start +- Add my repository using this link +[![Add repository on my Home Assistant][repository-badge]][repository-url] +- Install the portainer addon from my repo +- In the configuration panel of the addon, you can change the password +- In the main page of the addon, disable "Protection mode", then start the addon +- Login (default name is `admin`, default password is `homeassistant`) +- Click on `Primary` in the environement (at the center of the page) +- Click on `Containers` in the left menu bar +- Increase the number of items per page to see all your addons +- Click on the symbol `>_` next to the name of your selected addon to open the console page +- Either change the username, or more usually just click connect +- Type your commands, you have full access to the terminal of this specific container (this does not affect other parts of your HA system) -## WARNING +# Impact on your system +- There is no impact of installing, or running portainer +- Installing manually a custom container will modify your HA status to an unsupported/unhealthy state. You will be blocked from upgrading Home Assistant and upgrading any Add-ons you may have. Stopping this custom container will reset the normal status -The Portainer add-on is really powerful and gives you access to virtually -your whole system. While this add-on is created and maintained with care and -with security in mind, in the wrong or inexperienced hands, -it could damage your system. +# Tips and tricks -## Installation +## Reset database +Just change the password in your addon options and the database will be reset -To install this add-on, you'll first need to go to your profile and turn on -"Advanced Mode", once that is done go back to Home Assistant add-ons and search -for "Portainer" and install it as you would any other add-on. +## Further reference +- Here is a full guide on using it : https://codeopolis.com/posts/beginners-guide-to-portainer/ +- Old page on the HA community forum about portainer : https://community.home-assistant.io/t/home-assistant-community-add-on-portainer -To be able to use this add-on, you'll need to disable protection mode on this -add-on. Without it, the add-on is unable to access Docker. - -1. Search for the "Portainer" add-on in the Supervisor add-on store and - install it. -1. Set the "Protection mode" switch to off. -1. Start the "Portainer" add-on. -1. Check the logs of the "Portainer" add-on to see if everything went well. - -## Configuration - -**Note**: _Remember to restart the add-on when the configuration is changed._ - -Example add-on configuration: - -```yaml -log_level: info -agent_secret: password -``` - -**Note**: _This is just an example, don't copy and paste it! Create your own!_ - -### Option: `log_level` - -The `log_level` option controls the level of log output by the addon and can -be changed to be more or less verbose, which might be useful when you are -dealing with an unknown issue. Possible values are: - -- `trace`: Show every detail, like all called internal functions. -- `debug`: Shows detailed debug information. -- `info`: Normal (usually) interesting events. -- `warning`: Exceptional occurrences that are not errors. -- `error`: Runtime errors that do not require immediate action. -- `fatal`: Something went terribly wrong. Add-on becomes unusable. - -Please note that each level automatically includes log messages from a -more severe level, e.g., `debug` also shows `info` messages. By default, -the `log_level` is set to `info`, which is the recommended setting unless -you are troubleshooting. - -### Option: `agent_secret` - -An option to set a shared agent secret. Must also be set in the remote agent -as an Environment variable. - -## Known issues and limitations - -By default all Home Assistant managed containers are hidden from Portainer. -This is recommended since fooling around with Home Assistant managed containers -can easily lead to a broken system. - -Access to these containers can be gained by going into Portainer -> -Settings -> Hidden containers. Then delete the listed hidden labels -(io.hass.type labels). **Only do this if you know what you're doing!** - -## Changelog & Releases - -This repository keeps a change log using [GitHub's releases][releases] -functionality. - -Releases are based on [Semantic Versioning][semver], and use the format -of `MAJOR.MINOR.PATCH`. In a nutshell, the version will be incremented -based on the following: - -- `MAJOR`: Incompatible or major changes. -- `MINOR`: Backwards-compatible new features and enhancements. -- `PATCH`: Backwards-compatible bugfixes and package updates. - -## Support - -Got questions? - -You have several options to get them answered: - -- The [Home Assistant Community Add-ons Discord chat server][discord] for add-on - support and feature requests. -- The [Home Assistant Discord chat server][discord-ha] for general Home - Assistant discussions and questions. -- The Home Assistant [Community Forum][forum]. -- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit] - -You could also [open an issue here][issue] GitHub. - -## Authors & contributors - -The original setup of this repository is by [Franck Nijhof][frenck]. - -For a full list of all authors and contributors, -check [the contributor's page][contributors]. - -## License - -MIT License - -Copyright (c) 2018-2021 Franck Nijhof - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - -[contributors]: https://github.com/hassio-addons/addon-portainer/graphs/contributors -[discord-ha]: https://discord.gg/c5DvZ4e -[discord]: https://discord.me/hassioaddons -[forum]: https://community.home-assistant.io/t/home-assistant-community-add-on-portainer/68836?u=frenck -[frenck]: https://github.com/frenck -[issue]: https://github.com/hassio-addons/addon-portainer/issues -[reddit]: https://reddit.com/r/homeassistant -[releases]: https://github.com/hassio-addons/addon-portainer/releases -[semver]: http://semver.org/spec/v2.0.0.htm +[repository-badge]: https://img.shields.io/badge/Add%20repository%20to%20my-Home%20Assistant-41BDF5?logo=home-assistant&style=for-the-badge +[repository-url]: https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons