Community-driven coverage of elementary OS — news, guides & forums
Dark abstract low-poly geometric landscape with layered triangular facets in deep navy, charcoal, and muted teal, illuminated by a soft electric-blue glow near the horizon

News roundups, tutorials, application guides, and forums — built by users, for users of the elegant Linux distribution.

elementary weekly
#20
Latest roundup · 18 Apr 2015
Freya Release
Final
Covered in weekly #19 & #20
Forum Topics
Active
Installation, customization & more

How to Install and Use Docker on elementary OS

Docker gives elementary OS users a practical way to run applications in isolated containers without installing every dependency directly on the desktop. A container can package a web server, database, development tool, or self-hosted service with the libraries it needs, while keeping the host system comparatively tidy. This makes Docker useful for software testing, local development, and learning Linux administration. Learn more about Tips And Tricks.

The steps below use Docker Engine, the open-source command-line runtime, rather than Docker Desktop. That distinction matters on elementary OS: the engine is lighter, integrates well with the terminal, and is usually the better fit for a Linux desktop. The commands suit current elementary OS releases based on supported Ubuntu versions, although checking the installed base release before adding a repository is essential.

Check Your Elementary OS Base

Before installing anything, update the package index and identify the Ubuntu release underneath elementary OS. Docker publishes packages for Ubuntu codenames such as jammy and noble, while elementary OS has its own version name. The command below shows the relevant details:

sudo apt update
cat /etc/os-release

Look for VERSION_CODENAME or UBUNTU_CODENAME. On an elementary OS release based on Ubuntu 22.04, the value will generally be jammy; a release based on Ubuntu 24.04 will generally use noble. Do not guess this value, because adding a repository for the wrong Ubuntu series can create dependency conflicts.

Remove older or unofficial Docker packages if they are present. They can use different package names and may conflict with Docker’s current components:

sudo apt remove docker.io docker-doc docker-compose podman-docker containerd runc

This command does not remove images or containers stored under Docker’s usual data directory, although a package that was installed from another source may have different behaviour. If the command reports that a package is not installed, that is normal.

Install the tools required to add a signed third-party repository:

sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

Docker’s repository key should be stored in a dedicated keyring rather than added to the older global trusted-key store. This follows current Debian and Ubuntu packaging practice and makes it easier to see which repository has permission to install packages.

Add Docker Engine Safely

Download Docker’s signing key and convert it into the format used by APT:

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Next, create a repository entry using the Ubuntu codename detected earlier. The following shell command reads the codename automatically from /etc/os-release and falls back to VERSION_CODENAME when required:

. /etc/os-release
CODENAME="${UBUNTU_CODENAME:-$VERSION_CODENAME}"

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu ${CODENAME} stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

If CODENAME is empty, stop and inspect /etc/os-release manually rather than substituting the elementary OS release name. The repository must match the Ubuntu base. Users on an older elementary OS version may need to upgrade the operating system first if Docker no longer publishes packages for its underlying Ubuntu release.

Refresh APT and install the engine, command-line client, container runtime, Buildx plugin, and Compose plugin:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

The package names are deliberately explicit. docker-ce provides the daemon, docker-ce-cli provides the docker command, containerd.io handles lower-level container execution, and the plugins add modern image-building and multi-container workflows. When installation finishes, confirm that the service is running:

sudo systemctl status docker --no-pager
sudo docker run hello-world

The hello-world image is downloaded from Docker Hub, started briefly, prints a verification message, and exits. An NBN connection in Brisbane, Perth, or regional New South Wales should be sufficient, although a slow connection may make the first image download take several minutes. Docker images are cached locally after download, so later runs are faster.

Configure Access And Verify Containers

By default, Docker’s Unix socket is owned by root. Using sudo docker works immediately, but entering sudo for every command is inconvenient. Add your normal user to the docker group if you want to manage containers without elevated commands:

sudo usermod -aG docker "$USER"

Sign out and sign back in, or restart the session, then verify the group membership:

groups
docker run --rm hello-world

Membership of the docker group effectively grants root-level control over the host. A container with access to the Docker socket can often gain extensive access to the filesystem and system resources. For a personal desktop this trade-off is common, but do not treat the group as a harmless convenience on a shared computer.

A few commands provide a useful first look at the installation:

docker version
docker info
docker ps
docker images

docker ps lists running containers, while docker ps -a includes stopped containers. docker images shows locally stored images. The --rm option in the earlier test automatically removes the temporary container after it exits, which helps prevent small experiments from filling the disk.

Docker normally starts with the system. Check and enable the service if necessary:

sudo systemctl enable --now docker

If a command fails with a permission error, first check that you logged out after changing group membership. If the daemon is inactive, inspect recent service messages with journalctl -u docker. Firewall tools such as ufw may also affect published ports, though Docker’s networking rules can behave differently from ordinary desktop applications.

Task Recommended Command What It Does
Test the engine docker run --rm hello-world Downloads and runs a small verification image
List running containers docker ps Shows active containers and published ports
List all containers docker ps -a Includes stopped and exited containers
View local images docker image ls Displays downloaded image layers
Read container output docker logs NAME Shows standard output and error messages
Stop a service docker stop NAME Gracefully stops a running container
Remove a container docker rm NAME Deletes a stopped container
Inspect Compose projects docker compose ps Lists services managed by Compose

