VPS Deployment Guide

This guide covers deploying Health Manager on a Virtual Private Server (VPS) or any hosting environment with SSH/console access.

Requirements

Before starting, ensure your VPS meets these requirements:

PHP 8.4 or higher
Composer (PHP dependency manager)
Node.js & NPM (for building frontend assets)
Git (for cloning the repository)
Web Server (Nginx or Apache)
Database (MySQL, MariaDB, PostgreSQL, or SQLite)
SSL Certificate (recommended for production)

Required PHP Extensions

Health Manager requires the following PHP extensions:

Ctype
cURL
DOM
Fileinfo
Filter
Hash
Mbstring
OpenSSL
PCRE
PDO
Session
Tokenizer
XML
BCMath
Zip
Intl
GD (for image processing)
Exif

Installation Steps

Clone the Repository

Connect to your VPS via SSH and clone the Health Manager repository:

git clone https://github.com/formatocd/health-manager.git
cd health-manager

Install Dependencies

Install PHP dependencies with Composer and build frontend assets with NPM:

Composer & NPM

composer install --no-dev --optimize-autoloader
npm install && npm run build

Composer Only

composer install --no-dev --optimize-autoloader

NPM Only

npm install && npm run build

The --no-dev flag excludes development dependencies, keeping your production environment lean and secure.

Initial Configuration

Create your environment configuration file and generate the application key:

cp .env.example .env
php artisan key:generate

Important: Do not run database migrations manually. Health Manager uses an auto-installation system that creates tables automatically on first access.

Environment Configuration

Edit the .env file to configure your application:

Production Settings

APP_NAME="Health Manager"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com
APP_LOCALE=en

Security: Always set APP_DEBUG=false in production to prevent sensitive information leaks.

Database Configuration

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=health_manager
DB_USERNAME=your_username
DB_PASSWORD=your_secure_password

Mail Configuration

Configure SMTP settings for email notifications and password recovery:

MAIL_MAILER=smtp
MAIL_HOST=smtp.yourserver.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Common SMTP Providers Configuration

Gmail:

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls

Mailgun:

MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_ENCRYPTION=tls

SendGrid:

MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_ENCRYPTION=tls

Web Server Configuration

Critical: Your web server must point to the /public directory, not the project root. This is essential for security.

Nginx Configuration

Create a new Nginx server block configuration:

/etc/nginx/sites-available/health-manager

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com;
    root /path/to/health-manager/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.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

Enable the site and restart Nginx:

ln -s /etc/nginx/sites-available/health-manager /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

Apache Configuration

Create a virtual host configuration:

/etc/apache2/sites-available/health-manager.conf

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /path/to/health-manager/public

    <Directory /path/to/health-manager/public>
        AllowOverride All
        Require all granted
    </Directory>

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

Enable required modules and the site:

a2enmod rewrite
a2ensite health-manager
systemctl restart apache2

File Permissions

Set proper permissions for Laravel directories:

chown -R www-data:www-data /path/to/health-manager
chmod -R 775 /path/to/health-manager/storage
chmod -R 775 /path/to/health-manager/bootstrap/cache

Replace www-data with your web server user if different (e.g., nginx, apache, or httpd).

SSL/TLS Configuration (Recommended)

Secure your application with a free SSL certificate using Let’s Encrypt:

Install Certbot

sudo apt update
sudo apt install certbot python3-certbot-nginx

Obtain Certificate

sudo certbot --nginx -d yourdomain.com

Certbot will automatically modify your Nginx configuration to use HTTPS.

Update .env File

Update your APP_URL to use HTTPS:

APP_URL=https://yourdomain.com

First Access & Admin Creation

Health Manager uses a “First User Takeover” system:

Navigate to Your Domain

