🐳 INCEPTION

Build Your Own Multi-Service Environment with Docker

"Inception = A Docker based infrastructure project that simulates a production like hosting environment by orchestrating multiple interconnected services."

📚 Table of Contents

#	Section
1	🌍 From Bare Metal to the Cloud
2	🎯 What Is This Project?
3	🏗️ Project Architecture
4	📦 Understanding Containers
5	🆚 Containers vs Virtual Machines
6	🐳 Docker Deep Dive
7	🔩 Linux Internals: Namespaces & Cgroups
8	🗄️ MariaDB — The Data Layer
9	⚙️ PHP, PHP-FPM & Nginx — The Request Flow
10	🚀 Getting Started
11	🛠️ Makefile Commands
12	🔍 Troubleshooting

🌍 From Bare Metal to the Cloud

To truly understand what this project does, you need to understand what happens before any container is ever created.

🖥️ Step 1 — A Physical Server: Just Hardware

When you first get a physical server, it's literally just hardware:

CPU, RAM, hard drive, network card…
But no operating system, no applications, no data.

It's like buying a brand-new computer without Windows or Linux — it can't do anything yet.

⚙️ Step 2 — Install an Operating System

Just like your laptop runs macOS, Windows, or Linux, your server needs an OS — though servers almost always run a server version of Linux (not Windows or macOS):

OS	Use Case
Ubuntu Server	General purpose, beginner-friendly
Debian	Stable, minimal, widely used
CentOS / Rocky Linux	Enterprise environments

The OS is what lets you: store files, run programs, connect to the internet, and accept requests.

🌐 Step 3 — Install Server Software

Now your OS is ready — but it still doesn't know what kind of server it should be. You install specific software to give it a purpose:

Type of Server	Software Example	What It Does
Web server	Nginx, Apache	Serves web pages (HTML, CSS, JS)
Database server	MariaDB, MySQL, PostgreSQL	Stores and provides structured data
Application server	PHP-FPM, Node.js, Django	Runs backend logic or APIs
File server	Samba, FTP, NFS	Stores and shares files

🎯 What Is This Project?

Inception builds a mini web hosting environment on your local machine using Docker — inspired by how modern hosting platforms and cloud providers deploy applications.

🧩 Main Components

Component	Role
Nginx	Receives requests, serves pages, routes PHP requests (reverse proxy)
WordPress / PHP-FPM	Runs the website's code and generates pages dynamically
MariaDB	Stores website data (posts, users, settings, etc.)
Docker Network	Connects containers securely and privately
Docker Volumes	Keeps data persistent between container restarts
Makefile	Automates building, starting, and stopping the environment

🔑 Key Learning Outcomes

✅ How to isolate services using containers
✅ How to connect them securely and persist data
✅ How to automate deployment with a Makefile
✅ Understanding real-world web hosting architecture
✅ Foundation of cloud hosting, networking, and DevOps

🏗️ Project Architecture

Request Flow

Browser → Nginx → WordPress/PHP-FPM → MariaDB → Nginx → Browser

Container Interaction Diagram

flowchart TD
    Browser["🌐 Browser"] -->|"HTTPS Request"| Nginx["🟩 Nginx\n(Reverse Proxy)"]
    Nginx -->|"Static files"| Static["📄 Static Assets\n(HTML/CSS/JS)"]
    Nginx -->|"PHP requests\n(FastCGI)"| WordPress["🔵 WordPress\n(PHP-FPM)"]
    WordPress -->|"SQL Queries"| MariaDB["🟠 MariaDB\n(Database)"]
    MariaDB -->|"Query Results"| WordPress
    WordPress -->|"Generated HTML"| Nginx
    Nginx -->|"Final Response"| Browser

    subgraph volumes["💾 Persistent Volumes"]
        DBVol["📦 DB Volume\n/home/user/data/db"]
        WPVol["📦 WP Volume\n/home/user/data/wp"]
    end

    MariaDB --- DBVol
    WordPress --- WPVol

    subgraph network["🔒 Docker Network (inception)"]
        Nginx
        WordPress
        MariaDB
    end