Run A Useful Application

A container becomes useful when it runs a service you can access from the elementary OS desktop. For a simple example, start the lightweight Nginx web server and map port 8080 on the host to port 80 inside the container:

docker run -d \
  --name local-web \
  --restart unless-stopped \
  -p 127.0.0.1:8080:80 \
  nginx:alpine

Open http://localhost:8080 in a browser. The -d option runs the container in the background, --name gives it a memorable identifier, and --restart unless-stopped brings it back after a reboot. Binding to 127.0.0.1 keeps the service local to the elementary OS computer. If you use -p 8080:80 instead, the service may become reachable from other devices on the local network, depending on firewall rules.

The nginx:alpine tag uses a small Alpine Linux-based image. Avoid relying on the floating latest tag for important work; use a documented version such as nginx:1.27-alpine when repeatability matters. Stop and remove the demonstration service with:

docker stop local-web
docker rm local-web

For multi-service applications, Docker Compose uses a YAML file to define containers, networks, volumes, and environment variables. Create a directory and a small Compose file:

mkdir -p ~/docker/demo
cd ~/docker/demo
nano compose.yaml

Add this content:

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"
    restart: unless-stopped

Save the file, then start the service:

docker compose up -d
docker compose ps

Compose commands operate on the project directory, so keep each application in its own folder. docker compose logs -f follows live output, docker compose stop stops the services without deleting them, and docker compose down removes the containers and network created for the project. Persistent data should use named volumes or carefully chosen bind mounts rather than remaining inside a disposable container layer.

Manage Data, Ports And Updates

Containers are replaceable by design. If you store a database or application uploads only inside a container, removing that container can remove access to the data. A named volume is safer for many local services:

docker volume create app-data
docker volume ls

A volume can be attached with an option such as -v app-data:/var/lib/app. For source code and configuration, a bind mount such as -v "$PWD":/workspace connects a host directory to the container. Check permissions before mounting home-directory data, and avoid mounting the entire home folder or sensitive paths such as .ssh.

Published ports need the same care as any other network service. Port 8080 is convenient because it usually does not require privileged access, but a service exposed on 0.0.0.0 may be visible to other devices. On a home connection in Sydney or Melbourne, that could include other devices on the household Wi-Fi. Keep development tools bound to 127.0.0.1 unless remote access is an intentional requirement.

To update an image, pull the new version, recreate the container, and confirm the application still works:

docker pull nginx:alpine
docker compose pull
docker compose up -d

For a Compose project, docker compose up -d recreates services when their image or configuration changes. Do not blindly delete volumes during maintenance. A database backup should be tested before an upgrade, and passwords should be stored through environment files with restricted permissions or a proper secrets system rather than committed to a public repository.

Docker Hub availability and download limits can affect automated builds. Repeated pulls from Australian offices, university networks, or shared cloud addresses may encounter registry rate limits. Pinning versions, keeping a local cache, and authenticating to the registry can make builds more predictable. If a container handles Australian customer information, consider the Privacy Act 1988 and the Australian Privacy Principles when choosing logs, backups, and an external registry or hosting provider; container isolation does not remove privacy obligations.

Troubleshoot And Keep The Host Healthy

A failed container usually leaves useful evidence. Start with its status and logs:

docker ps -a
docker logs local-web
docker inspect local-web

If the port is already occupied, find the conflicting process with ss -tulpn | grep 8080, then choose another host port. If an image starts and immediately exits, read its logs and check the image documentation for required environment variables. A container that works from the terminal but not from a browser may be bound to the wrong address or listening on a different internal port.

Disk usage can grow quietly because images, stopped containers, build cache, and volumes accumulate:

docker system df
docker image prune
docker container prune

Prune commands remove unused objects, so review the confirmation prompt carefully. docker system prune is broader and can delete resources you planned to reuse. Keep active application data in named volumes or host backups, and monitor free space through System Settings or the command line.

Use trusted images, read their documentation, and avoid running unknown images with --privileged, host networking, or broad filesystem mounts. A container is a process-isolation tool, not a complete security boundary. Keep elementary OS patched with the normal software updates, update Docker packages from the configured repository, and review exposed ports with docker ps.

For a clean first milestone, run docker run --rm hello-world, then create ~/docker/demo/compose.yaml with the Nginx example and start it using docker compose up -d.

Browse the News Archive
Latest Updates

From the elementary weekly series

Low-poly faceted abstract render in dark charcoal and electric blue tones, suggesting a news bulletin or announcement
elementary news

elementary weekly #20

The first week with the final Freya release — community reactions, tips, and early impressions gathered in one roundup.

Abstract low-poly geometric scene in midnight blue and soft cyan, conveying a live broadcast or event atmosphere
elementary news

elementary SPECIAL

A live Hangouts event with the elementary OS founders, held on 11 April 2015, discussing the Freya final release.

Low-poly faceted render in deep navy and muted teal with subtle amber highlights, suggesting a tutorial or guide
Tips and Tricks

Timeshift Guide

How to use Timeshift — the intuitive system restore utility for elementary OS — to recover from configuration mishaps.

Explore

Topics & Resources

Dive into guides, application recommendations, and community discussions covering every aspect of elementary OS.