Installation - DentControl

System Requirements

Before installing DentControl, ensure your system meets these requirements:

Server Requirements

PHP: 8.2 or higher
Composer: Latest stable version
Node.js: 18.x or higher
npm: 9.x or higher (comes with Node.js)

PHP Extensions

DentControl requires the following PHP extensions:

OpenSSL
PDO
Mbstring
Tokenizer
XML
Ctype
JSON
BCMath
Fileinfo

Most PHP installations include these extensions by default. Use php -m to verify installed extensions.

Database Options

DentControl supports multiple database systems:

SQLite (default, recommended for development)
MySQL 8.0+ or MariaDB 10.3+
PostgreSQL 12+

Recommended Server Specifications

Development

2 CPU cores
2GB RAM
5GB storage

Production

4+ CPU cores
8GB+ RAM
20GB+ storage (SSD)

Installation Methods

Method 1: Automated Setup (Recommended)

The fastest way to get started:

Clone Repository

git clone https://github.com/Ary-dev04/DentControl.git dentcontrol
cd dentcontrol

Run Setup Script

composer setup

This automated script performs:

Dependency installation
Environment configuration
Database initialization
Asset compilation

Start Development Server

composer dev

Method 2: Manual Installation

For more control over the installation process:

Install PHP Dependencies

composer install

For production, use composer install --optimize-autoloader --no-dev

Configure Environment

Copy the example environment file:

cp .env.example .env

Generate application key:

php artisan key:generate

Configure Database

Edit .env file with your database settings:

DB_CONNECTION=sqlite
# Database file will be created at database/database.sqlite

For SQLite, create the database file:

touch database/database.sqlite

Run Migrations

Create database tables:

php artisan migrate

The migration system will create:

User authentication tables
Clinic management tables
Patient records tables
Appointment scheduling tables
Treatment and clinical records tables
Service catalogs

Install Frontend Dependencies

npm install

Build Assets

For development:

npm run dev

For production:

npm run build

Set Permissions

Ensure storage and cache directories are writable:

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Replace www-data with your web server user (e.g., nginx, apache, or your username for development).

Database Configuration

SQLite Setup (Development)

SQLite is perfect for development and small deployments:

# Create database file
touch database/database.sqlite

# Update .env
DB_CONNECTION=sqlite

# Run migrations
php artisan migrate

Advantages:

No database server required
Zero configuration
Perfect for development
Easy backups (single file)

Limitations:

Limited concurrency
Not suitable for high-traffic production

MySQL Setup (Production)

For production environments, MySQL/MariaDB is recommended:

Create Database

CREATE DATABASE dentcontrol CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'dentcontrol'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON dentcontrol.* TO 'dentcontrol'@'localhost';
FLUSH PRIVILEGES;

Configure .env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dentcontrol
DB_USERNAME=dentcontrol
DB_PASSWORD=secure_password

Run Migrations

php artisan migrate

PostgreSQL Setup (Production)

PostgreSQL offers advanced features for larger deployments:

Create Database

CREATE DATABASE dentcontrol WITH ENCODING 'UTF8';
CREATE USER dentcontrol WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE dentcontrol TO dentcontrol;

Configure .env

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=dentcontrol
DB_USERNAME=dentcontrol
DB_PASSWORD=secure_password

Run Migrations

php artisan migrate

Environment Configuration

Essential Settings

Configure these essential settings in your .env file:

.env

# Application
APP_NAME=DentControl
APP_ENV=production  # or 'local' for development
APP_KEY=base64:...  # Generated by 'php artisan key:generate'
APP_DEBUG=false     # Set to 'true' only in development
APP_URL=https://your-domain.com

# Database (example for MySQL)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dentcontrol
DB_USERNAME=dentcontrol
DB_PASSWORD=your_secure_password

# Session & Cache
SESSION_DRIVER=database  # Important for multi-tenant support
SESSION_LIFETIME=120
CACHE_STORE=database

# Queue System
QUEUE_CONNECTION=database  # or 'redis' for better performance

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME="${APP_NAME}"

Security Notice: Never commit your .env file to version control. It contains sensitive credentials.

Session Configuration

DentControl uses database sessions for multi-tenant support. This ensures proper session isolation between clinics.

The session table is created automatically by migrations. Verify it exists:

php artisan migrate:status | grep sessions

Queue Configuration

Queues handle background jobs. For production, consider Redis:

# Install Redis PHP extension
sudo apt-get install php-redis

# Update .env
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Start the queue worker:

php artisan queue:work --tries=3 --timeout=90

Web Server Configuration

Apache Setup

Enable Required Modules

sudo a2enmod rewrite
sudo systemctl restart apache2

Configure Virtual Host

Create /etc/apache2/sites-available/dentcontrol.conf:

<VirtualHost *:80>
    ServerName dentcontrol.local
    DocumentRoot /var/www/dentcontrol/public

    <Directory /var/www/dentcontrol/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/dentcontrol-error.log
    CustomLog ${APACHE_LOG_DIR}/dentcontrol-access.log combined
</VirtualHost>

Enable Site

sudo a2ensite dentcontrol.conf
sudo systemctl reload apache2

Nginx Setup

Configure Server Block

Create /etc/nginx/sites-available/dentcontrol:

