Install a container engine and run your first container

A container packages a program together with everything it needs, so it runs the same way on your laptop and on your server. This guide installs the container engine from the Ubuntu repositories, checks that the engine works, and runs your first container, a small web server you can open in a browser.

Before you begin

A VPS running Ubuntu 24.04 LTS with SSH access as a user with sudo rights, such as alex.
At least 1 GB of free RAM and 2 GB of free disk space. Containers need room for their images.
No other service already using port 8080 on the server.

Step 1: Install the engine

Ubuntu ships a container engine in its own repositories as the package docker.io. Refresh the package list, then install it. The -y flag skips the confirmation prompt.

sudo apt update
sudo apt install -y docker.io

Start the engine now and enable it to start at boot. The --now flag does both at once.

sudo systemctl enable --now docker

Confirm the engine is running and see which version you have:

sudo docker version --format '{{.Server.Version}}'

24.0.7

Step 2: Run the hello-world test

The official hello-world image is tiny. Running it proves that the engine can download an image, create a container, run it, and report the result. The --rm flag removes the container once it exits, so nothing is left behind.

sudo docker run --rm hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.

Step 3: Let your user run the container engine without sudo

the container engine's socket is owned by the docker group, so adding your user to that group lets you run container commands without typing sudo every time. Log out and back in afterwards so the new group membership takes effect.

sudo usermod -aG docker $USER
exit

After you reconnect over SSH, check that it works without sudo:

docker ps

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

The empty table is correct. It lists running containers, and you have none yet.

Step 4: Run a web server container

Next, run an nginx web server in the background. The -d flag means detached, so the container keeps running and your prompt comes back. -p 8080:80 maps port 8080 on the server to port 80 inside the container. --name web gives it a readable name.

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

Confirm it is running and test it from the server:

docker ps
curl -I http://127.0.0.1:8080/

HTTP/1.1 200 OK
Server: nginx/1.27.2

Step 5: Look inside and clean up

View the container's recent output with logs, which is useful when something misbehaves. Then stop and remove it with rm -f, which stops it first if it is still running.

docker logs web
docker rm -f web

To see the images stored on disk, and how much space they use, run:

docker images
docker system df

Careful: the container engine publishes ports by writing its own firewall rules, and those rules are processed before UFW's. A container published with -p 8080:80 can be reachable from the internet even when UFW says the port is closed. Publish only ports you mean to expose, bind to 127.0.0.1 when only the server itself needs access (for example -p 127.0.0.1:8080:80), and check your exposure with the guide on open ports and listening services.

Careful: Membership of the docker group is effectively the same as root access, because any the container engine user can start a container that mounts the host's files. Add only people you trust.

Troubleshooting

"permission denied while trying to connect to the container daemon socket". Your session does not yet have the docker group. Log out and back in, or use sudo docker until you reconnect.
"port is already allocated". Another container or program uses that port. Find it with docker ps or sudo ss -tlnp, then pick a different host port.
"Cannot connect to the the container engine daemon". The engine is not running. Check sudo systemctl status docker, and read the last few lines of the log with sudo journalctl -u docker -n 30.
The image download hangs or times out. Your server may have no outbound internet access, or DNS is failing. Test with ping -c 3 example.com and check your network settings.

Next steps

You now have a working engine and know the basic lifecycle: run, inspect, remove. Next, try writing a container build file that packages your own app, or run a service such as a database as a container with a named volume so its data survives restarts. Podman is another container engine available in Ubuntu's repositories, and it uses the same image format.