Knowledge-Base/40 - Guides/containers/docker-basics.md

title, description, tags, category, created, updated

title	description	tags	category	created	updated
Docker Basics	Practical introduction to Docker images, containers, and everyday command-line workflows	containers docker linux	containers	2026-03-14	2026-03-14

Docker Basics

Introduction

Docker packages applications and their dependencies into images that run as isolated containers. For homelab and developer workflows, it is commonly used to deploy repeatable services without building a full virtual machine for each workload.

Purpose

Docker is useful when you need:

• Repeatable application packaging
• Simple local development environments
• Fast service deployment on Linux hosts
• Clear separation between host OS and application runtime

Architecture Overview

Core Docker concepts:

• Image: immutable application package template
• Container: running instance of an image
• Registry: source for pulling and pushing images
• Volume: persistent storage outside the writable container layer
• Network: connectivity boundary for one or more containers

Typical flow:

Dockerfile -> Image -> Registry or local cache -> Container runtime

Step-by-Step Guide

1. Verify Docker is installed

docker version
docker info

2. Pull and run a container

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

3. Inspect the running container

docker ps
docker logs web
docker exec -it web sh

4. Stop and remove it

docker stop web
docker rm web

Configuration Example

Run a service with a persistent named volume:

docker volume create app-data
docker run -d \
  --name app \
  -p 3000:3000 \
  -v app-data:/var/lib/app \
  ghcr.io/example/app:latest

Inspect resource usage:

docker stats

Troubleshooting Tips

Container starts and exits immediately

• Check docker logs <container>
• Verify the image's default command is valid
• Confirm required environment variables or mounted files exist

Port publishing does not work

• Verify the service is listening inside the container
• Confirm the host port is not already in use
• Check host firewall rules

Data disappears after recreation

• Use a named volume or bind mount instead of the writable container layer
• Confirm the application writes data to the mounted path

Best Practices

• Pin images to a known tag and update intentionally
• Use named volumes for application state
• Prefer non-root containers when supported by the image
• Keep containers single-purpose and externalize configuration
• Use Compose for multi-service stacks instead of long docker run commands

References

• Docker: Docker overview
• Docker: Get started
• Docker: Volumes