# Installing Docker — What It Is, How It Works, and Why We Use It

Before installing Docker, it’s important to understand **what Docker actually does**, **how it fits into our media management setup**, and **why we run only the ARR stack inside Docker** while keeping **qBittorrent and Plex on the host system**.

This page will walk you through all of that in simple, practical terms.

---

# 🐳 What Is Docker?

Docker is a **containerization platform**.

That means:

### Docker lets you run applications in small, isolated environments called **containers**.

A container:

- has its own filesystem  
- has its own dependencies  
- has its own libraries  
- cannot interfere with your main system  
- can be destroyed and recreated easily  

Think of it like:

> **A lightweight, specialized mini-computer for one application.**

This makes apps more predictable, easier to upgrade, and easier to manage.

---

# 🔧 Why Use Docker?

### ✔ Avoid dependency conflicts  
Containers ship the libraries the app needs, so you don’t pollute your main OS.

### ✔ Easy to update  
Updating Radarr/Sonarr/Prowlarr becomes:

```
docker compose pull
docker compose up -d
```

### ✔ Easy to back up  
ARR services store their config in a small folder you can snapshot.

### ✔ Perfect for things that change often  
Indexers break, Prowlarr updates, Radarr adds features — Docker makes it painless.

---

# 🚫 Why Not Put Everything in Docker?

You *can* put everything in Docker, but in a real-world Raspberry Pi / home-server environment, some apps **behave badly** or **have limitations** inside containers.

Below is the reasoning for each major component.

---

# ❌ Why qBittorrent Is NOT in Docker

### qBittorrent needs:
- fine-grained permission control
- direct disk access  
- stable file paths  
- high-speed I/O for torrent hashing  
- ability to handle sudden restarts and disk states  

Inside Docker, qBit often has problems:

| Problem | Why It Happens |
|--------|----------------|
| Slow hashing | Docker’s overlay filesystem adds overhead |
| Permission issues | Containers struggle with mixed UID/GID + bind mounts |
| Inconsistent paths | qBit expects real Linux paths for completed downloads |
| Harder integration | Radarr/Sonarr sometimes misread container-mapped paths |

### 🧠 Therefore:
**qBittorrent on the host is cleaner, faster, and more stable.**

---

# ❌ Why Plex Is NOT in Docker

This is even more important.

### Plex inside Docker struggles with:

| Feature | Issue in Docker |
|--------|-----------------|
| **Hardware transcoding (VAAPI/V4L2/QuickSync)** | Often broken or requires special setup |
| **Direct I/O from large libraries** | Docker overlay adds slowdowns |
| **Automatic network discovery** | Plex uses multicast/IGMP which Docker isolates |
| **Large metadata directories** | Docker containers don’t like millions of tiny files |

Plex has a massive, constantly evolving I/O profile and **performs best on bare metal** (host).

### 🧠 Therefore:
**Install Plex directly on the host for speed, compatibility, and transcoding support.**

---

# 🟩 Why the ARR Stack *Is* in Docker

Radarr, Sonarr, and Prowlarr:

- are lightweight  
- use clean, simple paths  
- store configuration in manageable folders  
- benefit from frequent updates  
- rarely need hardware access  
- behave very predictably in containers  

They’re practically **designed to live inside Docker**.

### ✔ Consistent paths  
As long as `/mnt/omnissiah-vault` is mounted, containers have zero issues.

### ✔ Easy migrations  
Moving to a new server is as simple as:

```
copy configs → run docker-compose → done
```

### ✔ Better isolation  
If Radarr breaks from an update, it won’t affect Plex or qBit.

---

# 🧱 Summary — The Architecture Philosophy

| Component | Host or Docker? | Reason |
|----------|------------------|---------|
| **Docker Engine** | Host | Foundation layer |
| **ARR Stack (Radarr / Sonarr / Prowlarr / Bazarr)** | Docker | Best candidates for containers |
| **qBittorrent** | Host | Needs stable I/O + real filesystem access |
| **Plex** | Host | Needs hardware transcoding + network discovery |

This hybrid approach gives us the **best combination of performance, stability, and maintainability**.

---

# 🧰 Installing Docker (Raspberry Pi / Linux)

Here is the installation script referenced in the flow:

### 📥 Download Script  
👉 **[install-docker.sh](../scripts/shell/install-docker.sh)**  

### 🖥️ What the script does  
- updates the system  
- removes conflicting old packages  
- installs Docker using the official convenience script  
- installs Docker Compose  
- adds your user to the docker group  
- enables and starts the Docker service  
- verifies installation  

After running it:

```bash
sudo reboot
```
Your system will be ready to run containerized ARR services.

# 🚀 Next Step: Configure Plex (Host Installation)
Once Docker is installed, we move forward with:
👉 Install Plex (steps/install-plex.md)
This ensures the server is ready to serve media once the ARR stack begins populating it.