Skip to content

USER_DOC.md

Latest commit

 

History

History
306 lines (246 loc) · 7.33 KB

USER_DOC.md

File metadata and controls

306 lines (246 loc) · 7.33 KB

USER_DOC.md — User Documentation

Overview

This document explains how to use the Inception project as an end user or system administrator. It covers starting/stopping the services, accessing applications, managing credentials, and verifying service health.

What Services Are Provided?

The Inception stack provides a complete web infrastructure with the following components:

Service Purpose Access
WordPress Website CMS (Content Management System) https://mkhavari.42.fr
Nginx Web server & reverse proxy (HTTPS) Automatically handles requests to WordPress
MariaDB Database server Internal (port 3306, not exposed)
Redis Caching system Internal (port 6379, improves WordPress performance)
Adminer Database management UI http://localhost:8080/adminer.php
FTP File transfer service localhost:21 (for uploading WordPress files)
Portainer Docker container management UI https://localhost:9443
React Portfolio Bonus frontend application http://localhost:5173

Starting and Stopping the Project

Start All Services

cd /path/to/inception
make all

This command:

  • Sets up the environment (hosts file, data directories, secrets)
  • Builds Docker images
  • Starts all containers in the background

First startup takes 2-3 minutes while containers initialize.

Stop All Services

make down

This stops and removes all containers (data persists in volumes).

Stop Services (Keep Containers)

make stop

Pauses all containers without removing them.

Restart Services

make restart

Restarts all running containers (useful after configuration changes).

Check Service Status

make ps

Shows which containers are running.

Accessing the Website and Administration Panel

Access WordPress Website

https://mkhavari.42.fr
  • This is your main website
  • Built with WordPress CMS
  • Uses HTTPS (secure, self-signed certificate)

WordPress Admin Panel

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

Login Credentials:

  • Username: mkhavari
  • Password: Read from secrets/wp_admin_password.txt

From the terminal:

cat secrets/wp_admin_password.txt

WordPress User Accounts

The system creates two WordPress users:

User Role Purpose
mkhavari Administrator Full control (can install plugins, manage users, etc.)
javad Author Can write and publish posts only
wp_user Database User NOT a WordPress user — only for database connection

Adminer (Database Manager)

http://localhost:8080

Use to:

  • View/edit database contents directly
  • Run SQL queries
  • Backup/restore database

Login Credentials:

  • Server: mariadb
  • Username: wp_user
  • Password: Read from secrets/db_password.txt
  • Database: wordpress

Portainer (Container Management)

https://localhost:9443/

Use to:

  • View container logs
  • See resource usage (CPU, memory)
  • Restart/stop individual containers
  • Monitor container health

First Login:

  • Create admin username and password on first visit

React Portfolio

http://localhost:5173

Bonus feature — a personal portfolio website.

FTP Access

Host: localhost
Port: 21
Username: ftpuser
Password: Read from secrets/ftp_password.txt

Use an FTP client to upload/download WordPress files.

Locating and Managing Credentials

Where Are Credentials Stored?

All sensitive credentials are in the secrets/ directory:

secrets/
├── db_password.txt              # WordPress database user password
├── db_root_password.txt         # MariaDB root password
├── wp_admin_password.txt        # WordPress admin (mkhavari) password
├── wp_user_password.txt         # WordPress author (javad) password
├── ftp_password.txt             # FTP user password
└── portainer_pass.txt           # Portainer admin password (if configured)

View a Credential

cat secrets/db_password.txt
cat secrets/wp_admin_password.txt

Regenerate Secrets

⚠️ Warning: Only do this if you've never used the services, or you'll lose access.

rm secrets/*.txt
make secrets

Change WordPress Admin Password

After logging into WordPress admin panel:

  1. Go to Users > All Users
  2. Click on mkhavari
  3. Scroll down to Account Management
  4. Change password and save

Checking That Services Are Running Correctly

1. List All Running Containers

make ps

Should show 8 containers in "Up" status:

NAME        STATUS
nginx       Up
wordpress   Up
mariadb     Up
redis       Up
adminer     Up
ftp         Up
portainer   Up
react       Up

2. Test WordPress

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

Should return HTML (WordPress home page).

3. Test Database Connection

docker exec -it wordpress bash -c \
  'mariadb -hmariadb -u wp_user -p"$(cat /run/secrets/db_password)" -e "SELECT 1;"'

Should output: 1 (connection successful)

4. Test Redis Cache

docker exec -it redis redis-cli ping

Should output: PONG

5. View Service Logs

Check for errors in any service:

docker logs nginx       # Nginx logs
docker logs wordpress   # WordPress PHP errors
docker logs mariadb     # Database logs
docker logs redis       # Cache logs

6. Check Data Storage

Verify data is persisting:

ls -lah /home/mkhavari/data/

Should show:

  • wordpress/ — WordPress files and uploads
  • mariadb/ — Database files

Common Issues and Solutions

Issue: Cannot access WordPress

Solution:

  1. Check if containers are running: make ps
  2. Verify domain in /etc/hosts: grep mkhavari /etc/hosts
  3. Check nginx logs: docker logs nginx
  4. Restart: make restart

Issue: FTP Connection Failed

Solution:

  1. Check FTP container is running: make ps
  2. Verify FTP user was created: docker exec -it ftp id ftpuser
  3. Check password: cat secrets/ftp_password.txt

Issue: WordPress Slow or Not Loading

Solution:

  1. Check Redis is connected: docker exec -it redis redis-cli ping
  2. Check database: docker logs mariadb | tail -20
  3. Restart WordPress: docker restart wordpress

Issue: Cannot Access Portainer/Adminer

Solution:

  1. Clear browser cache
  2. Check containers: make ps
  3. Verify port mapping: docker ps

Backup and Restore

Backup WordPress Data

tar -czf wordpress_backup.tar.gz /home/mkhavari/data/wordpress/

Backup Database

docker exec mariadb mysqldump -u root -p$(cat secrets/db_root_password.txt) \
  wordpress > wordpress_db_backup.sql

Restore Database

docker exec -i mariadb mysql -u root -p$(cat secrets/db_root_password.txt) \
  wordpress < wordpress_db_backup.sql

Troubleshooting Quick Reference

Problem Command to Check
Container won't start docker logs <container_name>
Port already in use lsof -i :<port>
Database connection error make logs or docker logs wordpress
Files not syncing ls -la /home/mkhavari/data/wordpress/
High memory usage docker stats

Contact & Support

For issues or questions, check:

  1. The logs: docker logs <service_name>
  2. The DEV_DOC.md for technical details
  3. The README.md for project overview