Add troubleshooting section and firewall recommendation
Dominik Sander
1 changed files with 61 additions and 1 deletions
+ 61
- 1
doc/manual/installation.md
@@ -15,6 +15,8 @@ If you find a bug/error in this guide please **submit a pull request**. |
||
| 15 | 15 |
|
| 16 | 16 |
If not stated otherwise all commands should be run as user with sudo permissions or as root. |
| 17 | 17 |
|
| 18 |
+When having problems during the installation please check the [troubleshooting](#troubleshooting) section. |
|
| 19 |
+ |
|
| 18 | 20 |
## Overview |
| 19 | 21 |
|
| 20 | 22 |
The Huginn installation consists of setting up the following components: |
@@ -305,12 +307,14 @@ Visit YOUR_SERVER in your web browser for your first Huginn login. The setup has |
||
| 305 | 307 |
password |
| 306 | 308 |
|
| 307 | 309 |
|
| 308 |
-**Enjoy!** |
|
| 310 |
+**Enjoy!** :sparkles: :star: :fireworks: |
|
| 309 | 311 |
|
| 310 | 312 |
You can use `cd /home/huginn/huginn && sudo rake production:start` and `cd /home/huginn/huginn && sudo rake production:stop` to start and stop Huginn. |
| 311 | 313 |
|
| 312 | 314 |
Be sure to read the section about how to [update](./update.md) your Huginn installation as well! You can also use [Capistrano](./capistrano.md) to keep your installation up to date. |
| 313 | 315 |
|
| 316 |
+**Note:** We also recommend applying standard security practices to your server, including installing a firewall ([ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) is good on Ubuntu and also available for Debian). |
|
| 317 |
+ |
|
| 314 | 318 |
## Advanced Setup Tips |
| 315 | 319 |
|
| 316 | 320 |
### Using HTTPS |
@@ -341,3 +345,59 @@ cd /etc/nginx/ssl/ |
||
| 341 | 345 |
sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out huginn.crt -keyout huginn.key |
| 342 | 346 |
sudo chmod o-r huginn.key |
| 343 | 347 |
``` |
| 348 |
+ |
|
| 349 |
+## Troubleshooting |
|
| 350 |
+ |
|
| 351 |
+If something went wrong during the installation please make sure you followed the instructions and did not miss a step. |
|
| 352 |
+ |
|
| 353 |
+When your Huginn instance still is not working first run the self check: |
|
| 354 |
+ |
|
| 355 |
+ cd /home/huginn/huginn |
|
| 356 |
+ sudo rake production:check |
|
| 357 |
+ |
|
| 358 |
+We are sorry when you are still having issues, now please check the various log files for error messages: |
|
| 359 |
+ |
|
| 360 |
+#### Nginx error log `/var/log/nginx/huginn_error.log` |
|
| 361 |
+ |
|
| 362 |
+This file should be empty, it is the first place to look because `nginx` is the first application handling the request your are sending to Huginn. |
|
| 363 |
+ |
|
| 364 |
+Common problems: |
|
| 365 |
+ |
|
| 366 |
+* `connect() to unix:/home/huginn/huginn/tmp/sockets/unicorn.socket failed`: The Unicorn application server is not running, ensure you uncommented one of the example configuration below the `PRODUCTION` label in your [Profile](#install-init-script) and the unicorn config file (`/home/huginn/huginn/config/unicorn.rb`) exists. |
|
| 367 |
+* `138 open() "/home/huginn/huginn/public/..." failed (13: Permission denied)`: The `/home/huginn/huginn/public` directory needs to be readable by the nginx user (which is per default `www-data`) |
|
| 368 |
+ |
|
| 369 |
+ |
|
| 370 |
+#### Unicorn log `/home/huginn/huginn/log/unicorn.log` |
|
| 371 |
+ |
|
| 372 |
+Should only contain HTTP request log entries like: `10.0.2.2 - - [18/Aug/2015:21:15:12 +0000] "GET / HTTP/1.0" 200 - 0.0110` |
|
| 373 |
+ |
|
| 374 |
+If you see ruby exception backtraces or other error messages the problem could be one of the following: |
|
| 375 |
+ |
|
| 376 |
+* The configuration file `/home/huginn/huginn/config/unicorn.rb` does not exist |
|
| 377 |
+* Gem dependencies where not [installed](#install-gems) |
|
| 378 |
+ |
|
| 379 |
+#### Rails Application log `/home/huginn/huginn/log/production.log` |
|
| 380 |
+ |
|
| 381 |
+This file is pretty verbose, you want to look at it if you are getting the `We're sorry, but something went wrong.` error message when using Huginn. This is an example backtrace that can help you or other huginn developers locate the issue: |
|
| 382 |
+ |
|
| 383 |
+``` |
|
| 384 |
+NoMethodError (undefined method `name' for nil:NilClass): |
|
| 385 |
+ app/controllers/jobs_controller.rb:6:in `index' |
|
| 386 |
+ config/initializers/silence_worker_status_logger.rb:5:in `call_with_silence_worker_status' |
|
| 387 |
+``` |
|
| 388 |
+ |
|
| 389 |
+#### Runit/Background Worker logs `/home/huginn/huginn/log/*/current` |
|
| 390 |
+ |
|
| 391 |
+Those files will contain error messages or backtraces if one of your agent is not performing as they should. The easiest way to debug an Agent is to watch all your log files for changes and trigger the agent to run via the Huginn web interface. |
|
| 392 |
+ |
|
| 393 |
+The log file location depends your `Procfile` configuration, this command will give you a list of the available logs: |
|
| 394 |
+ |
|
| 395 |
+ ls -al /home/huginn/huginn/log/*/current |
|
| 396 |
+ |
|
| 397 |
+When you want to monitor the background processes you can easily watch all the files for changes: |
|
| 398 |
+ |
|
| 399 |
+ tail -f /home/huginn/huginn/log/*/current |
|
| 400 |
+ |
|
| 401 |
+### Still having problems? :crying_cat_face: |
|
| 402 |
+ |
|
| 403 |
+You probably found an error message or exception backtrace you could not resolve. Please create a new [issue](https://github.com/cantino/huginn/issues) and include as much information as you could gather about the problem your are experiencing. |