Docker

IMPORTANT NOTE
Unfortunately in recent times our Docker builds have not been maintained and this documentation does not work as intended. Please see Marcos' post below for a round up of the current issues - with possible solutions. An issue has been lodged on our issue tracker and hopefully we'll be able to resolve the situation as soon as possible. If you have more to add or are in a position to help, input is always welcome.


This page describes how to use the Docker builds of TurnKey Linux appliances. Use of TurnKey Docker builds requires you have a host system with Docker installed. If you wish to install Docker on an existing TurnKey appliance, please consult the instructions for Debian (TurnKey v15.x = Debian 9/Stretch).

Please note that these are "full OS" style containers, rather than "application" style containers as many Docker users might normally expect. As such, these containers provide a full TurnKey (Debian based) OS and include all the software components of the other alternate TurnKey appliance download options (e.g. ISO, etc). They are provide an environment more like an LXC container user might expect, but optimised to run on Docker.

This page is an updated and improved version of the original Docker builds announcement.

Docker builds

These are TurnKey builds optimized to run as docker containers, supporting automatic download via the docker public index.

All TurnKey appliances are available on the Docker Hub (generously provided by Docker, Inc), which streamlines deployment. For example:

docker pull turnkeylinux/core
docker run -i -t -d turnkeylinux/core

Docker containers can be run in the foreground or the background, so we've tried our best to support all use cases with regards to initialization (aka. inithooks) - secret regeneration, setting of passwords, application configuration, etc.

Depending on your use case, we recommend two options:

Option 1: Initialization via ssh (interactive)

On first login, you will be prompted to initialize the appliance.

CID=$(docker run -i -t -d turnkeylinux/core)
CIP=$(docker inspect --format='{{.NetworkSettings.IPAddress}}' $CID)
docker logs $CID | grep "Random initial root password"
ssh root@$CIP

Option 2: Create new image with preseeded values (non-interactive)

The appliance will initialize itself with the provided configuration. Once initialized, the configuration will be deleted. For more information see inithooks.

To use WordPress as an example:

mkdir /root/wordpress

cat > /root/wordpress/inithooks.conf <<EOF
export ROOT_PASS=secretrootpass
export DB_PASS=secretmysqlpass
export APP_PASS=secretadminwppass
export APP_EMAIL=admin@example.com
export APP_DOMAIN=www.example.com
export HUB_APIKEY=SKIP
export SEC_UPDATES=FORCE
EOF

cat > /root/wordpress/Dockerfile <<EOF
FROM turnkeylinux/wordpress
ADD inithooks.conf /etc/inithooks.conf
EOF

docker build -t wordpress /root/wordpress
docker run -i -t -d wordpress

Notes

Docker tags and pulling/running different TurnKey versions

Prior to TurnKey v15.0, each individual TurnKey appliance Docker build release included the TurnKey version in the name. E.g. v14.2 TurnKey Core was on the Docker Hub as "turnkeylinux/core-14.2". So if you wish to use older TurnKey appliances (<15.0) then you will need to include the specific version number as part of the name. E.g. to pull and run TurnKey Core v14.2:

docker pull turnkeylinux/core-14.2
docker run -i -t -d turnkeylinux/core-14.2

However as of v15.0+, we are using Docker tags as a much better way of providing different versions of our appliances. Tags can be (optionally) specified when using the docker commandline tool by appending a colon (:) and the tag name. The "latest" tag always points to the latest update, and if a tag is not specified, then "latest" is assumed. So to pull and run the latest release of TurnKey core, you can use either of these examples:

docker pull turnkeylinux/core
docker run -i -t -d turnkeylinux/core

Or if you wish to be verbose:

docker pull turnkeylinux/core:latest
docker run -i -t -d turnkeylinux/core:latest

If you wish to download a specific release (>=15.0) then you can specify the desired version as a tag. So to use the Drupal 8 appliance as an example, if you wished to pull and run the v15.4 version, you could do that like this:

docker pull turnkeylinux/drupal8:15.4
docker run -i -t -d turnkeylinux/drupal8:15.4

