🐳 Installing Docker on Ubuntu Desktop

IT & Systems
, , , ,
1

:spouting_whale: Installing Docker on Ubuntu Desktop

Get Docker running on your daily driver for testing and development

:desktop_computer::wrench::package:

You’re running Ubuntu Desktop as your main system and want to experiment with Docker containers. Maybe you want to test something before deploying it to your server, or you just want to learn how containers work without risking your production environment.

Good news: getting Docker running on Ubuntu Desktop is straightforward. This guide walks you through the entire process, from prerequisites to running your first container.

:clipboard: Before You Start

What You Need

  • Ubuntu Desktop (20.04 LTS, 22.04 LTS, or 24.04 LTS recommended)

  • Fully patched system (run sudo apt update && sudo apt upgrade first)

  • Sudo access (you’ll need administrator privileges)

  • Basic command line comfort (copy/paste skills required)

Time Required

  • Installation: 10-15 minutes

  • Testing and examples: 15-30 minutes

:wrench: Step 1: Remove Old Versions (If Any)

First, we need to remove any old Docker installations that might conflict with the official version. Even if you’ve never installed Docker before, run this command anyway. It won’t hurt anything if there’s nothing to remove:


sudo apt remove docker docker-engine docker.io containerd runc

This removes older package names and versions that could cause problems.

:package: Step 2: Install Prerequisites

Docker needs a few packages to work properly. Install them:


sudo apt update

sudo apt install ca-certificates curl gnupg lsb-release

What these do:

  • ca-certificates: SSL/TLS certificates for secure downloads

  • curl: Downloads files from the internet

  • gnupg: Verifies package signatures

  • lsb-release: Identifies your Ubuntu version

:key: Step 3: Add Docker’s Official GPG Key

This verifies that the Docker packages you download are actually from Docker and haven’t been tampered with:


sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

:memo: Step 4: Add Docker Repository

Now add Docker’s official repository to your system:


echo \

"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \

$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

This tells Ubuntu where to download Docker packages from.

:spouting_whale: Step 5: Install Docker Engine

Update your package list and install Docker:


sudo apt update

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

What gets installed:

  • docker-ce: Docker Engine (the core)

  • docker-ce-cli: Command line interface

  • containerd.io: Container runtime

  • docker-buildx-plugin: Extended build capabilities

  • docker-compose-plugin: Multi-container applications

This will take a few minutes to download and install.

:white_check_mark: Step 6: Verify Installation

Check that Docker installed correctly:


sudo docker run hello-world

You should see a message that starts with:


Hello from Docker!

This message shows that your installation appears to be working correctly.

If you see this, Docker is working. The command downloaded a test image, ran it in a container, and displayed the message.

:bust_in_silhouette: Step 7: Run Docker Without Sudo (Optional but Recommended)

By default, you need sudo to run Docker commands. This gets annoying fast. To fix this, add yourself to the docker group:


sudo usermod -aG docker $USER

Important: You need to log out and log back in (or reboot) for this to take effect.

After logging back in, test it:


docker run hello-world

No sudo needed this time. Much better.

Security note: Users in the docker group have root-equivalent permissions. Only add users you trust.

:rocket: Step 8: Enable Docker at Boot

Make Docker start automatically when you boot your system:


sudo systemctl enable docker.service

sudo systemctl enable containerd.service

Now Docker will always be ready when you need it.

:bullseye: Basic Docker Commands

Here are the essential commands you’ll use:

Check Docker Status


docker --version

docker info

List Running Containers


docker ps

List All Containers (Including Stopped)


docker ps -a

List Downloaded Images


docker images

Stop a Container


docker stop <container_id_or_name>

Remove a Container


docker rm <container_id_or_name>

Remove an Image


docker rmi <image_id_or_name>

:light_bulb: Practical Examples

Example 1: Run a Web Server

Run an Nginx web server:


docker run -d -p 8080:80 --name my-nginx nginx

