Skip to content

DEV_DOC.md

Latest commit

 

History

History
177 lines (141 loc) · 6.61 KB

DEV_DOC.md

File metadata and controls

177 lines (141 loc) · 6.61 KB
Raw

DEVELOPER DOCUMENTATION

Set up the environment from scratch

Prerequisites

  • You have to create a Virtual Machine, you can choose the OS you want, I chose Debian but you can choose another OS; This Docs is good for a VM with Debian 13. If you choose another OS some things may not work.
  • Don't forget to add yourself to the sudo group with the sudo adduser $USER sudo command and restart the VM.
  • You have to install Docker in your VM with the following commands :
$ sudo apt-get update
# sudo apt-get install docker-compose-plugin
  • You will need to run the command with sudo privileges so you have to add your user to the docker group.
    • Create the docker group : sudo groupadd docker.
    • Add your user to the docker group : sudo usermod -aG docker $USER
    • Restart the VM so the changes are effective.

  • You may need some other tools like Git, ZSH, vim. Don't forget to download them. You can do it with the following commands.
    • sudo apt install git-all
    • sudo apt install zsh
    • sudo apt install vim

Services

  • You have to set up 3 services (Nginx, WordPress and MariaDB)
    • For each service you have to create a Dockerfile.
    • All the Dockerfiles start with the following line : FROM debian:bookworm to use the penultimate stable version of Debian.
    • Each Dockerfile must install all requirements needed for making the service run.
    • You have to write conf files and a script for the service installation.
    • In these files you may have to use some secret variables but you don't have to write them in raw in your code, you have to create a .env file and call variables with the $ sign before. For example if you want to get the WordPress Admin Password you have to use $WP_ADMIN_PASSWD, and it will return to you the linked variable.

Secrets

  • The .env file is a file where you store all your secret variables; you may not push it into a git repository because some other person may use it with bad intention.
  • This is what a .env file look :
MYSQL_DATABASE=####
MYSQL_USER=####
MYSQL_PASSWD=####
MYSQL_ROOT_PASSWD=####

WP_DOMAIN_NAME=####
WP_SITE_NAME=####
WP_ADMIN_NAME=#####
WP_ADMIN_PASSWD=#####
WP_ADMIN_EMAIL=####
DATA_PATH=####

WORDPRESS_DB_NAME=####
WP_USER=####
WP_USER_EMAIL=####
WP_USER_PASSWD=m####
WORDPRESS_DB_HOST=####
  • You have to link the env file to the services in the docker-compose file.

Build and launch the project using the Makefile and Docker Compose

  • You have to make a Makefile that call a DockerCompose file.

The Makefile

  • There are not many requirements for the Makefile. He must only call you docker-compose.yml file.
    • I use the Makefile Syntax for calling docker comandd.
    make 
# Create the data repositorys.
# Run docker compose up -d to build or run the docker-compose.yml
# I add a personal touch that wait 3 sec and open my website in firefox.

make down
# Call docker compose down to stop all containers.

make clean
# Call docker compose down to stop all containers and delete all data repository.

make fclean
# Call make clean and call docker systeme prune -a -f --volumes for deleting EVERYTHING. 

make re
# Call make fclean and after call make so i delete everything and after i rebuild.

The docker-compose.yml

  • The docker-compose is use to call multiple services at once.
  • The dockercompose is structured like this :
services:
  service1_name:
    build: #call requirements#
    depends_on:
      - #service needed by the service for working#
    ports:
      - "HostPort:ContainerPort"
    container_name : #name
    network:
      - inception
    env_file : path/to/.env
    restart: always 
    volume:
      - volume_name:/where/is/volume

  service2_name:
    etc etc

networks:
  inception:
    driver: bridge

volumes:
  volume_name:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ~/path/to/voulume
Explications on syntax
  • Indentation is VERY VERY IMPORTANT :
    • First layer is for root categories (services, network, volumes)
    • Second layer is for Identifiant (nginx, wordpres, mariadb, inception)
    • Third layer is for Service Properties (image, ports, volumes, ...)
    • Fourth layer os for Values, for each Service Properties there's a value at the next indentation layer that start with a -.

restart : always it's mandatory, if a service can't start it must restart.

Manage the containers and volumes.

Container Lifecycle

  • Start the infrastructure: docker-compose -f srcs/docker-compose.yml up -d
  • Stop and remove containers/networks: docker-compose -f srcs/docker-compose.yml down
  • Check service status: docker-compose -f srcs/docker-compose.yml ps
  • View real-time logs (Debugging): docker-compose -f srcs/docker-compose.yml logs -f [service_name]

Volume Management

  • List all persistent volumes: docker volume ls
  • Inspect volume metadata (Mountpoint): docker volume inspect [volume_name]
  • Deep clean (Remove all unused data/volumes): docker system prune -a --volumes

Access the database

  • To login to the database you can use the comman line sudo docker exec -it srcs-mariadb-1 mysql -u (your mariaDB username) -p and after type you mariaDB password.

  • Useful commands to navigate through the database:
    • USE database_name; — Selects the specific database you want to work with.
    • SHOW TABLES; — Lists the tables, sequences, and views in the current database.
    • SELECT * FROM wp_posts; — Displays a table of all rows and columns from the specified table. Here, we use the * wildcard to select everything from wp_posts.

Data Storage and Persistence

Identification of Storage

In the Inception project, data is stored on the VM and mapped to the containers. This ensures that if a container is deleted, the data remains on the disk.

Service Host Path (Physical Storage) Container Path (Internal)
MariaDB /home/login/data/mariadb /var/lib/mysql
WordPress /home/login/data/wordpress /var/www/html

How Persistence Works

  1. Mounting: When the container starts, it "mounts" the host directory. Any file created by WordPress in /var/www/html is actually written to /home/login/data/wordpress on the VM.
  2. Stateless Containers: Containers are "disposable." Running docker-compose down destroys the containers, but not the folders on the host.
  3. Data Survival: When you run docker-compose up again, the new containers reconnect to the existing data folders, restoring the website state immediately.