Pre-configured run command

Docker is designed for "application or process" containers - for example, running mysql, and only mysql. Docker short-circuits /sbin/init so you can't really "boot" a container like in vanilla LXC.

To work around this, we've included /usr/sbin/start.sh (default run command) which will start all services and drop to a shell. When the shell is exited, the services will be stopped. For this reason, SSH is recommended for regular console usage.

STDIN and TTY options required

The -i and -t options are required to attach STDIN and allocate a TTY to the container. There have been moves by Docker to allow this to be pre-configured but we haven't yet looked deeper into that and are not up to date on hte current state of play.

Pre-configured to expose ports

All TurnKey Docker appliances are configured to expose their custom services. This means that the host can access the services, but they are not exposed to the network.

Exposing ports to the network needs to be done at runtime (docs), for example:

# bind port 80 on the host to the container's port 80
docker run -i -t -d -p 80:80 turnkeylinux/lamp

Or to use an alternate host port:

# bind port 8080 on the host to the container's port 80
docker run -i -t -d -p 0.0.0.0:8080:80 turnkeylinux/lamp

Skipping security updates on first boot

To speed up testing during development, support for overriding the default SEC_UPDATES value was added to start.sh. It was planned to remove this support or leave it undocumented, but we decided others might find it useful when testing (and only in testing!).

# THIS IS NOT RECOMMENDED, USE AT YOUR OWN RISK!
docker run -i -t -d -e SEC_UPDATES=SKIP turnkeylinux/openldap

Comments

Jeremy Davis's picture

FWIW, it's probably best to post in the forums, rather than comment on docs. There is no easy way for me to see unanswered doc comments, so if I miss the initial notification in my inbox, the post will go answered (as happened to you here).

I'm not really sure why docker compose doesn't work as expected. Personally I'm not very familiar with Docker at all, let alone with docker compose. So I'm probably not much immediate help.

My guess is that you are correct. But how that might be addressed, I'm not really sure, sorry.

My hope is that it will be resolved when we finally move to our new appliance model (based on containers rather than a monolithic server). Then we will be building proper containers (rather than the hacky way we currently build them).

Having said that, that won't be happening anytime soon. So in the meantime, I've lodged it as a bug and will try to address it once we have our next release of appliance ISOs published (i.e. before we release the v15.0 Docker builds).

Jeremy Davis's picture

And extra brownie points for the fix/workaround! :)

FWIW, I've open an issue on our tracker, so this doesn't get forgotten for our upcoming release.

Jeremy Davis's picture

One of our developers has had a look at this and couldn't reproduce your issue. See his comment on the issue.

If you can provide further info on how to recreate the issue that you experienced, we're more than happy to reopen it and investigate further.

Regardless, thanks for posting.

Jeremy Davis's picture

Right you are. You can install like this:

apt update
apt install -y cifs-utils
Marcos's picture

Request for Documentation Update or Removal

Docker Image for TurnkeyLinux Not Functional

Dear TurnkeyLinux Documentation Team,

I am reaching out to request a review and possible removal or update of the Docker documentation for TurnkeyLinux. After multiple attempts to run and use the container as described in the documentation, it became evident that the instructions do not result in a functional environment. Below, I have provided a detailed analysis of the key issues encountered while trying to use the Docker container.

🕵️ Key Issues Identified

1️⃣ Systemd Not Available in Docker (Critical Issue)

Error:

System has not been booted with systemd as init system (PID 1). Can't operate.

Cause: TurnkeyLinux relies on systemd for service management, but Docker does not support systemd by default.

Impact: Essential services like Apache, MariaDB, and SSH cannot be properly managed. This prevents users from controlling or restarting services, rendering the container unusable.

Suggested Solution: Update the Dockerfile to remove systemd dependencies or use a Docker-compatible alternative such as service commands or start-stop-daemon.

2️⃣ Script Failure: /etc/rc2.d/S01turnkey-init-fence

Error:

run-parts: /etc/rc2.d/S01turnkey-init-fence exited with return code 1

