Add README.md

1 files changed, 116 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..081de594
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# slx-admin
+
+`slx-admin` is a web-based administration interface for **bwLehrpool Satellite servers**. These servers are typically deployed at universities to provide netboot services for computer labs across the campus.
+
+Clients boot a Linux flavor over the network, allowing students to choose from a list of "lectures" that run as virtual machines tailored to specific courses. This interface is used by technical staff to manage the lab hardware and by organizers to manage electronic exams.
+
+This documentation is intended for **developers**. End users typically receive a pre-configured virtual machine image containing a set-up `slx-admin`.
+
+## Stack
+- **Language**: PHP (Legacy, recommended 7.4+ or 8.0+)
+- **Database**: MySQL / MariaDB (using PDO)
+- **Templating**: Mustache (bundled engine in `Mustache/`)
+- **Package Manager**: None (Dependencies are mostly bundled).
+
+## Requirements
+- **Web Server**: agnostic, currently running under lighttpd 1.4.x
+- **PHP Extensions**:
+  - `pdo_mysql`
+  - `mbstring`
+  - `curl`
+  - `xml`
+  - `json`
+  - `soap`
+- **MariaDB Server**:
+  - Version 5.7 or higher is recommended.
+
+## Setup & Installation
+
+### 1. Enable Modules
+`slx-admin` uses a symlink-based activation system. Modules are stored in `modules-available/` and enabled by symlinking them into `modules/`.
+
+```bash
+cd modules/
+# Example: Enable the 'main' module
+ln -s ../modules-available/main main
+# Enable all common modules (TODO: List required/common modules)
+```
+
+### 2. Configuration
+Copy the example configuration file and update it with your environment details:
+
+```bash
+cp config.php.example config.php
+```
+
+Edit `config.php` and configure:
+- MySQL credentials (`CONFIG_SQL_DSN`, `CONFIG_SQL_USER`, `CONFIG_SQL_PASS`)
+- File paths for TFTP, HTTP, and VM storage.
+- External service URLs (Masterserver, Shibboleth, etc.).
+
+### 3. Permissions
+Allow the web server to write to language files (required for the translation module):
+```bash
+sudo ./tools/allow-www-write
+```
+
+### 4. Database Installation
+Run the installation script to set up the database schema for all enabled modules.
+
+**Via CLI:**
+```bash
+./install-all
+```
+
+**Via Web:**
+Access `http://your-server/slx-admin/install.php` (No authentication required by default).
+
+### 5. Cron Job
+To handle periodic tasks (housekeeping, monitoring), add a crontab entry to run every 5 minutes:
+```cron
+*/5 * * * * php /path/to/slx-admin/api.php cron
+```
+Not crucial for development, especially when wiping the DB occasionally.
+
+## Entry Points
+- `index.php`: Main web interface.
+- `api.php`: API endpoint for certain web/AJAX requests and CLI operations.
+- `install.php`: Web-based installation and database migration tool.
+
+## Scripts & CLI Commands
+- `./install-all`: Shell script to iterate and install/update all enabled modules.
+- `php api.php cron`: Executes periodic tasks via the hook system.
+- `php api.php sysconfig --action rebuild`: Rebuilds the `config.tgz` modules.
+- `./pack.sh`: Packages the application into `slx-admin.tar.gz` for deployment.
+
+## Environment Variables
+The application primarily uses `config.php` for configuration.
+
+## Tests
+The project uses PHPUnit. Since it doesn't use Composer, it relies on a PHPUnit PHAR.
+
+### Running Tests
+1. Download a compatible `phpunit.phar` (e.g., 9.6):
+   ```bash
+   curl -L -o phpunit.phar https://phar.phpunit.de/phpunit-9.6.phar
+   chmod +x phpunit.phar
+   ```
+2. Run from the project root:
+   ```bash
+   ./phpunit.phar
+   ```
+
+Detailed testing information and instructions for using the SQLite test backend can be found in [tests/README.md](tests/README.md).
+
+## Project Structure
+- `api.php` / `index.php` / `install.php`: Main entry points.
+- `apis/`: Legacy API implementations (e.g., `cron`, `getconfig`).
+- `doc/`: Internal documentation on specific subsystems.
+- `inc/`: Core classes and utility functions (autoloaded).
+- `lang/`: Files defining a supported language.
+- `modules-available/`: Source directory for all available modules.
+- `modules/`: Enabled modules (symlinks to `modules-available/`).
+- `Mustache/`: Bundled Mustache template engine.
+- `script/` / `style/`: Global frontend assets.
+- `tests/`: PHPUnit test suite.
+- `tools/`: Administrative and utility scripts.