Skip to content

DEV_DOC.md

Latest commit

 

History

History
171 lines (126 loc) · 4.7 KB

DEV_DOC.md

File metadata and controls

171 lines (126 loc) · 4.7 KB

Developer Documentation — Inception

Environment Setup

Prerequisites

  • OS: Debian-based VM (Ubuntu/Debian recommended)
  • Tools:
    • Docker Engine (v20+)
    • Docker Compose (v2+)
    • GNU Make
    • Git

Install Docker (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install -y docker.io docker-compose-plugin
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

Project Structure

inception/
├── Makefile                          # Build & orchestration commands
├── README.md                         # Project overview
├── USER_DOC.md                       # User documentation
├── DEV_DOC.md                        # This file
├── .gitignore                        # Git ignore rules
├── secrets/                          # Docker secrets (NOT in Git)
│   ├── credentials.txt               # WP admin password
│   ├── db_password.txt               # MariaDB user password
│   └── db_root_password.txt          # MariaDB root password
└── srcs/
    ├── .env                          # Environment variables (NOT in Git)
    ├── docker-compose.yml            # Service definitions
    └── requirements/
        ├── nginx/
        │   ├── Dockerfile
        │   ├── .dockerignore
        │   └── conf/nginx.conf       # NGINX site config
        ├── wordpress/
        │   ├── Dockerfile
        │   ├── .dockerignore
        │   ├── conf/www.conf         # php-fpm pool config
        │   └── tools/wp-setup.sh     # WP init entrypoint
        └── mariadb/
            ├── Dockerfile
            ├── .dockerignore
            ├── conf/50-server.cnf    # MariaDB server config
            └── tools/db-setup.sh     # DB init entrypoint

Configuration Files

srcs/.env

Contains non-sensitive environment variables:

  • DOMAIN_NAME — the project domain (e.g., ezohin.42.fr)
  • MYSQL_USER, MYSQL_DATABASE — database config
  • WP_ADMIN_USER, WP_TITLE, etc. — WordPress config

secrets/

Contains one secret per file. These are mounted into containers via Docker secrets at /run/secrets/. Scripts read them with cat /run/secrets/<name>.

Building & Launching

Full build and start

make          # Equivalent to: make up

This will:

  1. Create data directories at /home/ezohin/data/{wordpress,mariadb}
  2. Build all 3 Docker images from their Dockerfiles
  3. Start all containers via docker compose up -d --build

Stop services

make down     # Stop and remove containers
make stop     # Stop without removing

Clean up

make clean    # Remove containers + images
make fclean   # Remove everything + volumes + host data
make re       # Full clean + rebuild

Container Management

Useful commands

# Enter a container shell
docker exec -it nginx bash
docker exec -it wordpress bash
docker exec -it mariadb bash

# Check container logs
docker logs nginx
docker logs wordpress
docker logs mariadb

# Follow all logs
make logs

# Check container status
make status

Rebuild a single service

docker compose -f srcs/docker-compose.yml build nginx
docker compose -f srcs/docker-compose.yml up -d nginx

Data Persistence

Volume locations on host

Volume Host Path Container Mount
wp_files /home/ezohin/data/wordpress /var/www/html
db_data /home/ezohin/data/mariadb /var/lib/mysql

Both use Docker named volumes with the local driver and device pointing to the host directory.

Data survives

  • Container restarts (docker restart)
  • make down + make up
  • Image rebuilds

Data is destroyed by

  • make fclean (removes host data directories)
  • docker volume rm <volume_name>

Network Architecture

All containers are connected to a single Docker bridge network named inception.

  • NGINX → listens on port 443 (TLS), proxies PHP requests to wordpress:9000
  • WordPress → listens on port 9000 (php-fpm), connects to mariadb:3306
  • MariaDB → listens on port 3306

Only NGINX exposes a port to the host. All inter-service communication happens on the internal Docker network.

Entrypoint Scripts

MariaDB (db-setup.sh)

  1. Reads secrets from /run/secrets/
  2. If database doesn't exist: initializes MariaDB, creates database and user
  3. Starts mysqld in foreground (PID 1)

WordPress (wp-setup.sh)

  1. Reads secrets from /run/secrets/
  2. Waits for MariaDB to be ready (connection loop)
  3. If wp-config.php doesn't exist: downloads WordPress, configures it, installs it, creates users
  4. Starts php-fpm in foreground (PID 1)