What this does:

  • -d: Runs in background (detached)

  • -p 8080:80: Maps port 8080 on your computer to port 80 in the container

  • --name my-nginx: Names the container “my-nginx”

  • nginx: Uses the official Nginx image

Open http://localhost:8080 in your browser. You should see the Nginx welcome page.

Stop it when done:


docker stop my-nginx

docker rm my-nginx

Example 2: Run a Database

Run a PostgreSQL database with a password:


# Generate a secure password

PG_PASSWORD=$(openssl rand -base64 32)

echo "Your PostgreSQL password: $PG_PASSWORD"

# Run PostgreSQL

docker run -d \

--name my-postgres \

-e POSTGRES_PASSWORD=$PG_PASSWORD \

-p 5432:5432 \

postgres

What this does:

  • Generates a random 32-character password

  • Creates a PostgreSQL container

  • Sets the password via environment variable

  • Exposes PostgreSQL on port 5432

Save that password! You’ll need it to connect.

Stop it when done:


docker stop my-postgres

docker rm my-postgres

Example 3: Run a Container Interactively

Sometimes you want to run a container and interact with it directly:


docker run -it ubuntu bash

What this does:

  • -it: Interactive terminal

  • ubuntu: Uses Ubuntu image

  • bash: Runs bash shell

You’re now inside a fresh Ubuntu container. Try some commands:


ls

pwd

cat /etc/os-release

Type exit to leave and stop the container.

Example 4: Run Docker Compose

Create a file called docker-compose.yml:


version: '3.8'

services:

web:

image: nginx

ports:

- "8080:80"

db:

image: postgres

environment:

POSTGRES_PASSWORD: changeme

Run it:


docker compose up -d

This starts both Nginx and PostgreSQL together. Check they’re running:


docker compose ps

Stop everything:


docker compose down

:locked: Generating Secure Passwords

When containers need passwords, generate them properly. Don’t use “password123” or anything you can remember. Use one of these methods:

Method 1: OpenSSL (Recommended)


openssl rand -base64 32

Method 2: /dev/urandom


tr -dc 'A-Za-z0-9!@#$%^&*' < /dev/urandom | head -c 32; echo

Method 3: Using a Variable


MY_PASSWORD=$(openssl rand -base64 32)

echo "Generated password: $MY_PASSWORD"

Save these passwords somewhere safe like a password manager. Don’t lose them.

:hammer_and_wrench: Troubleshooting

Docker Daemon Not Running


sudo systemctl start docker

sudo systemctl status docker

Permission Denied Error

Did you log out and back in after adding yourself to the docker group? Do that.

Port Already in Use

If you get “port is already allocated,” something else is using that port. Either stop that service or use a different port:


docker run -d -p 8081:80 nginx # Use 8081 instead

Container Won’t Start

Check the logs:


docker logs <container_name>

Out of Disk Space

Docker images and containers take up space. Clean up:


# Remove stopped containers

docker container prune

# Remove unused images

docker image prune

# Remove everything unused (be careful!)

docker system prune -a

:books: Learning Resources

Now that you have Docker installed, here’s where to learn more:

:bullseye: What’s Next?

You’ve got Docker running on your Ubuntu Desktop. Here are some ideas for what to do with it:

  1. Test before deploying - Run containers locally before moving them to production

  2. Development environments - Consistent dev environments across your team

  3. Learn new software - Try databases, web servers, or tools without installing them permanently

  4. Build your own images - Create custom containers for your projects

  5. Practice for your homelab - Get comfortable with Docker before deploying it on a server

:brain: TL;DR

  • Remove old versions first to avoid conflicts

  • Install prerequisites (ca-certificates, curl, gnupg, lsb-release)

  • Add Docker’s GPG key for package verification

  • Add Docker repository to your system

  • Install Docker Engine and related packages

  • Add yourself to docker group to avoid using sudo

  • Enable Docker at boot so it starts automatically

  • Generate secure passwords with openssl when needed

:speech_balloon: Your Turn

Got Docker installed? Running into issues? Want to share what you’re using it for?

Drop a comment below. Let’s figure it out together.