Collections/DEVELOPMENT.md

LocalWeb Development Environment Guide

Overview

This document describes the LocalWeb Collections PHP MVC application development environment setup using LXC containers.

Architecture

Host Environment

• Location: /home/edwin/Documents/Projects/localweb/
• User: edwin
• Container Runtime: Incus/LXC
• Container Name: www

LXC Container www

• OS: Linux distribution with Apache2 + PHP
• Web Root: /var/www/localhost/ (mounted from host project directory)
• Service: apache2.service (running as systemd service)
• Database: SQLite (collections.sqlite)
• PHP Version: Compatible with Composer dependencies

Network Setup

• LXC Proxy: Container port 80 → Host port 80
• Access: http://localhost on host serves the webapp
• Internal: Apache binds to 127.0.0.1:80 inside container

Project Structure

/home/edwin/Documents/Projects/localweb/
├── src/                    # PHP MVC source code
│   ├── Controllers/        # Route handlers
│   ├── Models/            # Data models
│   └── Services/          # Business logic
├── templates/             # Twig templates
├── public/                # Web root (entry point)
├── vendor/                # Composer dependencies
├── collections.sqlite     # SQLite database
└── config.php            # Configuration

Development Workflow

1. Local Development

• Edit files in /home/edwin/Documents/Projects/localweb/
• Changes are immediately reflected in the container via shared mount
• Test via curl localhost or browser at http://localhost

2. Container Management

# Execute commands in container
incus exec www -- <command>

# Check Apache status
incus exec www -- systemctl status apache2

# View Apache logs
incus exec www -- tail -f /var/log/apache2/error.log

# Reload Apache
incus exec www -- systemctl reload apache2

# Check PHP version
incus exec www -- php -v

3. Database Operations

# Access database in container
incus exec www -- sqlite3 /var/www/localhost/collections.sqlite

# Check database permissions
incus exec www -- ls -la /var/www/localhost/collections.sqlite

Application Details

Technology Stack

• PHP: MVC application with PSR-4 autoloading
• Framework: Custom MVC with FastRoute routing
• Templating: Twig templates
• Database: SQLite with PDO
• Frontend: Bootstrap 5 + vanilla JavaScript (SPA-like)
• Dependencies: Managed via Composer

Key Features

• Collections Management: CRUD operations for items
• Categories: Hierarchical category structure
• QR Codes: Automatic generation for items
• Multi-language: Dutch/English support
• Search & Filter: Dynamic content loading

Routing

• Web Routes: Full page loads (/, /categories, /parts)
• API Routes: AJAX endpoints (/api/items, /api/categories)
• Entry Point: public/index.php

Development Commands

Dependencies

# Install/update dependencies
composer install
composer update

# Check for security issues
composer audit

Testing

# Manual testing via curl
curl localhost
curl -s localhost | grep -i "collections"

# Test specific endpoints
curl localhost/api/items
curl localhost/api/categories

Debugging

# Check Apache error logs
incus exec www -- tail -f /var/log/apache2/error.log

# Check access logs
incus exec www -- tail -f /var/log/apache2/access.log

# Verify file permissions
incus exec www -- ls -la /var/www/localhost/

File Permissions

Container Permissions

• Project files: ubuntu:www-data ownership
• Database: ubuntu:ubuntu ownership
• Apache: Runs as www-data user (group access)

Common Issues

• Database permission errors: Check collections.sqlite ownership
• 403 errors: Verify file permissions in container
• 500 errors: Check Apache error logs

Environment Variables & Configuration

PHP Configuration

• Located in container PHP configuration
• Error reporting configured for development
• SQLite extension enabled

Application Config

• config.php: Database path and constants
• SUPPORTED_LOCALES: ['en', 'nl'] for i18n
• DB_PATH: Points to SQLite database file

Deployment Notes

Container Persistence

• Data persists in container filesystem
• Database file stored in project directory
• No external database dependencies

Backup Strategy

• Git repository for code
• SQLite database backup: collections.sqlite.backup
• Regular snapshots of LXC container recommended

Troubleshooting

Common Issues

1. Apache not responding: Check service status in container
2. Database errors: Verify SQLite file permissions
3. 404 errors: Check .htaccess and routing configuration
4. Permission denied: Ensure www-data can read project files

Recovery Commands

# Restart Apache
incus exec www -- systemctl restart apache2

# Fix permissions (if needed)
incus exec www -- chown -R ubuntu:www-data /var/www/localhost/
incus exec www -- chmod -R 755 /var/www/localhost/

# Check container status
incus list
incus info www

Security Considerations

• Container isolation via LXC
• No direct database access from host
• Apache runs with limited privileges
• SQLite database in project directory (not web-exposed)

Performance Notes

• Lightweight SQLite database
• Minimal PHP dependencies
• Efficient routing with FastRoute
• Client-side caching for static assets