Cause: The script appears to attempt to run system-level commands that are incompatible with Docker, likely referencing systemd or init commands.

Impact: The container's initialization process is halted, preventing the container from being usable.

Suggested Solution: Update the script to use service commands or modify the entrypoint to bypass this script entirely.

3️⃣ Terminal Error: dialog.PythonDialogBug

Error:

dialog.PythonDialogBug: Bug in pythondialog: expected an empty output from 'msgbox', but got: 'Error opening terminal: unknown.'

Cause: The confconsole script tries to use the dialog package, which requires a TTY terminal. Since Docker doesn't provide an interactive TTY unless -it is used, the script fails.

Impact: The initialization process fails, and the container becomes non-functional.

Suggested Solution: Update the container to use non-interactive methods for setup, or recommend that users run the container with -it to provide a TTY interface.

4️⃣ SSH Key Generation Fails

Error:

ssh-keygen: /etc/ssh/ssh_host_dsa_key.pub: No such file or directory

Cause: The SSH daemon attempts to generate keys, but the required directory or permissions are not available in the Docker container.

Impact: Without SSH keys, the container cannot start the SSH service, which makes remote access impossible.

Suggested Solution: Run ssh-keygen -A in the Dockerfile to ensure all necessary SSH keys are pre-generated before container launch.

5️⃣ No Foreground Process (Container Exits Automatically)

Error:

WARNING: Exiting this shell will stop the container.

Cause: The container runs background services, but since no foreground process (like an infinite loop) is running, Docker stops the container automatically.

Impact: The container exits as soon as it finishes starting its background services.

Suggested Solution: Use tail -f /dev/null as the primary process to keep the container alive, or set --restart unless-stopped in the Docker run command.

📋 Summary of Key Issues

Issue Cause Impact Possible Solution
Systemd not working No systemd in Docker Critical services not running Remove systemd or use service commands
Script /etc/rc2.d/S01turnkey-init-fence fails Script failure Container fails to initialize Use service commands instead
dialog.PythonDialogBug Missing TTY terminal Container initialization stops Run container with -it or update confconsole
SSH key generation fails Missing keys SSH service does not start Generate keys using ssh-keygen -A
No foreground process All services run in background Container exits immediately Use tail -f /dev/null as main process

🛠️ Suggested Actions

  • Option 1: Remove the Docker documentation entirely as the container does not work without significant rework.
  • Option 2: Update the documentation to highlight these issues and suggest solutions.

💡 Conclusion

The current Docker image for TurnkeyLinux has several critical issues, including the reliance on systemd, script failures, TTY issues, and missing foreground processes. As a result, it is nearly impossible for users to use the image as intended. To avoid confusion, it is recommended to either update the documentation to reflect these issues or remove the Docker documentation entirely.

If you'd like more details, I can provide additional logs or information to help resolve these issues.

Best regards, Navigator

Jeremy Davis's picture

Thanks for taking the time to write all this out Marcos. TBH I haven't done your efforts full justice as I'm not going to respond with any real depth.

I also deeply apologize that you've obviously wasted your valuable time mucking around with our Docker builds without a good result. :(

As you note, this documentation is outdated and our Docker builds are not in a good state. We've neglected Docker as a platform for some time now and we really need to address that.

Despite your solid argument to either update or delete this doc page, I'm not in a position to fix and update it and I don't really want to delete it. But I agree that something needs to be done to ensure others avoid repeating your experience. So until we're in a position to actually do something meaningful about it, my immediate plan is to just add a "warning" paragraph at the top of this doc - linking to your post. I'll also open an issue so addressing the points you raise in a more appropriate way doesn't completely fall off the radar.

I hope you think that is sufficient. Regardless, if you have ideas and/or further feedback, please continue to share it. I love your input and are so happy to have you as part of the TurnKey community. :)

Marcos's picture

Jed now a days i always ask help to AI to prettyfy my discoveries. Writing beautiful and verbose information takes time, some sumarization always is helpfull. I Tought that this aproch would benefit SEO from the post because i can't delete my own comments LOL. Thats all budy i hope that helps. Big hug from brazil