Skip to main content

​
Overview

RALQ is a PHP-based web application that uses MySQL for data storage and includes modern frontend technologies like Tailwind CSS for styling. This guide covers both Docker deployment and traditional server setup.

​
System Requirements

​
Minimum Requirements

PHP

Version 8.2 or higher

Web Server

Apache with mod_rewrite enabled

Database

MySQL 5.7+ or MariaDB 10.3+

Node.js

Version 14+ (for building frontend assets)
  • RAM: 2GB minimum, 4GB recommended
  • Storage: 500MB for application + database
  • PHP Extensions: mysqli, json, session
  • Browser Support: Modern browsers with WebGL support for 3D models
For AR features to work, end users need mobile devices with ARCore (Android 7.0+) or ARKit (iOS 11+).

​
Quick Start with Docker

The fastest way to deploy RALQ is using Docker.
1

Prerequisites

Ensure Docker is installed on your system:
docker --version
If not installed, get Docker from docker.com
2

Build the Docker Image

RALQ includes a Dockerfile for easy deployment:
Dockerfile
FROM php:8.2-apache

# Copy project files to the container
COPY . /var/www/html/

# Enable Apache rewrite module
RUN a2enmod rewrite
Build the image:
cd /path/to/ralq
docker build -t ralq-app .
3

Run the Container

Start the RALQ container:
docker run -d -p 8080:80 --name ralq ralq-app
The application will be available at http://localhost:8080
4

Set Up Database Connection

You’ll need a MySQL database. You can run MySQL in Docker:
docker run -d \
  --name ralq-mysql \
  -e MYSQL_ROOT_PASSWORD=1234 \
  -e MYSQL_DATABASE=registro_RALQ \
  -p 3306:3306 \
  mysql:8.0
Link the containers:
docker network create ralq-network
docker network connect ralq-network ralq
docker network connect ralq-network ralq-mysql

​
Traditional Server Installation

For deployment on a traditional LAMP/LEMP stack:
1

Install Dependencies

​
On Ubuntu/Debian:

sudo apt update
sudo apt install apache2 php8.2 php8.2-mysqli mysql-server
sudo a2enmod rewrite
sudo systemctl restart apache2

​
On CentOS/RHEL:

sudo yum install httpd php php-mysqli mariadb-server
sudo systemctl enable httpd mariadb
sudo systemctl start httpd mariadb
2

Clone or Upload Files

Upload the RALQ files to your web server:
cd /var/www/html
# Copy your RALQ files here
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html
3

Install Node.js Dependencies

RALQ uses Tailwind CSS for styling:
cd /var/www/html
npm install
The package.json includes:
package.json
{
  "name": "integradora2",
  "version": "1.0.0",
  "devDependencies": {
    "autoprefixer": "^10.4.21",
    "postcss": "^8.5.6",
    "tailwindcss": "^4.1.11"
  }
}
Build the CSS:
npx tailwindcss -i ./src/input.css -o ./build/output.css --watch
4

Configure Apache

Create a virtual host configuration:
/etc/apache2/sites-available/ralq.conf
<VirtualHost *:80>
    ServerName ralq.yourdomain.com
    DocumentRoot /var/www/html

    <Directory /var/www/html>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/ralq_error.log
    CustomLog ${APACHE_LOG_DIR}/ralq_access.log combined
</VirtualHost>
Enable the site:
sudo a2ensite ralq.conf
sudo systemctl reload apache2

​
Database Setup

1

Create the Database

Connect to MySQL:
mysql -u root -p
Create the database:
CREATE DATABASE registro_RALQ CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
The database name registro_RALQ is hardcoded in the application configuration.
2

Create Database User

CREATE USER 'ralq_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON registro_RALQ.* TO 'ralq_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
3

Create Required Tables

Create the users table for authentication:
USE registro_RALQ;

