This project has been created as part of the 42 curriculum by jyniemit

Inception

Inception is a small WordPress site built from scratch with Docker Compose. It is designed to run inside a virtual machine and keep the website and database data even when containers are recreated.

What is running?

Service	Purpose	Reachable from
NGINX	HTTPS entry point and PHP request proxy	Your browser on port 443
WordPress + PHP-FPM	The website and its administration panel	NGINX only
MariaDB	WordPress database	WordPress only

NGINX is the only public service. WordPress and MariaDB communicate over the private inception Docker network.

Quick start

1. Work from the required virtual machine with Docker, Docker Compose, and Make installed. Ensure Docker is running and your user can access it; see Docker access.
2. Create your local configuration file:

   cp srcs/.env.example srcs/.env
   

3. Edit srcs/.env. Replace every <...> value, set DATA_DIR, and keep WORDPRESS_DB_HOST=mariadb. All ports are configured there: HTTPS_PORT (host input), NGINX_PORT (NGINX listener), PHP_FPM_PORT, and MARIADB_PORT. HTTPS_PORT maps the host to NGINX_PORT; defaults 443/443/9000/3306 satisfy project requirements. WordPress automatically tracks the resulting public URL.
4. Create the four local secret files listed in Credentials.
5. Configure a VirtualBox host-only adapter and map <login>.42.fr to the VM's host-only IP address; see Access the VM-hosted site.
6. Start the stack:

   make
   

7. Open https://<login>.42.fr. The certificate is self-signed, so your browser will display a warning. Then visit /wp-admin/ to sign in.

Use make clean to stop the stack and remove its containers and network. make re rebuilds it without deleting your site or database data.

Access the VM-hosted site

On school computers, the browser is on the host and Docker is inside the VM. Configure VirtualBox so the host can reach the VM:

1. In Tools → Network → Host-only Networks, create or select a host-only network, for example vboxnet0 with 192.168.56.1/24 and DHCP enabled.
2. Power off the VM. In Settings → Network → Adapter 2, enable the adapter, set Attached to to Host-only Adapter, select vboxnet0, and keep Cable Connected checked. This is a host-only adapter—not a bridged adapter. Adapter 1 may stay on NAT for Internet access.
3. Start the VM and discover its address on that network:

   ip -4 addr show
   

   Find the inet address in the 192.168.56.x subnet (for example, 192.168.56.10/24). Do not use 127.0.0.1, a Docker 172.x.x.x address, or 192.168.56.1 (the host-only adapter's address).
4. On the host computer, open the site with Chrome, replacing the login and IP address with yours:

   flatpak run com.google.Chrome --incognito --user-data-dir="$HOME/.inception-chrome" --host-resolver-rules="MAP <login>.42.fr 192.168.56.10" "https://<login>.42.fr"
   

The Chrome resolver rule affects only this browser instance and avoids changing the host's /etc/hosts. The VM address can change when DHCP is used, so repeat ip -4 addr show and update the command if the mapping no longer works. A self-signed-certificate warning is expected.

Credentials

Configuration values such as the domain, database name, and user names belong in the ignored srcs/.env file. Passwords are separate Docker Compose secrets, stored locally in these ignored files:

secrets/mysql_password
secrets/mysql_root_password
secrets/wp_admin_password
secrets/wp_user_password

Each file must contain one non-empty password. Use simple passwords made only of letters, digits, and safe punctuation such as ., _, -, or !; do not use single quotes, backslashes, or line breaks. make checks that all four files exist before it starts the containers. Never commit .env or secrets/, and never put passwords in Dockerfiles.

How data is kept

The stack uses two named volumes backed by folders on the VM:

Host folder	Container folder	Contains
$DATA_DIR/wordpress	/var/www/html	WordPress files, themes, uploads
$DATA_DIR/mariadb	/var/lib/mysql	MariaDB database files

make clean removes containers and the Compose network but preserves images, volume objects, and these host folders. make fclean additionally removes volume objects and all project images, including explicitly tagged service images, while preserving the host folders. make purge first runs the global evaluator Docker cleanup, then performs project cleanup and deletes exactly these two folders.

Warning: make purge irreversibly deletes the WordPress site and MariaDB data under $DATA_DIR. Confirm DATA_DIR and make a backup before running it.

Design notes

Virtual machine vs Docker

The virtual machine is the required isolated computer. Docker runs the services inside that VM. A VM includes its own operating system and kernel; containers share the VM kernel, so they are lighter and start faster. Here, the VM provides the outer boundary and Docker separates the web server, application, and database.

Secrets vs environment variables

Environment variables are convenient for non-sensitive configuration. Secrets are better for passwords because Compose mounts them as files under /run/secrets/ instead of placing them in a Dockerfile or tracked configuration. Both are local and ignored by Git in this project.

Docker network vs host network

The custom bridge network gives services private DNS names such as mariadb. It lets WordPress reach the database without exposing the database to the VM network. Host networking and legacy links are not used.

Docker volumes vs bind mounts

Compose gives the project named volumes, while the local volume driver binds them to $DATA_DIR. This keeps durable data easy to locate and back up on the VM. A normal Docker-managed volume is stored in Docker's own data directory instead.

Useful commands

make                 # build and start
make ps              # show containers
make logs            # follow all logs
make nginx-logs      # show NGINX logs
make wp-logs         # show WordPress logs
make mariadb-logs    # show MariaDB logs
make clean           # stop and remove containers
make fclean          # remove project volumes and images
make purge           # destructive: delete the two persistent data folders
make db-shell        # open a MariaDB shell
make db-login        # MariaDB client as MYSQL_USER (prompts for password)
make db-root         # MariaDB client as root (prompts for password)

Use SHOW DATABASES; and SHOW TABLES FROM <database>; in the client. Edit only srcs/.env to change ports, then run make re; keep external HTTPS_PORT at 443 normally for project compliance.

To query MariaDB manually, run make db-shell, then run:

mariadb -u <login> -p<password>
SHOW DATABASES;
SHOW TABLES FROM <database>;

Replace <login> with MYSQL_USER from srcs/.env, <password> with the value in secrets/mysql_password, and <database> with MYSQL_DATABASE. make db-login is the safer equivalent because it prompts for the password instead of placing it in shell history. It uses Docker Compose to locate the MariaDB container, so it remains valid without assigning a fixed mariadb container name.

For fuller operating and development instructions, see USER_DOC.md and DEV_DOC.md.

Resources

• Docker Compose documentation
• Docker storage: volumes
• Docker secrets in Compose
• NGINX documentation
• WordPress administration documentation
• MariaDB documentation

AI was used to help review and rewrite the project documentation. The configuration, commands, and technical descriptions were checked against this repository before inclusion.