---
title: Docker Basics
description: Practical introduction to Docker images, containers, and everyday command-line workflows
tags:
  - containers
  - docker
  - linux
category: containers
created: 2026-03-14
updated: 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:

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

## Step-by-Step Guide

### 1. Verify Docker is installed

```bash
docker version
docker info
```

### 2. Pull and run a container

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

### 3. Inspect the running container

```bash
docker ps
docker logs web
docker exec -it web sh
```

### 4. Stop and remove it

```bash
docker stop web
docker rm web
```

## Configuration Example

Run a service with a persistent named volume:

```bash
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:

```bash
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](https://docs.docker.com/get-started/docker-overview/)
- [Docker: Get started](https://docs.docker.com/get-started/)
- [Docker: Volumes](https://docs.docker.com/engine/storage/volumes/)