Skip to content

DEV_DOC.md

Latest commit

 

History

History
executable file
·
239 lines (168 loc) · 6.45 KB

DEV_DOC.md

File metadata and controls

executable file
·
239 lines (168 loc) · 6.45 KB
Raw

Developer Documentation

Purpose

This project builds a small Docker-based infrastructure for the 42 Inception project. The stack is composed of three isolated services:

  • NGINX: HTTPS entry point exposed on port 443
  • WordPress + PHP-FPM: application service
  • MariaDB: database service used by WordPress

Each service runs in its own container and is built from a dedicated Dockerfile.

Project Structure

.
├── Makefile
├── README.md
├── USER_DOC.md
├── DEV_DOC.md
├── secrets/
│   ├── credentials.txt
│   ├── db_password.txt
│   └── db_root_password.txt
└── srcs/
    ├── .env
    ├── docker-compose.yml
    └── requirements/
        ├── mariadb/
        │   ├── Dockerfile
        │   ├── conf/50-server.cnf
        │   └── tools/init.sh
        ├── nginx/
        │   ├── Dockerfile
        │   ├── conf/default.conf.template
        │   └── tools/script.sh
        └── wordpress/
            ├── Dockerfile
            ├── conf/www.conf
            └── tools/script.sh

Architecture

Network

All services are connected through the custom bridge network inception. Containers communicate internally by service name:

  • nginx forwards PHP requests to wordpress:9000
  • wordpress connects to mariadb:3306

Only NGINX is exposed to the host machine.

Volumes

Persistent data is stored outside the containers through local bind-backed volumes:

  • /home/${LOGIN}/data/mariadb
  • /home/${LOGIN}/data/wordpress

This keeps the database and WordPress files available after container restarts or rebuilds.

Secrets

Sensitive data is injected through Docker secrets:

  • db_password
  • db_root_password
  • credentials

These values are mounted inside /run/secrets/ and read by the startup scripts.

Non-sensitive configuration is loaded from srcs/.env.

Service Details

MariaDB

MariaDB is built from Debian Bookworm and configured with a custom 50-server.cnf.

Main responsibilities:

  • initialize the database directory if it does not exist
  • create the WordPress database
  • create the application user
  • set the root password
  • start MariaDB with persistent storage

Important file:

  • srcs/requirements/mariadb/tools/init.sh

Initialization happens only on first run, detected through /var/lib/mysql/mysql.

WordPress

WordPress runs with PHP-FPM on port 9000.

Main responsibilities:

  • wait until MariaDB is available
  • read database and WordPress credentials from Docker secrets
  • download WP-CLI
  • download WordPress core
  • generate wp-config.php
  • install WordPress
  • create an additional WordPress user
  • start PHP-FPM in foreground mode

Important files:

  • srcs/requirements/wordpress/tools/script.sh
  • srcs/requirements/wordpress/conf/www.conf

The installation is skipped if wp-config.php already exists in the persistent volume.

NGINX

NGINX is the only public entry point of the stack.

Main responsibilities:

  • generate a self-signed TLS certificate
  • inject the configured domain into the NGINX template
  • serve the WordPress files through HTTPS
  • pass PHP requests to the WordPress container

Important files:

  • srcs/requirements/nginx/tools/script.sh
  • srcs/requirements/nginx/conf/default.conf.template

NGINX mounts the WordPress volume in read-only mode.

Startup Flow

The expected startup sequence is:

  1. make build or make creates the required host directories under /home/${LOGIN}/data.
  2. Docker Compose builds and starts the containers.
  3. mariadb initializes its data directory and becomes healthy.
  4. wordpress starts only after MariaDB passes the healthcheck.
  5. WordPress waits until the database accepts connections, then installs itself if needed.
  6. nginx starts and exposes HTTPS on port 443.

Environment Configuration

The file srcs/.env contains non-sensitive values such as:

  • LOGIN
  • DOMAIN_NAME
  • DB_NAME
  • DB_USER
  • WP_TITLE
  • WP_ADMIN_USER
  • WP_ADMIN_EMAIL
  • WP_USER
  • WP_USER_EMAIL

These variables are shared with the services through env_file.

Docker Compose Design Choices

The stack follows these design choices:

  • one process per container
  • one Dockerfile per service
  • one dedicated internal Docker network
  • only one public entry point
  • persistent storage outside the container filesystem
  • secrets separated from regular configuration

This design keeps the stack simple, traceable, and aligned with the project subject.

Makefile Targets

The Makefile provides a small workflow wrapper around Docker Compose.

  • make or make up: start containers
  • make build: build and start containers
  • make down: stop containers
  • make clean: stop containers and remove Docker volumes
  • make fclean: remove volumes and host persistent data
  • make re: full rebuild
  • make ps: show running containers
  • make logs: show service logs

The prepare target creates the host data directories before startup.

Debugging Notes

Useful commands during development:

make ps
make logs
docker compose --env-file srcs/.env -f srcs/docker-compose.yml logs mariadb
docker compose --env-file srcs/.env -f srcs/docker-compose.yml logs wordpress
docker compose --env-file srcs/.env -f srcs/docker-compose.yml logs nginx

To inspect a running container:

docker compose --env-file srcs/.env -f srcs/docker-compose.yml exec mariadb bash
docker compose --env-file srcs/.env -f srcs/docker-compose.yml exec wordpress sh
docker compose --env-file srcs/.env -f srcs/docker-compose.yml exec nginx sh

To test HTTPS locally:

curl -k https://brturcio.42.fr

Known Limitations

Current technical limitations of this implementation:

  • WordPress downloads wp-cli.phar at container startup, which depends on external network access
  • secrets are stored locally in files and should not be committed in a real production workflow
  • NGINX depends on WordPress startup order, but WordPress does not expose a dedicated healthcheck
  • the project uses a self-signed certificate, so browsers will display a warning

Maintenance Notes

If configuration values change, check these areas together:

  • srcs/.env
  • README.md
  • USER_DOC.md
  • domain name configured in /etc/hosts
    • sudo vim /etc/hosts
    • 127.0.0.1 LOGIN.42.fr
  • persistent data paths under /home/${LOGIN}/data

Keeping names and paths aligned is important to avoid broken mounts, wrong domains, or inconsistent documentation.