|
| 1 | +# Home Assistant Community Add-on: Bookstack |
| 2 | + |
| 3 | +BookStack is a simple, self-hosted, easy-to-use platform for organising and |
| 4 | +storing information. Please support the developers of this software at |
| 5 | +[Bookstack]. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +The installation of this add-on is pretty straightforward and not different in |
| 10 | +comparison to installing any other Home Assistant add-on. |
| 11 | + |
| 12 | +1. Search for the "bookstack" add-on in the add-on store and install it. |
| 13 | +1. Start the "bookstack" add-on |
| 14 | +1. Check the logs of the "bookstack" add-on to see if everything went well. |
| 15 | +1. Default login information is admin@admin.com/password. |
| 16 | + |
| 17 | +## Configuration |
| 18 | + |
| 19 | +**Note**: _Remember to restart the add-on when the configuration is changed._ |
| 20 | + |
| 21 | +Example add-on configuration: |
| 22 | + |
| 23 | +```yaml |
| 24 | +log_level: info |
| 25 | +ssl: false |
| 26 | +certfile: fullchain.pem |
| 27 | +keyfile: privkey.pem |
| 28 | +``` |
| 29 | +
|
| 30 | +**Note**: _This is just an example, don't copy and paste it! Create your own!_ |
| 31 | +
|
| 32 | +### Option: `log_level` |
| 33 | + |
| 34 | +The `log_level` option controls the level of log output by the addon and can |
| 35 | +be changed to be more or less verbose, which might be useful when you are |
| 36 | +dealing with an unknown issue. Possible values are: |
| 37 | + |
| 38 | +- `trace`: Show every detail, like all called internal functions. |
| 39 | +- `debug`: Shows detailed debug information. |
| 40 | +- `info`: Normal (usually) interesting events. |
| 41 | +- `warning`: Exceptional occurrences that are not errors. |
| 42 | +- `error`: Runtime errors that do not require immediate action. |
| 43 | +- `fatal`: Something went terribly wrong. Add-on becomes unusable. |
| 44 | + |
| 45 | +Please note that each level automatically includes log messages from a |
| 46 | +more severe level, e.g., `debug` also shows `info` messages. By default, |
| 47 | +the `log_level` is set to `info`, which is the recommended setting unless |
| 48 | +you are troubleshooting. |
| 49 | + |
| 50 | +### Option: `ssl` |
| 51 | + |
| 52 | +Enables/Disables SSL (HTTPS) on the web interface of Bookstack |
| 53 | +Panel. Set it `true` to enable it, `false` otherwise. |
| 54 | + |
| 55 | +### Option: `certfile` |
| 56 | + |
| 57 | +The certificate file to use for SSL. |
| 58 | + |
| 59 | +**Note**: _The file MUST be stored in `/ssl/`, which is the default_ |
| 60 | + |
| 61 | +### Option: `keyfile` |
| 62 | + |
| 63 | +The private key file to use for SSL. |
| 64 | + |
| 65 | +**Note**: _The file MUST be stored in `/ssl/`, which is the default_ |
| 66 | + |
| 67 | +### Option: `proxy_host` |
| 68 | + |
| 69 | +If using a reverse proxy, the domain configured for example |
| 70 | +`https://www.example.com`. |
| 71 | + |
| 72 | +### Option: `remote_mysql_host` |
| 73 | + |
| 74 | +If using an external database, the hostname/address for the MYSQL/MariaDB |
| 75 | +database. |
| 76 | + |
| 77 | +### Option: `remote_mysql_database` |
| 78 | + |
| 79 | +Only applies if a remote MYSQL database is used, the name of the database. |
| 80 | + |
| 81 | +### Option: `remote_mysql_username` |
| 82 | + |
| 83 | +Only applies if a remote MYSQL database is used, the username with permissions. |
| 84 | + |
| 85 | +### Option: `remote_mysql_password` |
| 86 | + |
| 87 | +Only applies if a remote MYSQL database is used, the password of the above user. |
| 88 | + |
| 89 | +### Option: `remote_mysql_port` |
| 90 | + |
| 91 | +Only applies if a remote MYSQL database is used, the port that the database |
| 92 | +server is listening on. |
| 93 | + |
| 94 | +## Database usage |
| 95 | + |
| 96 | +By default, Bookstack will automatically use and configure the Home Assistant |
| 97 | +MariaDB addon which should be installed prior to startup, this can be changed |
| 98 | +within the configuration to use an external MySql/MariaDB Database. Please note |
| 99 | +that there is no easy upgrade path between the two options. |
| 100 | + |
| 101 | +## Known issues and limitations |
| 102 | + |
| 103 | +- SMTP support is disabled. |
| 104 | +- Ingress will not function due to the way the application stores image files. |
| 105 | + |
| 106 | +## Changelog & Releases |
| 107 | + |
| 108 | +This repository keeps a change log using [GitHub's releases][releases] |
| 109 | +functionality. The format of the log is based on |
| 110 | +[Keep a Changelog][keepchangelog]. |
| 111 | + |
| 112 | +Releases are based on [Semantic Versioning][semver], and use the format |
| 113 | +of ``MAJOR.MINOR.PATCH``. In a nutshell, the version will be incremented |
| 114 | +based on the following: |
| 115 | + |
| 116 | +- ``MAJOR``: Incompatible or major changes. |
| 117 | +- ``MINOR``: Backwards-compatible new features and enhancements. |
| 118 | +- ``PATCH``: Backwards-compatible bugfixes and package updates. |
| 119 | + |
| 120 | +## Support |
| 121 | + |
| 122 | +Got questions? |
| 123 | + |
| 124 | +You have several options to get them answered: |
| 125 | + |
| 126 | +- The [Home Assistant Community Add-ons Discord chat server][discord] for add-on |
| 127 | + support and feature requests. |
| 128 | +- The [Home Assistant Discord chat server][discord-ha] for general Home |
| 129 | + Assistant discussions and questions. |
| 130 | +- The Home Assistant [Community Forum][forum]. |
| 131 | +- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit] |
| 132 | + |
| 133 | +You could also [open an issue here][issue] GitHub. |
| 134 | + |
| 135 | +## Authors & contributors |
| 136 | + |
| 137 | +The original setup of this repository is by [Paul Sinclair][sinclairpaul]. |
| 138 | + |
| 139 | +For a full list of all authors and contributors, |
| 140 | +check [the contributor's page][contributors]. |
| 141 | + |
| 142 | +## License |
| 143 | + |
| 144 | +MIT License |
| 145 | + |
| 146 | +Copyright (c) 2019-2020 Paul Sinclair |
| 147 | + |
| 148 | +Permission is hereby granted, free of charge, to any person obtaining a copy |
| 149 | +of this software and associated documentation files (the "Software"), to deal |
| 150 | +in the Software without restriction, including without limitation the rights |
| 151 | +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 152 | +copies of the Software, and to permit persons to whom the Software is |
| 153 | +furnished to do so, subject to the following conditions: |
| 154 | + |
| 155 | +The above copyright notice and this permission notice shall be included in all |
| 156 | +copies or substantial portions of the Software. |
| 157 | + |
| 158 | +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 159 | +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 160 | +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 161 | +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 162 | +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 163 | +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 164 | +SOFTWARE. |
| 165 | + |
| 166 | +[bookstack]: https://www.bookstackapp.com/ |
| 167 | +[contributors]: https://github.com/hassio-addons/addon-bookstack/graphs/contributors |
| 168 | +[discord-ha]: https://discord.gg/c5DvZ4e |
| 169 | +[discord]: https://discord.me/hassioaddons |
| 170 | +[forum]: https://community.home-assistant.io/t/community-hass-io-xxxxx/xxxxx |
| 171 | +[sinclairpaul]: https://github.com/sinclairpaul |
| 172 | +[issue]: https://github.com/hassio-addons/addon-bookstack/issues |
| 173 | +[keepchangelog]: http://keepachangelog.com/en/1.0.0/ |
| 174 | +[reddit]: https://reddit.com/r/homeassistant |
| 175 | +[releases]: https://github.com/hassio-addons/addon-bookstack/releases |
| 176 | +[semver]: http://semver.org/spec/v2.0.0 |
0 commit comments