You are here
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
Oops sorry I missed your post.
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).
Thanks very much for your bug report! :)
FWIW, I've open an issue on our tracker, so this doesn't get forgotten for our upcoming release.
Hi Bernard
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.
You can install it pretty easy...
Right you are. You can install like this:
Request for Documentation Update or Removal
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:
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 orstart-stop-daemon
.2️⃣ Script Failure: /etc/rc2.d/S01turnkey-init-fence
Error:
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:
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:
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:
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-it
or update confconsolessh-keygen -A
tail -f /dev/null
as main process🛠️ Suggested Actions
💡 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
Thanks for taking the time to write all this out Marcos
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. :)
Jed now a days i always ask