Visit your domain in a web browser (e.g., https://yourdomain.com).

Automatic Database Setup

The system will detect an empty database and automatically create all necessary tables.

You’ll be redirected to the registration page. The first user to register becomes the administrator.

Start Using Health Manager

After registration, you’ll have full administrative access to the application.

Security Tip: Register your admin account immediately after deployment to prevent unauthorized users from claiming admin rights.

Performance Optimization

Enable OPcache

Add to your PHP configuration (/etc/php/8.4/fpm/php.ini):

opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0

Cache Configuration

Optimize Laravel’s configuration cache:

php artisan config:cache
php artisan route:cache
php artisan view:cache

Run these commands after any configuration changes to apply updates.

Troubleshooting

500 Internal Server Error

Possible causes:

Incorrect permissions: Ensure storage and bootstrap/cache directories are writable
```
chmod -R 775 storage bootstrap/cache
```
Missing APP_KEY: Generate a new application key
```
php artisan key:generate
```
Check error logs:
```
tail -f storage/logs/laravel.log
```

Database Connection Error

Verify database credentials in .env
Ensure database server is running
Check if database user has proper permissions

Test connection:

php artisan tinker
DB::connection()->getPdo();

Assets Not Loading

Verify web server points to /public directory
Check if public/build directory exists
Rebuild assets:
```
npm run build
```
Clear browser cache

Email Not Sending

Verify SMTP configuration in .env
Check if firewall allows outbound SMTP connections

Test mail configuration:

php artisan tinker
Mail::raw('Test email', function($msg) { $msg->to('[email protected]')->subject('Test'); });

Review logs:
```
tail -f storage/logs/laravel.log
```

Permission Denied Errors

Ensure proper ownership and permissions:

# Set ownership
chown -R www-data:www-data /path/to/health-manager

# Set directory permissions
find /path/to/health-manager -type d -exec chmod 755 {} \;

# Set file permissions
find /path/to/health-manager -type f -exec chmod 644 {} \;

# Set storage permissions
chmod -R 775 storage bootstrap/cache

Maintenance & Updates

Update Application

To update Health Manager to the latest version:

cd /path/to/health-manager
git pull origin main
composer install --no-dev --optimize-autoloader
npm install && npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache

Backup

Regularly backup your database and .env file:

# Backup database (MySQL example)
mysqldump -u username -p health_manager > backup-$(date +%Y%m%d).sql

# Backup .env file
cp .env .env.backup

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

Next Steps

Configure user roles and permissions in the admin panel
Customize email templates
Set up automated backups
Configure monitoring and logging
Review security best practices

Get Started

Core Features

Deployment

User Guide

Administration

Requirements

Required PHP Extensions

Installation Steps

Environment Configuration

Production Settings

Database Configuration

Mail Configuration

Web Server Configuration

Nginx Configuration

Apache Configuration

File Permissions

SSL/TLS Configuration (Recommended)

Install Certbot

Obtain Certificate

Update .env File

First Access & Admin Creation

Performance Optimization

Enable OPcache

Cache Configuration

Troubleshooting

Maintenance & Updates

Update Application

Backup

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

User Guide

Administration

​Requirements

​Required PHP Extensions

​Installation Steps

​Environment Configuration

​Production Settings

​Database Configuration

​Mail Configuration

​Web Server Configuration

​Nginx Configuration

​Apache Configuration

​File Permissions

​SSL/TLS Configuration (Recommended)

​Install Certbot

​Obtain Certificate

​Update .env File

​First Access & Admin Creation

​Performance Optimization

​Enable OPcache

​Cache Configuration

​Troubleshooting

​Maintenance & Updates

​Update Application

​Backup

​Next Steps

Build docs developers (and LLMs) love

Requirements

Required PHP Extensions

Installation Steps

Environment Configuration

Production Settings

Database Configuration

Mail Configuration

Web Server Configuration

Nginx Configuration

Apache Configuration

File Permissions

SSL/TLS Configuration (Recommended)

Install Certbot

Obtain Certificate

Update .env File

First Access & Admin Creation

Performance Optimization

Enable OPcache

Cache Configuration

Troubleshooting

Maintenance & Updates

Update Application

Backup

Next Steps