Directory Structure

Inception/
├── Makefile                    # Automation commands
├── srcs/
│   ├── docker-compose.yml      # Orchestrates all services
│   └── requirements/
│       ├── nginx/              # Nginx container definition
│       │   ├── Dockerfile
│       │   └── conf/
│       ├── wordpress/          # WordPress + PHP-FPM container
│       │   ├── Dockerfile
│       │   └── conf/
│       └── mariadb/            # MariaDB container definition
│           ├── Dockerfile
│           └── conf/
└── secrets/                    # Sensitive credentials (not committed)

📦 Understanding Containers

🍰 The Cake Analogy

Imagine you bake a cake 🍰. To make it, you need:

Ingredients (flour, eggs, sugar…) → libraries & dependencies
Tools (oven, bowl, spoon…) → runtime environment
A recipe (the steps to follow) → your code

If you send only your recipe to a friend but they don't have the same tools or ingredients — they won't be able to make the same cake.

This is the "it works on my computer" problem 😅

🧳 The Container Solution

A container is like a box that you put your program + everything it needs inside:

The program's code
The libraries
The tools it uses
The settings it needs

When you give this box to someone else, they just open it — and everything works perfectly, no matter what computer they're using.

Instead of saying:

"Install Python 3.10, Flask library, and change this configuration file…"

You just run:

docker run mywebsite

🧩 A container is a small box that holds a program and everything it needs, so it can run anywhere easily and safely.

🆚 Containers vs Virtual Machines

💻 Virtual Machine (VM)

A virtual machine is like a big fake computer inside your real computer.

It has:

Its own full operating system (like Windows or Linux)
Its own apps
Its own virtual hardware (CPU, memory, disk)

┌─────────────────────────────────────┐
│          Physical Machine            │
│  ┌─────────────────────────────┐    │
│  │       Hypervisor            │    │
│  │  ┌──────────┐ ┌──────────┐  │    │
│  │  │  VM 1    │ │  VM 2    │  │    │
│  │  │ Full OS  │ │ Full OS  │  │    │
│  │  │ + App 1  │ │ + App 2  │  │    │
│  │  └──────────┘ └──────────┘  │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

⚠️ Heavy and slow — each VM needs a full OS, which costs lots of memory, disk, and CPU.

📦 Container

A container isolates programs — but it's much lighter.

Instead of creating a new fake computer with its own OS, containers share the host's operating system kernel. They only isolate:

The program
Its files
Its libraries

┌─────────────────────────────────────┐
│          Physical Machine            │
│  ┌─────────────────────────────┐    │
│  │     Host Operating System   │    │
│  │  ┌────────┐  ┌────────┐    │    │
│  │  │ Cont.1 │  │ Cont.2 │    │    │
│  │  │ App +  │  │ App +  │    │    │
│  │  │ Libs   │  │ Libs   │    │    │
│  │  └────────┘  └────────┘    │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

✅ Lightweight and fast — containers start in seconds and use minimal resources.

❓ But Wait — How Can a Linux Container Run on Windows?

Great question! Containers share the host's OS kernel:

A Linux container can only work on a Linux kernel
A Windows container can only work on a Windows kernel

Docker's trick: When you install Docker Desktop on Windows or macOS, it secretly runs a small hidden Linux virtual machine in the background 🐧.

Your App → Linux Container → Tiny Hidden Linux VM → Windows/macOS Host

Host System	What Docker Does	What Containers Use
Linux	Runs containers directly	Shares Linux kernel
Windows/macOS	Runs a lightweight Linux VM	Containers share that Linux kernel

📊 Quick Comparison

Feature	Container	Virtual Machine
Startup time	Seconds ⚡	Minutes 🐢
Size	MBs 📦	GBs 💾
OS included	No (shares host kernel)	Yes (full OS)
Isolation	Process-level	Hardware-level
Performance	Near-native	Some overhead
Use case	Microservices, apps	Full OS environments

🐳 Docker Deep Dive

