TurnKey server domain configuration

Why am here? Where is my server homepage?

The most likely reason you have found yourself here is because you launched a TurnKey server which requires a domain (FQDN - fully qualified domain name) and you have accepted the default rather than set your own. TurnKey appliances that require a domain to be set will ask during firstboot configuration. 'example.turnkeylinux.org' is the default domain set at build time - which redirects to this page.

If you did set a custom domain; another possibility is that you have discovered a bug and the firstboot configuration failed to properly (re)set the domain. If you think that is the case, please open a bug on our Issue Tracker (requires free GitHub user account) &/or open a new thread on our Support Forums (requires free TurnKey Linux user website user account).

Paying TurnKey Linux customers may also contact TurnKey support directly for a priority response. Support requests related to TurnKey bugs will not be counted towards support incidents bundled with your subscription.

Once we become aware of a "showstopper" bug we will aim to develop and document a workaround ASAP. The fix will also be applied to the next release of the relevant TurnKey appliance.

How can I fix access to my server?

These things are required to access your server and avoid being redirected to this page:

  1. Configure a domain to point to your server.
  2. Reconfigure your server to use the new domain.
  3. Clear your web browser cache and cookies to remove cached redirects.

Configure Domain

If your server is publicly available via the internet then the best path is to buy a custom domain or add a new subdomain to a domain that you already control. Ensure that an "A"/"AAAA" record/s exist which point to your server's IP address. If you have a TurnKey Hub account you also have the option of a free "tklapp.com" subdomain. The Hub also supports custom domains via AWS Route53.

After you have configured your domain, please confirm that it is directing to your server as required. There are a variety of ways to do that, but 'ping' and 'dig' are useful CLI tools to check that your domain maps to the IP address of your server. Google also has an online DIG tool. Another test you could run is accessing Webmin on your server - i.e. https://YOUR_DOMAIN.COM:12321

Reconfigure your TurnKey Server domain

Once you have your domain set up, then you will need to reconfigure the web app on your TurnKey server. A full configuration of a TurnKey appliance can be done using the 'turnkey-init' command.

Alternatively, Just the web app itself can be reconfigured via it's specific initialization script. The script can be found in '/usr/lib/inithooks/bin' and will be 'name-of-the-appliance.py' - e.g. to reinitialize WordPress on the TurnKey Linux WordPress appliance:

/usr/lib/inithooks/bin/wordpress.py

The script will also ask you to (re)set other initialization info such as email and password. You can reuse the same ones you used initially - the only thing that needs to be changed is the domain. Restarting the web server is not strictly required, but is recommended. E.g. Apache2:

systemctl restart apache2

Clear browser cache and cookies

By default web browsers cache domain redirects. Exactly how you clear your browser cache and cookies will depend on the browser you are using. Note that usually you will not need to clear all cache and cookies as most browsers support cleaning cache and cookies for specific domain/s.

Why do I need a domain?

The specific reason why a domain is required for your TurnKey appliance is due to software design decisions made by the web app developers. There are a couple of likely reasons:

  • To provide absolute URLs to specific content/resources - e.g., static assets such as images, CSS styling, etc or when storing and/or rewriting content URLs within a database.
  • To provide an additional layer of security - i.e. ensure that your server can only be contacted to via the specific FQDN/s that you have defined.

It can also be handy to have an FQDN set if/when you wish to generate a CA signed SSL/TLS certificate - e.g. via Let's Encrypt.