Reporting problems and getting support

TurnKey Linux strives to be awesome. And we like to think that mostly it is. However problems do sometimes occur. Sometimes it's misunderstanding; sometimes it's confusing (or lack of) documentation or sometimes it's a bug. Perhaps it is a bug in our software or pre-configuration, or a bug in software packaged by Debian or perhaps even the original software developer (i.e. "upstream")!?

This page is to give you some pointers to make your troubleshooting quicker and easier and/or make it easier for someone trying to help you out.

Check the logs!

Often software logs errors in greater detail than it provides on screen. The default place for logs in TurnKey is /var/log. Sometimes there may be a file in that directory, sometimes it will be in a sub directory. Generally most software that is installed from Debian will have it's logs there.

Software installed from other sources may have it elsewhere. Other places to look are within the software installation directory. E.g. /var/www/<software-name>/log or /opt/<software-name>/log - depending on the appliance. Check the individual appliance page to see if it notes an install location.

Google your issue.

This one is pretty obvious, but it's always worth googling as a first step to troubleshooting.

As TurnKey is based on Debian (v13.x = Debian Wheezy; v14.x = Debian Jessie) generally there should be info online for many common issues that users might face. Ubuntu is also based on Debian so can sometimes be useful too, but be careful because Ubuntu is not binary compatible with Debian. Avoid adding Ubuntu repos on your TurnKey server!

If you found some errors in your logs, try googling the specific, verbatim error message. Remove any timestamps as they are unlikely to match. If that gets no helpful results, try making it more general (e.g. if it quotes line numbers in the error message, delete them from your search).

If you do find a solution to your issue somewhere other than TurnKey, please consider posting about it on our forums anyway. Chances are that if you had the issue and didn't know what to do, that others are or will be in the same position!

Start your own thread!

If you still can't resolve your issue and decide to post on the forums; as a general rule you should start a new thread. Unless there is a really recent thread that EXACTLY describes your issue, it's better to start your own thread. If there are other threads describing similar issues (but not the same and/or old threads) then I suggest a brief post with a link to your (new) thread. That will get the attention of previous posters to that thread without completely hijacking it.

The reason behind that suggestion is because bugs which appear similar can often have different causes. That is especially the case with older software (newer software versions often have the old bugs fixed - so a similar error will have a difference cause). Having your own thread makes life better for everyone, especially if the issue ends up being different. If the issue ends up being the same, we can always cross post links.

Give your thread a brief but descriptive subject.

This is probably not as important when posting on TurnKey compared to other forums, but it still helps.

Examples of unhelpful subject lines:

  • "HELP!!"
  • "My server is broken"
  • "Doesn't work"

    Examples of better subjects:

  • "WordPress won't update"
  • "Can't connect to HTTPS on Redmine"
  • "Error 504 when connecting to Drupal site"

    Give your thread relevant tags.

    Tagging threads are not necessary, but it makes it much more useful for other users. It also helps us aggregate user pain points and bugs.

    As much as possible, try to reuse existing tags rather than making new ones. When you start typing, our website should provide auto complete options which should help there. Remember to separate tags with commas.

    At the very least I suggest that you tag your post with the TurnKey version (e.g. "14.0" or "14.1" - see below) and the appliance name (e.g. "redmine" or "lamp"). If it's a particular piece of software that you are having issues with then tag that too (e.g. "Webmin" or "TKLBAM"). Tags can always be edited later so don't be scared!

    What version of TurnKey is it?

    Bugs almost always apply to a particular version (or versions) of software. So to give those who might want to help you out a head start, provide the version of TurnKey you have. If you are not 100% sure, there is a really easy way to check:

    turnkey-version
    It should produce a result like this (v14.1 LAMP appliance):
    turnkey-lamp-14.1-jessie-amd64

    Where is it running?

    TurnKey produces a range of builds. They are all built from the ISO originally so should generally share bugs across platforms. However, that is not always the case as each different build has some degree of customisation. Also different platforms have their quirks and idiosyncrasies which new comers may not be aware of. So to help reduce friction, stating where your appliance is running may also be useful. E.g.:

    t2.small server on the Hub (AWS)
    or
    OVA in VirtualBox v5.0 on Windows 8.1"
    etc...

    What are you trying to achieve?

    Generally it's helpful to understand what it was you were trying to do when the unexpected behaviour occurred. Sometimes it may illuminate an misunderstanding on your behalf (perhaps the problem is actually expected behaviour from the command you are using)? If you don't state it, your intended aim may not be obvious. Also as there is almost always multiple ways to "skin a cat", perhaps there may be a better way to achieve your desired ends?

    What have you tried so far?

    If you followed some instructions that you found online (e.g. a random blog post or a StackOverflow Q&A), post a link to it. That might help us understand why it didn't work. Perhaps it's not compatible with the current version? E.g. the instructions apply to an older version of Debian/TurnKey which no longer applies or is irrelevant to your situation.

    What was the result?
    I.e. what is the exact nature of the error/problem?

    This one doesn't need a lot of explanation. If there was a specific error message post it. If you found some issues in your logs, post the relevant parts. For big long logs, consider attaching them to your post, rather than copy/pasting them. That's actually another reason to start your own thread; only the first post can have attachments!

    Screenshots of issues can also be useful (especially in browser errors), however if you are sharing an error message it's much better to post the text as text. It makes it easier to google the error messages and also makes it much easier for google to find your thread in future (to help others out).

    What other things have you done recently?

    It is also good to note what other adjustments you have recently made within TurnKey (even if you think it's irrelevant). Sometimes things you've changed have unintended consequences. And sometimes a combination of seemingly unconnected adjustments can cause issues. Often not, but the more info you provide the easier it is to help you out!

    Time to post a bug?

    If you are sure that you are "doing it right" but getting the wrong result then it may be a legitimate bug. If you think so, please post on our issue tracker. Again provide info regarding your TurnKey version, what you did and what you were expecting, etc.

    If you aren't sure, it's probably best to post in the Support Forums first.