Docker is not a container itself — it's a platform that automates and simplifies everything needed to run containers.

Without Docker — The Hard Way

If you tried to make a container yourself, you'd have to:

Create an isolated filesystem manually
Configure Linux namespaces (process, network, file isolation)
Manage cgroups to control CPU/RAM usage
Set up virtual networking for your container
Handle storage layers

➡️ Building containers by hand would be like assembling an OS from scratch every time.

⚙️ What Docker Does for You

Docker automates all of this:

Builds images (from a Dockerfile)
Runs containers (using docker run)
Manages networking, volumes, and resources
Provides registries (Docker Hub) to share and pull prebuilt images
Ensures consistency — your app runs the same everywhere

🧱 Docker's Core Concepts

1️⃣ Docker Image — The Recipe 📋

Think of it like a boxed meal recipe:

It tells Docker what ingredients you need (software, libraries)
And how to set everything up (commands)
Read-only — you can share this recipe with anyone

# Example: pull a prebuilt image
docker pull nginx

2️⃣ Docker Container — The Running Meal 🍽️

This is the meal you cook from the recipe.

Once you "run" an image, it becomes a container
It's the actual app running in a small isolated environment
Each container is separate from others

# Run a container from an image
docker run nginx

3️⃣ Dockerfile — Your Custom Recipe 📝

This is how you write your own recipe. A simple text file with build instructions:

FROM debian:bullseye

RUN apt-get update && apt-get install -y nginx

COPY ./conf/nginx.conf /etc/nginx/nginx.conf

EXPOSE 443

CMD ["nginx", "-g", "daemon off;"]

4️⃣ Docker Volume — The Safe Storage Box 💾

Containers are temporary. If you delete them, all data inside is gone.

A volume is like a storage box outside the container:

Important data is stored there
It survives even if the container is deleted

# Mount a volume
docker run -v /host/path:/container/path nginx

Example: Database files → stored in a volume, not inside the container.

5️⃣ Docker Network — The Private Hallway 🔒

Containers need to talk to each other. A network is like a private hallway connecting containers:

Only containers on the same network can communicate directly
Provides secure, isolated communication

# docker-compose.yml
networks:
  inception:
    driver: bridge

Example: WordPress container talks to MariaDB container through the inception network.

6️⃣ Docker Compose — The Orchestra Manager 🎼

Running many containers at once manually is hard. Compose is a script that starts all containers together — like a manager telling each chef: "start cooking, here's your station."

# Start everything with one command
docker compose up --build

🔧 Docker's Internal Architecture

Docker CLI (docker command)
         ↓
Docker Engine (dockerd daemon)  →  interacts with Linux Kernel
         ↓
Namespaces + Cgroups + Filesystem
         ↓
Container processes (isolated, resource-limited)

Main Docker Components:

Component	Role
Docker Engine (dockerd)	Core daemon — creates containers, manages images/networking/storage
Docker CLI	The `docker` command — sends instructions to Engine
Docker Images	Read-only templates with app + dependencies
Docker Containers	Running instances of images
Docker Compose	Defines and runs multi-container apps via YAML
Docker Hub/Registry	Store and share images online
Docker Volumes	Persistent storage for containers

🔩 Linux Internals: Namespaces & Cgroups

Namespaces and Cgroups are Linux kernel features — the actual mechanism that makes containers possible.

1️⃣ Namespaces — Isolation 🧱

Namespaces make processes think they have their own separate view of system resources, even though they share the same kernel.

Namespace	What It Isolates
PID	Each container has its own process tree
Network	Each container has its own network interfaces & IP
Mount	Containers have their own filesystem view
UTS	Allows containers to have their own hostname
IPC	Isolates inter-process communication
User	Maps container users to different host users

✅ Effect: Containers feel like they are running on their own independent machine, but share the same OS kernel.

2️⃣ Cgroups — Resource Limiting 📊

Control Groups let you limit, prioritize, and monitor resources that processes can use:

Resource	What You Can Control
CPU	Limit how much CPU time a container gets
Memory	Cap how much RAM a container can use
Disk I/O	Limit read/write speed
Network	Control network bandwidth