CREATE TABLE usuarios (
    id INT AUTO_INCREMENT PRIMARY KEY,
    nombre VARCHAR(100) NOT NULL,
    apellido_paterno VARCHAR(100) NOT NULL,
    apellido_materno VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
This is a basic schema. You should implement proper password hashing and additional security measures for production.

​
Configuration

​
Database Connection

Update the database credentials in php/validar.php: 
<?php
$servername = "localhost";
$username = "root";
$password = "1234";
$dbname = "registro_RALQ";

// Create connection
$conn = new mysqli($servername, $username, $password, $dbname);

// Check connection
if ($conn->connect_error) {
    die("Conexión fallida: " . $conn->connect_error);
}
?>
Security Best Practices:
  1. Never use root in production: Create a dedicated database user with limited privileges
  2. Use strong passwords: Replace “1234” with a secure password
  3. Move credentials to environment variables: Don’t hardcode sensitive data
  4. Use SSL for database connections: Especially if the database is on a separate server
Recommended Configuration
<?php
$servername = getenv('DB_HOST') ?: 'localhost';
$username = getenv('DB_USER') ?: 'ralq_user';
$password = getenv('DB_PASSWORD');
$dbname = getenv('DB_NAME') ?: 'registro_RALQ';

$conn = new mysqli($servername, $username, $password, $dbname);

if ($conn->connect_error) {
    error_log("Database connection failed: " . $conn->connect_error);
    die("Connection error. Please contact support.");
}
?>

​
File Structure

Ensure these key files are properly configured: 
/var/www/html/
├── index.php              # Landing page
├── registro.php           # User registration
├── iniciosesion.php       # Login page
├── menu.php              # Main menu (requires authentication)
├── estructuras-mol.php   # 3D molecules viewer
├── laboratorios.php      # Lab instruments
├── tabla-periodica.php   # Periodic table
├── Dockerfile            # Docker configuration
├── package.json          # Node.js dependencies
├── php/
│   ├── validar.php       # Database connection
│   ├── log.php           # Login handler
│   └── alerta-registro.php  # Registration handler
├── css/                  # Stylesheets
├── js/                   # JavaScript files
├── img/                  # Images and assets
├── modelos/              # 3D model files (.glb)
└── build/
    └── output.css        # Compiled Tailwind CSS

​
Running the Application

1

Verify PHP Configuration

Check that PHP is working:
php -v
Test Apache and PHP:
echo "<?php phpinfo(); ?>" | sudo tee /var/www/html/test.php
Visit http://your-server/test.php to verify PHP is running.
2

Test Database Connection

Create a test file:
test-db.php
<?php
include('php/validar.php');
echo "Database connection successful!";
$conn->close();
?>
Access it via browser to verify the database connection.
3

Access the Application

Navigate to your server:
  • Landing page: http://your-server/index.php
  • Registration: http://your-server/registro.php
  • Login: http://your-server/iniciosesion.php
Create a test account and verify you can log in.
4

Verify 3D Models Load

After logging in:
  1. Navigate to the molecular structures page
  2. Verify that 3D models load and are interactive
  3. On a mobile device, test AR functionality
3D models use Google’s model-viewer component, loaded from CDN:
<script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>

​
Troubleshooting

​
Common Issues

Symptoms: Error message “Conexión fallida” on any pageSolutions:
  1. Verify MySQL is running: 
    sudo systemctl status mysql
  2. Check credentials in php/validar.php
  3. Ensure the database exists: 
    mysql -u root -p -e "SHOW DATABASES;"
  4. Check MySQL user permissions: 
    SHOW GRANTS FOR 'root'@'localhost';
Symptoms: Empty spaces where molecules should appearSolutions:
  1. Check browser console for errors (F12)
  2. Verify .glb files exist in the modelos/ directory
  3. Ensure file paths are correct in PHP files
  4. Check file permissions: 
    sudo chmod -R 755 modelos/
  5. Verify model-viewer CDN is accessible
Symptoms: AR button doesn’t work or camera doesn’t openSolutions:
  1. Verify device supports AR (ARCore or ARKit)
  2. Ensure HTTPS is enabled (AR requires secure context)
  3. Grant camera permissions in browser
  4. Test on a different device
  5. Check that AR links are valid in estructuras-mol.php
Symptoms: Gets logged out immediately or can’t access menu.phpSolutions:
  1. Check PHP session configuration: 
    php -i | grep session
  2. Verify session_start() is called at the beginning of protected pages
  3. Check session directory permissions: 
    ls -la /var/lib/php/sessions/
  4. Review session code in menu.php (line 2)
Symptoms: Pages look broken or unstyledSolutions:
  1. Verify Tailwind CSS was built: 
    ls -la build/output.css
  2. Rebuild CSS: 
    npx tailwindcss -i ./src/input.css -o ./build/output.css
  3. Check that CSS files are referenced correctly in HTML
  4. Clear browser cache (Ctrl+Shift+R)
  5. Verify CDN link is working: 
    <script src="https://cdn.tailwindcss.com"></script>
Symptoms: 404 errors on certain pagesSolutions:
  1. Enable mod_rewrite: 
    sudo a2enmod rewrite
sudo systemctl restart apache2
  2. Verify AllowOverride is set in Apache config
  3. Check for .htaccess file conflicts

​
Debug Mode

Enable PHP error reporting for debugging: 
<?php
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
?>
Disable error display in production! Log errors instead:
ini_set('display_errors', 0);
ini_set('log_errors', 1);
ini_set('error_log', '/var/log/php/ralq-errors.log');

​
Performance Optimization

​
Caching

  1. Enable OPcache for PHP:
    php.ini
    opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
  2. Browser caching for static assets:
    .htaccess
    <IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType image/jpg "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType model/gltf-binary "access plus 1 month"
</IfModule>

​
CDN for 3D Models

For better performance, consider hosting large .glb files on a CDN: 
<model-viewer
    src="https://cdn.yourdomain.com/modelos/cafeina.glb"
    alt="Modelo de cafeína"
    ...>
</model-viewer>

​
Security Hardening

1

Implement Password Hashing

Update registration to use password_hash():
$hashed_password = password_hash($password, PASSWORD_DEFAULT);
// Store $hashed_password in database
Verify on login:
if (password_verify($input_password, $stored_hash)) {
    // Login successful
}
2

Protect Sensitive Files

.htaccess
<Files "validar.php">
    Order Allow,Deny
    Deny from all
</Files>
3

Enable HTTPS

AR features require HTTPS. Use Let’s Encrypt:
sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d ralq.yourdomain.com
4

SQL Injection Prevention

Use prepared statements:
$stmt = $conn->prepare("SELECT * FROM usuarios WHERE email = ?");
$stmt->bind_param("s", $email);
$stmt->execute();

​
Next Steps

User Management

Implement admin panel for managing registered users

Backup Strategy

Set up automated database backups

Monitoring

Configure server monitoring and error tracking

Scale Up

Deploy load balancers for high-traffic scenarios

​
Support

If you encounter issues not covered in this guide:
  • Email: [email protected]
  • Check logs: /var/log/apache2/ralq_error.log
  • PHP errors: Check your configured error_log path
  • Database: Review MySQL error log
This installation guide is based on RALQ’s current architecture. Future updates may require additional configuration steps.

Build docs developers (and LLMs) love

Get started for freeTalk to us