Installation Guides

Windows (XAMPP)

These steps are verified against a real Windows 10 VM running XAMPP.

1. Install XAMPP for Windows 8.2.12: download link (uninstall any older XAMPP first). The app requires PHP ^8.2 — 8.2, 8.3, and 8.4 all work; older versions will not run it.
2. Open C:\xampp\php\php.ini. Confirm these two lines have no ; in front (XAMPP 8.2.12 ships with both already enabled by default — just double-check):

   extension=openssl
   extension=imap

   If either has a ; in front, remove it and save.
3. Open XAMPP Control Panel, start Apache and MySQL.
4. Go to http://localhost/phpmyadmin and create a new database. Note its name.
5. Download the package and extract it to:

   C:\xampp\htdocs\msp-helpdesk

6. Open Command Prompt and run:

   cd C:\xampp\htdocs\msp-helpdesk
   copy .env.example .env
   C:\xampp\php\php.exe artisan key:generate

   This step is required before the first visit — without it, the site returns a 500 error instead of the setup wizard.
7. Edit C:\xampp\apache\conf\extra\httpd-vhosts.conf and add:

   <VirtualHost *:80>
       DocumentRoot "C:/xampp/htdocs/msp-helpdesk/public"
       ServerName localhost
       <Directory "C:/xampp/htdocs/msp-helpdesk/public">
           AllowOverride All
           Require all granted
       </Directory>
   </VirtualHost>

   Using localhost here (not a custom hostname) avoids needing to edit the Windows hosts file at all.
8. In XAMPP Control Panel, Stop then Start Apache to reload the config.
9. Visit http://localhost/ — the setup wizard loads automatically and shows a system requirements check (all green). Click Continue, then fill in the Database & Site Setup form:
   • Site URL: leave as http://localhost.
   • Database Host: leave as 127.0.0.1, Port: leave as 3306.
   • Database Name: the database you created in step 4.
   • Database Username: root — XAMPP's default MySQL user.
   • Database Password: leave blank — XAMPP's default root user has no password.
   Click Test Connection & Continue.

Linux (Ubuntu/Debian)

These steps are verified against a real Ubuntu 22.04 deployment.

1. Install PHP 8.2 (Ubuntu 22.04's default repo only has 8.1, so add the PPA first). PHP ^8.2 is required — 8.3 and 8.4 also work if you swap the version number below:

   sudo add-apt-repository ppa:ondrej/php -y
   sudo apt update
   sudo apt install php8.2-fpm php8.2-cli php8.2-mysql php8.2-mbstring \
     php8.2-xml php8.2-curl php8.2-zip php8.2-gd php8.2-bcmath php8.2-intl php8.2-imap -y

2. Install and start MySQL:

   sudo apt install mysql-server -y
   sudo systemctl enable mysql --now

   Create a database and user — replace choose-a-strong-password with your own password before running this:

   sudo mysql -e "CREATE DATABASE msphelpdesk; CREATE USER 'msphelpdesk'@'localhost' IDENTIFIED BY 'choose-a-strong-password'; GRANT ALL PRIVILEGES ON msphelpdesk.* TO 'msphelpdesk'@'localhost'; FLUSH PRIVILEGES;"

   Note the database name, username, and password — you'll enter them in the installer.
3. Install Nginx: sudo apt install nginx -y
4. Download and extract the package (the zip has no wrapping folder, so create the target directory first and unzip into it):

   sudo apt install curl unzip -y
   sudo mkdir -p /var/www/your-app-name
   cd /var/www/your-app-name
   sudo curl -LO https://updates.simpleit.nyc/releases/msp-helpdesk-1.0.45.zip
   sudo unzip msp-helpdesk-1.0.45.zip
   sudo rm msp-helpdesk-1.0.45.zip

   Check the download page for the current version number — the URL above will go stale as new versions are released.
5. Run these before the first visit — without them, the site returns a 500 error instead of the setup wizard (all files here are owned by root from the previous step, so these need sudo):

   cd /var/www/your-app-name
   sudo cp .env.example .env
   sudo php8.2 artisan key:generate

   Then set APP_URL to exactly how you'll access the site in a browser — the same host you'll put in server_name below, including http://. Replace your-domain-or-ip with your real IP or domain:

   sudo sed -i 's|^APP_URL=.*|APP_URL=http://your-domain-or-ip|' .env

   This matters: .env.example defaults APP_URL to http://localhost, and Laravel rejects any request whose Host header doesn't match it, with a 400 Bad Request. If you skip this and access the server by IP or a custom domain, you'll hit that error.
6. Set ownership so the web server (running as www-data) can write where it needs to:

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

   The last line matters: the setup wizard writes your database settings into .env directly from the browser (as www-data). If .env is still owned by root, that write silently fails and your settings won't actually save.
7. Create /etc/nginx/sites-available/your-app-name pointing at the package's public/ folder, with PHP-FPM handling .php requests. Run this whole block as one command — it writes the file for you, no text editor needed. Replace your-domain-or-ip with the same host you set as APP_URL above:

   sudo tee /etc/nginx/sites-available/your-app-name > /dev/null <<'EOF'
   server {
       listen 80;
       server_name your-domain-or-ip;
       root /var/www/your-app-name/public;
       index index.php;
       location / { try_files $uri $uri/ /index.php?$query_string; }
       location ~ \.php$ {
           fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
           fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
           include fastcgi_params;
       }
   }
   EOF

   Do not paste just the server { ... } block on its own — pasted straight into the shell without the sudo tee ... <<'EOF' wrapper, bash tries to run server, listen, etc. as commands and fails with a wall of "command not found" errors.
8. Enable the site and reload Nginx:

   sudo ln -s /etc/nginx/sites-available/your-app-name /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl reload nginx

9. If ufw is enabled on this server, allow HTTP first: sudo ufw allow 80/tcp (check with sudo ufw status — skip this if it says inactive).
10. Visit the site in a browser — the setup wizard loads and shows a system requirements check. Continue to the Database & Site Setup form and enter the Site URL (same value as APP_URL), Database Host 127.0.0.1, Port 3306, and the database name/username/password from step 2. Click Test Connection & Continue.

Namecheap, HostGator & Similar (cPanel) Hosting

1. Confirm your hosting plan supports PHP 8.2 — in cPanel, use Select PHP Version (sometimes called "MultiPHP Manager") to set it for your domain, and enable the extensions listed on the download page if any show as off.
2. Create a MySQL database and database user in cPanel's MySQL Database Wizard, and note the database name, username, and password it generates (shared hosts commonly prefix these with your account username automatically).
3. Upload the package via cPanel's File Manager (upload the zip, then use its built-in "Extract" option) or via FTP, into a folder outside your domain's public web root — e.g. a sibling folder next to public_html, not inside it.
4. The app's structure expects the web server to point at its public/ subfolder specifically, but most shared hosting points your domain straight at public_html. Two ways to handle this, in order of preference:
   • If you're installing to a subdomain or addon domain: most cPanel setups let you choose a custom document root when creating it — point it directly at the package's public folder.
   • If you must use the account's main public_html: move everything from inside the package's public folder up into public_html, then edit the two require lines in public_html/index.php so they point one directory further up to where the rest of the app (the vendor and bootstrap folders) actually lives.
5. Visit your domain in a browser and complete the installer using the database details from step 2.