Example: You can run 3 containers on the same host but ensure no single container can hog all the CPU or memory.

🗄️ MariaDB — The Data Layer

What Is MariaDB?

MariaDB is a database server — it stores data in an organized way so applications can:

Save information
Read information
Update information
Delete information

Just like your phone contacts app stores names + numbers, WordPress stores:

Posts & pages
Comments
Users & passwords
Site settings

🔑 MariaDB is the place where WordPress stores ALL its data.

Why Can't WordPress Work Without MariaDB?

WordPress cannot store data directly in files for everything — it needs a database to organize its dynamic content. Without MariaDB → WordPress cannot work.

What "Building MariaDB" Means in Inception

You do NOT build MariaDB itself — MariaDB is a complete, existing database engine.

What you DO build is the Docker container that:

Starts from a minimal Linux image (Debian)
Installs MariaDB via the package manager (apt)
Configures it with the right settings
Runs initialization scripts to set up the WordPress database
Keeps data persistent via Docker volumes

FROM debian:bullseye

RUN apt-get update && apt-get install -y mariadb-server

COPY ./conf/my.cnf /etc/mysql/my.cnf
COPY ./tools/init_db.sh /init_db.sh

ENTRYPOINT ["/init_db.sh"]

⚙️ PHP, PHP-FPM & Nginx — The Request Flow

The Three Players

Component	Role
PHP	Server-side scripting language that generates dynamic HTML
PHP-FPM	The engine/daemon that actually runs PHP scripts efficiently
Nginx	The web server that receives requests and decides how to handle them

Detailed Request Lifecycle

1. 🌐 Browser requests:  GET /index.php
              ↓
2. 🟩 Nginx receives the request
              ↓
3. 🤔 Nginx checks: Is this a static file or PHP?
       ├── Static file (HTML/CSS/JS/Image)?
       │         → Nginx serves it directly ⚡
       └── PHP script?
                 → Nginx forwards to PHP-FPM via FastCGI
                           ↓
4. 🔵 PHP-FPM runs the PHP code:
       - Queries MariaDB for data
       - Processes business logic
       - Generates dynamic HTML
                           ↓
5. 🟩 PHP-FPM sends generated HTML back to Nginx
                           ↓
6. 🌐 Nginx sends final HTML to the browser
                           ↓
7. 🖥️ Browser displays the page

Why This Architecture?

Nginx is extremely fast for serving static files
PHP-FPM efficiently processes PHP using worker pools (handles many requests simultaneously)
Together they create a fast, scalable, and secure architecture
This is the standard setup for WordPress, Laravel, and most PHP applications

Key Difference: PHP vs PHP-FPM

	PHP	PHP-FPM
What it is	The language	The process manager
Role	Defines syntax & features	Runs PHP scripts efficiently
Analogy	A cooking language/recipe	The chef who actually cooks

💡 In one sentence: Nginx handles incoming requests, PHP-FPM executes PHP code to generate output, and the browser receives only the final HTML.

🚀 Getting Started

Prerequisites

Docker installed
Docker Compose installed
make available on your system

1. Clone the Repository

git clone https://github.com/Samia-Hb/Inception.git
cd Inception

2. Configure Environment Variables

Edit the .env file inside srcs/ with your credentials:

# Database
MYSQL_DATABASE=wordpress
MYSQL_USER=wp_user
MYSQL_PASSWORD=your_secure_password
MYSQL_ROOT_PASSWORD=your_root_password

# WordPress
WP_ADMIN_USER=admin
WP_ADMIN_PASSWORD=your_admin_password
WP_ADMIN_EMAIL=admin@example.com
DOMAIN_NAME=login.42.fr   # Replace with your actual 42 login (e.g., jdoe.42.fr)

⚠️ Domain Setup: The domain login.42.fr (where login is your 42 username) must resolve to your local machine. Add it to your /etc/hosts file:
echo "127.0.0.1 login.42.fr" | sudo tee -a /etc/hosts

