Skip to content

USER_DOC.md

Latest commit

 

History

History
267 lines (151 loc) · 9.01 KB

USER_DOC.md

File metadata and controls

267 lines (151 loc) · 9.01 KB
Raw

Contents

Services Provided by the Stack

This project provides the following services:

  • Website (WordPress) The main website of the project, where users can view content and interact with the application through a web browser.

  • Web Server (NGINX) Handles incoming web requests and ensures the website is securely accessible over HTTPS.

  • Database (MariaDB) Stores all persistent data used by the website, such as user accounts and content.

  • Cache System (Redis) Improves website performance by temporarily storing frequently accessed data.

  • FTP Server Allows administrators to upload and manage website files remotely using an FTP client.

  • Database Administration Interface (Adminer) Provides a web-based interface to inspect and manage the database content.

  • Infrastructure Management Interface (Portainer) Offers a visual dashboard to monitor running services and containers.

  • Website (Foco) A simple standalone website is included to demonstrate how additional web content can coexist within the same project.

Starting and Stopping the Project

This repository does not include sensitive configuration files in version control. Running make (or make up) sets both of them up automatically:

  • A .env file inside srcs/, containing the required environment variables. If it doesn't already exist (or is empty), it is created from srcs/.env.example — edit it afterwards with your own values.

  • A directory named secrets at the root of the project containing the password files used by the services, created and filled with strong, randomly generated passwords.

The secrets directory contains the following files, each holding a single line with the corresponding password:

  • db_root_password.txt
  • db_user_password.txt
  • ftp_user_password.txt
  • wp_admin_password.txt
  • wp_user_password.txt

Before running make, you need to make sure your system has Docker and Docker Compose installed.

If this is your first time running the project, you may need an internet connection so your system can download a few required components. After that, the project can work completely offline.

To start the project, open a terminal in the root directory of the repository and run one of the commands:

make || make up

It will automatically prepare the required directories, build the necessary components, and start all services in the background.

Note: if this is the first time running the project, an internet connection is required to download the required components. After the initial setup, the project can be started without internet access.

Once the command completes, all services will be running and ready to use.

To stop all running services, run:

make down

This stops the project safely without deleting any data. All website content and database information are preserved and will be available the next time the project is started.

If you want to fully reset the project by removing all containers, images, volumes, and stored data, run:

make clean

This will permanently delete all project data and should be used with caution.

Accessing the Website and Administration Panels

Since efinda.42.fr isn't a real public domain, your system needs to be told to resolve it locally before it can be reached from a browser. If you haven't done so already, add the following local DNS entry to /etc/hosts:

echo "127.0.0.1 efinda.42.fr" | sudo tee -a /etc/hosts

Once the project is running, you can:

  • Open a web browser.

  • Enter the following URL:

    https://efinda.42.fr

This address opens the main WordPress website, which represents the public-facing part of the project. All content visible here is generated dynamically by WordPress and served securely over HTTPS by Nginx.

In addition to the main website, several administration interfaces are available for management purposes:

WordPress Administration Panel

  • Open a web browser.

  • Go to:

    https://efinda.42.fr/wp-admin

  • Log in using the WordPress administrator credentials:

    • Username: stored in the WP_ADMIN environment variable

    • Password: stored in the file on the WP_ADMIN_SECRET environment variable

This panel allows administrators to manage website content, users, and settings.

Database Administration Panel (Adminer)

  • Open a web browser.

  • Go to:

    http://localhost:8000

  • Use the MariaDB credentials:

    • System: MySQL/MariaDB

    • Server: mariadb

    • Username: set in the MARIADB_USER environment variable

    • Password: stored in the MariaDB user secret file

    • Database: set in the MARIADB_NAME environment variable

Adminer provides a web interface to inspect and manage the database used by WordPress.

Foco

  • Open a web browser.

  • Go to:

    http://localhost:4242

Here, I did exactly what was asked: a simple static website with just one page. I even added a music video of a song I love. It’s like, minimalistic art, right? You get to enjoy a great tune, and that's pretty much it.

Infrastructure Management Panel (Portainer)

  • Open a web browser.

  • Go to:

    https://localhost:9000

Portainer offers a graphical interface to monitor containers, images, volumes, and networks used in the project.

Locate and Manage Credentials

All sensitive credentials in this project are stored inside the secrets/, and each secret is stored in its own file and contains only the password value, without extra formatting.

The available secret files are:

  • db_root_password.txt — MariaDB root password

  • db_user_password.txt — MariaDB user password

  • ftp_user_password.txt — FTP user password

  • wp_admin_password.txt — WordPress administrator password

  • wp_user_password.txt — WordPress regular user password

On the other hand, non-sensitive values (such as usernames, domain names, and service ports) are defined in the .env file. It does not contain passwords, only paths pointing to secret files. This prevents credentials from being exposed through Docker commands or logs.

How Credentials Are Used

  • Credentials are not hardcoded inside Dockerfiles or configuration files.

  • Docker secrets are mounted inside containers at runtime under:

/run/secrets/
  • Entry-point scripts read these files and inject the values only when the container starts.

For example:

  • WordPress reads database and user passwords at startup.

  • MariaDB initializes users using passwords provided via secrets.

  • FTP authentication uses a password read from a secret file.

This means credentials are never visible in:

  • Docker images

  • Source code

  • Version control history

Updating Credentials

To change a password or an environment variable:

  • Edit the corresponding file inside the secrets/ and/or any value on the srcs/.env file.

  • Restart the project using:

make down
make up

The updated credentials will be automatically loaded at container startup.

Security Notes

  • The secrets directory and srcs/.env file are excluded from version control using .gitignore.

  • This prevents accidental leaks when pushing the repository to a remote server.

  • Credentials are only accessible to the containers that explicitly require them.

Checking that the Services Are Running Correctly

To verify that the project is running, list the active Docker containers:

docker ps

Each service in the project runs inside its own container and the container names match the service names defined in the project (nginx, wordpress, mariadb, redis, ftp, adminer, foco, portainer).

If a container appears in the list and its STATUS column shows Up, it means the service is running.

If a container is missing or not marked as Up, there may be a startup or configuration issue.

To inspect what is happening inside a specific service, you can view its logs:

docker logs <container_name>

This command shows the output produced by the service and is usually enough to identify common problems, such as configuration errors or slow startup processes.

Using these commands allows you to quickly verify the state of the infrastructure and diagnose issues without requiring in-depth technical knowledge.