Run UBOS with Docker


UBOS is available on the Docker hub. To run UBOS using Docker:

  1. Make sure you have a reasonably recent Docker installation on your machine.

  2. Boot UBOS with a command such as this:

    % docker run -i -t \
        --cap-add NET_ADMIN --cap-add NET_BROADCAST --cap-add SYS_ADMIN \
        -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
        -p 8080:80 \
        ubos/ubos-green \

    While that looks somewhat intimidating, all this command really says is: “Boot the image called ubos/ubos-green, keep the terminal around, give it the privileges it needs, and let me access it with a web browser through my local 8080 port.”

    As UBOS is a full operating system, not just an application running in a container, it needs privileges such as NET_ADMIN so it can manage its firewall, for example.

    Note: If you run it in a non-Linux environment, you may get various warnings, such as that UBOS cannot initialize its firewall, or that the filesystem does not understand extended file system attributes. Most of those should be fairly harmless.

    Note: Some very recent versions of systemd seem to conflict with Docker. That appears to be a problem for Docker in general that they need to solve. Should this be the case here, you will know because UBOS will fail with a fatal error.

  3. When the boot process is finished, log in as user root. For password, see I need root. Alternatively, execute docker exec -i -t <name> /bin/bash or such in a separate terminal to obtain a root shell in the container.

  4. Now: wait. UBOS needs to generate a few cryptographic keys before it is ready to use and initialize a few other things on the first boot. That might take a few minutes. To determine whether UBOS ready, execute:

    % systemctl is-system-running

    The Docker container takes entropy from the host computer, so make sure the host system provides enough. Depending your Linux distro, you may be able to generate more by typing on the keyboard, moving the mouse, generating hard drive activity etc. You can also run:

    % sudo systemctl start haveged

    on your host (not in your Docker container).

  5. Check that your Docker container has acquired an IP address:

    % ip addr

    Make sure you are connected to the internet before attempting to proceed.

  6. Update UBOS to the latest and greatest:

    % sudo ubos-admin update
  7. You are now ready for Setting up your first Site and App.

  8. To shut down your Docker container, execute

    % systemctl poweroff

About that run command

If you are interested in the details of the complicated run command, let’s unpack it:

docker run Run a Docker image.
-i -t Keep a terminal open on the command-line, so you can log into UBOS.
--cap-add NET_ADMIN ... Grant certain needed capabilities to the container running UBOS. These are required so UBOS can manage networking using systemd-networkd and its firewall using iptables.
--v /sys/fs/cgroup:/sys/fs/cgroup:ro Make the "cgroup" device hierarchy available to the container in read-only mode. This is needed so Docker can successfully boot an entire operating system like UBOS.
-e container=docker Tell UBOS that it is running under Docker.
ubos/ubos-green The UBOS version to download and to run. Here we run the most recent release of UBOS on the "green" Release Channel. To see what UBOS versions are available via Docker, go to the UBOS section on the [Docker hub](
/usr/lib/systemd/systemd Run systemd, which will start the UBOS operating system, instead of running some other kind of command.

P.S. If you understand Docker better than we do, and there is a way of making the above command-line shorter, please do let us know. Thank you!