3. Build and Start

make build    # Build all containers from Dockerfiles
make          # Start the full environment

4. Access Your Site

Service	URL
WordPress	`https://login.42.fr` (replace `login` with your 42 username)
MariaDB	Internal (port 3306, container network only)

🛠️ Makefile Commands

Command	Description
`make` or `make all`	Start all services (creates volumes if needed)
`make build`	Build and start all containers
`make down`	Stop all services
`make re`	Restart all services
`make clean`	Stop and remove containers, images, and volumes
`make fclean`	Full cleanup including persistent data on disk

🔍 Troubleshooting

Container fails to start?

# Check logs for a specific service
docker compose -f srcs/docker-compose.yml logs nginx
docker compose -f srcs/docker-compose.yml logs wordpress
docker compose -f srcs/docker-compose.yml logs mariadb

Database connection issues?

Verify .env credentials match between WordPress and MariaDB configs
Ensure MariaDB container fully initialized before WordPress starts (check healthcheck)

Port conflicts?

# Check what's using port 443
sudo lsof -i :443

Full reset?

make fclean   # Removes everything including data volumes
make build    # Rebuild from scratch

🌟 Connection to the Real World

Inception (Local)	Cloud Provider (AWS/Azure/GCP)
Docker containers	Virtual machines / containers
Docker volumes	Cloud storage (EBS, Azure Disk)
Docker network	VPC / Virtual Network
Makefile automation	Terraform / CloudFormation
`login.42.fr`	Your actual domain name

Every large-scale cloud infrastructure starts with the same building blocks you're learning here.

Made with ❤️ by Samia-Hb

"Tell me and I forget. Teach me and I remember. Involve me and I learn." — Benjamin Franklin

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
secrets		secrets
srcs		srcs
DEV_DOC.md		DEV_DOC.md
Makefile		Makefile
README.md		README.md
USER_DOC.md		USER_DOC.md

Folders and files

Latest commit

History

Repository files navigation

🐳 INCEPTION

Build Your Own Multi-Service Environment with Docker

📚 Table of Contents

🌍 From Bare Metal to the Cloud

🖥️ Step 1 — A Physical Server: Just Hardware

⚙️ Step 2 — Install an Operating System

🌐 Step 3 — Install Server Software

🎯 What Is This Project?

🧩 Main Components

🔑 Key Learning Outcomes

🏗️ Project Architecture

Request Flow

Container Interaction Diagram

Directory Structure

📦 Understanding Containers

🍰 The Cake Analogy

🧳 The Container Solution

🆚 Containers vs Virtual Machines

💻 Virtual Machine (VM)

📦 Container

❓ But Wait — How Can a Linux Container Run on Windows?

📊 Quick Comparison

🐳 Docker Deep Dive

Without Docker — The Hard Way

⚙️ What Docker Does for You

🧱 Docker's Core Concepts

1️⃣ Docker Image — The Recipe 📋

2️⃣ Docker Container — The Running Meal 🍽️

3️⃣ Dockerfile — Your Custom Recipe 📝

4️⃣ Docker Volume — The Safe Storage Box 💾

5️⃣ Docker Network — The Private Hallway 🔒

6️⃣ Docker Compose — The Orchestra Manager 🎼

🔧 Docker's Internal Architecture

🔩 Linux Internals: Namespaces & Cgroups

1️⃣ Namespaces — Isolation 🧱

2️⃣ Cgroups — Resource Limiting 📊

🗄️ MariaDB — The Data Layer

What Is MariaDB?

Why Can't WordPress Work Without MariaDB?

What "Building MariaDB" Means in Inception

⚙️ PHP, PHP-FPM & Nginx — The Request Flow

The Three Players

Detailed Request Lifecycle

Why This Architecture?

Key Difference: PHP vs PHP-FPM

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Configure Environment Variables

3. Build and Start

4. Access Your Site

🛠️ Makefile Commands

🔍 Troubleshooting

Container fails to start?

Database connection issues?

Port conflicts?

Full reset?

🌟 Connection to the Real World

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages