Skip to content

DEV_DOC.md

Latest commit

 

History

History
226 lines (167 loc) · 5.23 KB

DEV_DOC.md

File metadata and controls

226 lines (167 loc) · 5.23 KB

Developer Documentation

Overview

This document provides guidance for developers to set up, build, and manage the Inception project locally. The project uses Docker and Docker Compose for containerization, with optional Ansible automation for remote infrastructure provisioning.

Prerequisites

System Requirements

  • OS: Alpine Linux
  • Docker: Version 20.10+ with Docker Compose v2
  • Python: 3.12+ (required only on controller machine for Ansible)
  • Git: For version control
  • OpenSSL: For certificate generation
  • Make: For using the Makefile
  • uv: Fast Python package installer

Python Environment Setup (Control Machine Only)

Python and Ansible are only required on the controller machine (the one running Ansible playbooks to deploy to remote servers). Local Docker Compose development does not require Ansible.

Check Python version:

python3 --version  # Should be 3.12+

Install dependencies:

uv sync

Verify installation:

ansible --version

Setting Up the Environment from Scratch

Step 1: Clone and Initialize Repository

git clone <repository-url> inception
cd inception

Step 2: Install Python Dependencies

Install with uv:

uv sync

Step 3: Configure Project Variables

Edit playbooks/group_vars/all.yml:

Step 4: Generate Secrets Files

Secret files are automatically generated by the Makefile on first run:

make secrets

This command creates the following files in the secrets/ directory with secure permissions (600):

  • db_password.txt - WordPress database password
  • db_root_password.txt - MariaDB root password
  • ftp_password.txt - FTP user password
  • gobackup_ui_password.txt - GoBackup web UI password
  • wordpress_root_password.txt - WordPress admin password (used by WordPress auto-installation)
  • wordpress_user_lrocca_password.txt - WordPress user "lrocca" password

Step 5: Deploy Infrastructure with Ansible

ansible-playbook playbooks/site.yml

This playbook configures the environment, generates SSL certificates, and prepares the system for Docker services.

Verify deployment:

ls -la ssl/  # Check SSL certificates exist
ls -la secrets/  # Check secrets were created

Makefile Overview

The Makefile provides convenient shortcuts for common tasks:

make up      # Start all services (builds if needed)
make down    # Stop all services
make build   # Build Docker images without starting
make logs    # View live logs
make re      # Rebuild and restart everything

Quick Start

After deploying site.yml, start all services with:

make up

This single command:

  1. Generates missing secrets files with secure permissions (600)
  2. Builds Docker images for all services
  3. Starts all containers
  4. Automatically installs WordPress with admin user and plugins
  5. Displays live logs

Press Ctrl+C to exit logs (containers continue running).

First Run WordPress Setup: On first startup, WordPress automatically:

  • Creates the database schema
  • Installs WordPress core with URL https://lrocca.42.fr
  • Creates admin user root with password from wordpress_root_password.txt
  • Creates additional contributor user lrocca for content management
  • Installs and activates the Redis Object Cache plugin
  • Configures Redis connection for performance optimization

On subsequent runs, these setup steps are skipped (WordPress already installed).

Building Only

To build images without starting services:

make build

This is useful for:

  • Verifying Dockerfiles have no syntax errors
  • Pre-building images before deployment
  • Updating base images with docker pull

Docker Compose Direct Commands

For more control, use Docker Compose directly. First change to the srcs directory:

cd srcs

Start services:

docker compose up -d        # Start in background
docker compose up           # Start in foreground (shows logs)

Stop services:

docker compose down         # Stop and remove containers
docker compose stop         # Stop without removing

View status:

docker compose ps           # List containers and status
docker compose logs -f      # Follow logs (live update)
docker compose logs nginx   # Logs for specific service

Rebuild specific service:

docker compose build nginx
docker compose up -d nginx

Execute commands in container:

docker compose exec nginx sh           # Interactive shell
docker compose exec nginx ls /etc      # Single command
docker compose exec wordpress wp-cli   # WordPress CLI

Volume management

List volumes:

docker volume ls

Expected volumes:

  • inception_database - MariaDB data
  • inception_wordpress - WordPress files

Inspect volume:

docker volume inspect inception_database

Remove volume (⚠️ Deletes data):

docker volume rm inception_database

Cleaning Up

Remove stopped containers:

docker container prune

Remove unused volumes:

docker volume prune

Remove unused images:

docker image prune

Full cleanup (⚠️ Removes everything unused):

docker system prune -a