server {
    listen 80;
    server_name dentcontrol.local;
    root /var/www/dentcontrol/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable Site

sudo ln -s /etc/nginx/sites-available/dentcontrol /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Production Deployment

Optimization

Optimize the application for production:

# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev

Security Checklist

File Permissions

# Application files
find /var/www/dentcontrol -type f -exec chmod 644 {} \;
find /var/www/dentcontrol -type d -exec chmod 755 {} \;

# Storage and cache
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Hide Sensitive Files

Ensure .env, .git, and other sensitive files are not web-accessible (handled by public/ directory structure).

Enable HTTPS

Install and configure SSL certificate using Let’s Encrypt:

sudo certbot --nginx -d your-domain.com

Process Management

Use Supervisor to keep queue workers running:

/etc/supervisor/conf.d/dentcontrol-worker.conf

[program:dentcontrol-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/dentcontrol/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/dentcontrol/storage/logs/worker.log
stopwaitsecs=3600

Reload Supervisor:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start dentcontrol-worker:*

Creating the First Super Admin

After installation, create your first super admin user:

php artisan tinker

# Then run:
App\Models\Usuario::create([
    'nombre' => 'Admin',
    'apellido_paterno' => 'System',
    'apellido_materno' => 'Root',
    'email' => '[email protected]',
    'password' => bcrypt('ChangeThisPassword123!'),
    'rol' => 'super_admin',
    'estatus' => 1,
    'id_clinica' => null  // Super admin not tied to a clinic
]);

Important: Change the default password immediately after first login!

Troubleshooting

Common Issues

500 Internal Server Error

Possible causes:

Missing .env file
Incorrect file permissions
Missing APP_KEY

Solutions:

# Check if .env exists
ls -la .env

# Generate app key
php artisan key:generate

# Fix permissions
chmod -R 775 storage bootstrap/cache

Database Connection Failed

For SQLite:

# Ensure file exists
touch database/database.sqlite
chmod 664 database/database.sqlite

For MySQL/PostgreSQL:

Verify credentials in .env
Test connection: php artisan db:show
Check if database exists
Verify user permissions

Assets Not Loading

# Clear cache
php artisan cache:clear
php artisan view:clear

# Rebuild assets
npm run build

# Check public/build directory exists
ls -la public/build

Queue Jobs Not Processing

# Check queue worker is running
ps aux | grep "queue:work"

# Check failed jobs
php artisan queue:failed

# Retry failed jobs
php artisan queue:retry all

# Start worker manually
php artisan queue:work --tries=3

Session/Login Issues

DentControl uses database sessions. Ensure:

# Verify session table exists
php artisan migrate:status | grep session

# Clear session cache
php artisan session:table
php artisan migrate

# Check .env
SESSION_DRIVER=database

Permission Denied Errors

# Fix storage permissions
sudo chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

# For development (use your username)
sudo chown -R $USER:www-data storage bootstrap/cache

Debug Mode

For development troubleshooting:

.env

APP_DEBUG=true
LOG_LEVEL=debug

Check logs:

# View Laravel logs
tail -f storage/logs/laravel.log

# Or use Pail for real-time logs
php artisan pail

Never enable debug mode in production - it exposes sensitive information!

Backup Strategy

Database Backups

# Simple file copy
cp database/database.sqlite backups/database-$(date +%Y%m%d).sqlite

Application Backups

# Backup uploaded files and storage
tar -czf storage-backup-$(date +%Y%m%d).tar.gz storage/app

# Backup .env configuration
cp .env env-backup-$(date +%Y%m%d)

Performance Tuning

OPcache Configuration

Enable PHP OPcache for better performance:

/etc/php/8.2/fpm/conf.d/10-opcache.ini

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=2
opcache.validate_timestamps=0  # Production only

Database Optimization

-- MySQL: Analyze and optimize tables
ANALYZE TABLE clinica, paciente, citas, tratamiento;
OPTIMIZE TABLE clinica, paciente, citas, tratamiento;

-- Add indexes for frequently queried fields
CREATE INDEX idx_paciente_clinica ON paciente(id_clinica);
CREATE INDEX idx_citas_fecha ON citas(fecha_cita);

Next Steps

Your DentControl installation is complete! Here’s what to do next:

Create Your First Clinic

Configure Mail

Set up email notifications for appointments and reminders

Add Users

Create dentist and assistant accounts for your clinic

Customize Settings

Configure service catalogs and treatment templates

For questions or issues, consult the application logs at storage/logs/laravel.log or use php artisan pail for real-time monitoring.

Get Started

Core Features

User Roles

Guides

​System Requirements

​Server Requirements

​PHP Extensions

​Database Options

​Recommended Server Specifications

Development

Production

​Installation Methods

​Method 1: Automated Setup (Recommended)

​Method 2: Manual Installation

​Database Configuration

​SQLite Setup (Development)

​MySQL Setup (Production)

​PostgreSQL Setup (Production)

​Environment Configuration

​Essential Settings

​Session Configuration

​Queue Configuration

​Web Server Configuration

​Apache Setup

​Nginx Setup

​Production Deployment

​Optimization

​Security Checklist

​Process Management

​Creating the First Super Admin

​Troubleshooting

​Common Issues

​Debug Mode

​Backup Strategy

​Database Backups

​Application Backups

​Performance Tuning

​OPcache Configuration

​Database Optimization

​Next Steps

Create Your First Clinic

Configure Mail

Add Users

Customize Settings

Build docs developers (and LLMs) love

System Requirements

Server Requirements

PHP Extensions

Database Options

Recommended Server Specifications

Installation Methods

Method 1: Automated Setup (Recommended)

Method 2: Manual Installation

Database Configuration

SQLite Setup (Development)

MySQL Setup (Production)

PostgreSQL Setup (Production)

Environment Configuration

Essential Settings

Session Configuration

Queue Configuration

Web Server Configuration

Apache Setup

Nginx Setup

Production Deployment

Optimization

Security Checklist

Process Management

Creating the First Super Admin

Troubleshooting

Common Issues

Debug Mode

Backup Strategy

Database Backups

Application Backups

Performance Tuning

OPcache Configuration

Database Optimization

Next Steps