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 location for logs in TurnKey (and Linux in general) is /var/log. Look for a file or directory with the name of the application you are looking for. Sometimes it may be a file right there, sometimes it will be in a sub directory. Generally most software that is installed from Debian will have it's logs there.

As a rule, any applications that don't log directly to /var/log, we try to provide convenience symlinks from /var/log to the real log files (to make them easier to find) but unfortunately that doesn't apply to all appliances (yet). So 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.

Please report (either via the forums and/or on our issue tracker) any non-standard log locations, or issues you have finding particular logs. Then we can be aware of the problem and aim to fix it in the next release.

Google your issue.

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

TurnKey is based on Debian (v14.x = Debian 8/Jessie; v15.x = Debian 9/Stretch) and remains binary compatible. So most Debian instructions, should be relevant to TurnKey. Generally there should be info online for many common issues that users might face, particularly with regard to software installed from the default Debian repos. 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 there are error messages being displayed somewhere, and/or you find errors in your logs, try googling the specific, verbatim error message. Remove any timestamps as they are unlikely to match. Explicit paths may also not match (I recommend including them initially, but remove if nothing useful comes up). If that still 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, remove paths, etc).

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, then please post on the forums. Note that if you're not already a user, you will need to register for an account. It's also worth noting that sometimes our spam filters can be a little aggressive (and yet some spammers still get through somehow?!). If you find yourself in that situation, please post on an existing thread, such as this one and or send us an email and we'll whitelist your user account.

When posting 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 quite the same and/or old threads) then I suggest adding a brief post (on the other thread(s)) 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 different 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, or even combine threads.

Be verbose!

Often people are scared to be too verbose, especially online. I would argue that you can never be too verbose when describing bugs or issues! Even though you may not feel something is completely relevant, please don't hesitate to include any info you have. It's much easier for someone to disregard info that it irrelevant, but much harder to read your mind! :)

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 tags can include spaces, and tags should be separated 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 from the commandline:

turnkey-version

It should produce a result like this (v15.1 LAMP appliance):

turnkey-lamp-15.1-stretch-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 newcomers and/or developers may not always 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 TurnKey Hub

or

OVA in VirtualBox v6.0.4 on Windows 10

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/easier 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! Please feel free to redact any content which you may think is sensitive or private, but please note what changes you have made to logs, error messages, etc.

Screenshots of issues can also be useful (especially web content visual errors within your web browser), however if you are sharing an error message it's much better to post the text of the error 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 - see above point re verbosity). 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, but it doesn't really matter. Closing bugs (that aren't really bugs) is easy! :)