HamNotes - Simple PHP Notes App MVP

A lightweight, multi-user web notes application built with PHP 8.2, Slim 4, Twig, HTMX, and Alpine.js. Designed for deployment on Virtualmin/LAMP servers.

Features

• User authentication (registration, login, password reset)
• Folder management with drag-and-drop reordering
• Rich-text note editing with formatting support
• Full-text search across notes
• Responsive UI with Bootstrap 5
• RESTful API with HTMX for seamless updates
• Automatic trash purging (30 days)

Tech Stack

• Backend: PHP 8.2+, Slim 4, Twig, PDO
• Frontend: HTMX, Alpine.js, Bootstrap 5
• Database: MariaDB 10.6+ / MySQL 8.0+ with full-text search
• Security: Argon2id password hashing, CSRF protection, sessions, rate limiting
• Email: PHPMailer with SMTP or sendmail support

Prerequisites

• PHP 8.2+ with extensions: pdo_mysql, mbstring, intl
• MariaDB 10.6+ or MySQL 8.0+
• Composer for dependency management
• Virtualmin control panel (recommended for deployment)
• Apache/Nginx web server with URL rewriting enabled

Quick Start (Development)

1. Clone the repository

   git clone <repository-url>
   cd hamnotes

2. Install dependencies

   composer install

3. Configure environment

   cp .env.example config/env.php
   # Edit config/env.php with your database and SMTP settings

4. Set up database

   # Create database and user, then run migration
   php migrations/migrate.php

5. Start development server

   # Point your web server document root to the public/ directory
   # Or use PHP's built-in server for testing:
   cd public
   php -S localhost:8000

Production Deployment (Virtualmin/LAMP)

1. Virtualmin Server Setup

1. Create a new virtual server in Virtualmin:

   • Domain: notes.yourdomain.com
   • Enable SSL (Let's Encrypt recommended)
   • PHP version: 8.2 or higher

2. Configure PHP settings:

   • Memory limit: 256MB minimum
   • Max execution time: 300 seconds
   • Upload max filesize: 10MB (for future attachments)
   • Post max size: 10MB

3. Create database:

   • Database name: hamnotes
   • Database user: hamnotes_user
   • Grant all privileges on hamnotes.* to hamnotes_user

2. Application Deployment

1. Upload files to your Virtualmin server:

   # Upload the entire project to /home/yourdomain/public_html/
   # Or create a subdirectory like /home/yourdomain/notes/

2. Install dependencies:

   cd /home/yourdomain/public_html/
   composer install --no-dev --optimize-autoloader

3. Configure environment:

   cp .env.example config/env.php
   # Edit config/env.php with production values:
   # - Database credentials from Virtualmin
   # - SMTP settings (use localhost for sendmail, or configure external SMTP)
   # - App URL: https://notes.yourdomain.com
   # - Environment: 'production'

4. Run database migration:

   php migrations/migrate.php

5. Set proper permissions:

   chown -R yourdomain:yourdomain /home/yourdomain/public_html/
   chmod -R 755 /home/yourdomain/public_html/
   chmod 600 config/env.php  # Secure config file

3. Web Server Configuration

The included .htaccess file handles URL rewriting. Ensure:

• Apache: mod_rewrite is enabled
• Document root: Points to public/ directory
• AllowOverride: Set to All for .htaccess support

4. Email Configuration

For password reset functionality:

Option A: Sendmail (recommended for Virtualmin)

// In config/env.php
'smtp' => [
    'host' => 'localhost',
    'port' => 587,
    'user' => '',  // Leave empty
    'pass' => '',  // Leave empty
    'from' => 'noreply@yourdomain.com',
],

Option B: External SMTP

'smtp' => [
    'host' => 'smtp.gmail.com',  // Or your SMTP provider
    'port' => 587,
    'user' => 'your-email@gmail.com',
    'pass' => 'your-app-password',
    'from' => 'noreply@yourdomain.com',
],

5. Cron Job Setup (Trash Purging)

Set up daily cron job to purge trashed notes older than 30 days:

1. Via Virtualmin: Go to Server Configuration > Scheduled Cron Jobs
2. Add cron job:

   Command: cd /home/yourdomain/public_html && php cli/purge_trash.php
   When to execute: Daily (0 2 * * *) - runs at 2 AM daily
   

Or via command line:

crontab -e
# Add: 0 2 * * * cd /home/yourdomain/public_html && php cli/purge_trash.php

6. Security Configuration

1. SSL/TLS: Ensure SSL is enabled and forced (Virtualmin handles this)

2. File permissions: Keep sensitive files secure:

   chmod 600 config/env.php
   chmod 600 .env.example

3. Rate limiting: Built-in rate limiting protects against brute force attacks

4. CSRF protection: Enabled by default for all forms

5. Session security: Configure secure session settings in PHP:

   session.cookie_secure = 1
   session.cookie_httponly = 1
   session.cookie_samesite = Lax

Development Setup

1. Clone and install as described in Quick Start

2. Enable error reporting in config/env.php:

   'app' => [
       'env' => 'development',
       // ...
   ],

3. Run tests:

   vendor/bin/phpunit

4. Use CLI scripts:

   # Disable a user
   php cli/disable_user.php user@example.com
   
   # Purge trash manually
   php cli/purge_trash.php

Troubleshooting

Common Issues

Database connection fails

• Verify database credentials in config/env.php
• Ensure database user has proper permissions
• Check if MySQL/MariaDB service is running

Emails not sending

• For sendmail: Check mail logs in Virtualmin
• For SMTP: Verify SMTP credentials and server settings
• Test with a simple PHP mail script

404 errors on routes

• Ensure .htaccess is working (check Apache config)
• Verify document root points to public/ directory
• Clear browser cache

Permission errors

• Run: chown -R domainuser:domainuser /home/domainuser/public_html/
• Ensure PHP can write to necessary directories

Composer install fails

• Ensure PHP 8.2+ is available
• Check memory limit: php -r "echo ini_get('memory_limit');"

Logs and Debugging

• PHP errors: Check Virtualmin's error logs
• Application logs: Add error logging to your PHP code if needed
• Database queries: Enable query logging in MySQL for debugging

Performance Tuning

• Database: Ensure proper indexes (included in schema)
• PHP: Use OPcache in production
• Static assets: Consider CDN for Bootstrap/HTMX files in production

Database Schema

The application uses four main tables:

• users: User accounts with Argon2id hashed passwords
• folders: User folders with drag-drop ordering
• notes: Notes with full-text search on title/body
• password_resets: Secure password reset tokens

Run php migrations/migrate.php to set up the database schema.

API Endpoints

The app uses HTMX for dynamic updates. Key endpoints:

• GET/POST /login, /register, /logout
• GET / - Dashboard
• POST /folders - CRUD operations
• GET/POST /notes/{id} - Note operations
• GET /search?q=... - Full-text search

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

License

MIT License

Support

For issues and questions, please check the troubleshooting section or create an issue in the repository.