Installation

This guide walks you through installing aldidsCoop from GitHub on your own machine. You can run the app on Laravel Herd (recommended, macOS/Windows), on XAMPP (Apache + MariaDB), or simply with PHP's built-in dev server.

#Requirements

#Step 1 — Clone the repository

git clone https://github.com/<owner>/<repo>.git
cd <repo>

Replace <owner>/<repo> with the project's actual GitHub address. If you already have a clone, pull the latest:

git pull

#Step 2 — Set up your PHP environment

Pick one of the following options.

#Option A — Laravel Herd (recommended)

Herd bundles PHP (with a per-site version switcher) and nginx, and gives every project a .test domain automatically.

1. Download and install Herd for macOS or Windows.
2. From the Herd dashboard, install PHP 8.3 (or 8.4/8.5) and make it the active version.
3. Install Composer and Node.js (Herd can install both for you).

You can now host the project as a site. Either place the cloned folder inside ~/Herd, or link an existing folder:

cd /path/to/<repo>
herd link coop
herd secure

#Option B — XAMPP

XAMPP provides Apache, MariaDB, and PHP in one installer for Windows, macOS, and Linux.

1. Install XAMPP.

2. Check the bundled PHP version — XAMPP often ships PHP 8.2 or older:

   bashCopy

   php -v
   

   If it's below 8.3, do one of the following:

   • Update XAMPP's PHP to 8.3+, or
   • Install PHP 8.3+ separately (e.g. from windows.php.net) and make sure your terminal's php resolves to it, and
   • Use XAMPP's Apache + MariaDB only, and run the app with php artisan serve.

3. Start the Apache and MySQL services from the XAMPP Control Panel.

4. (Optional) Create a virtual host so the app has its own domain. Edit C:\xampp\apache\conf\extra\httpd-vhosts.conf (or /Applications/XAMPP/xamppfiles/etc/extra/httpd-vhosts.conf on macOS):

   apacheCopy

   <VirtualHost *:80>
       ServerName coop.test
       DocumentRoot "C:/path/to/<repo>/public"
       <Directory "C:/path/to/<repo>/public">
           Options Indexes FollowSymLinks
           AllowOverride All
           Require all granted
       </Directory>
   </VirtualHost>
   

   Then add coop.test to your hosts file and restart Apache.

#Option C — Plain PHP + artisan serve

If you already have PHP 8.3+, Composer, and MySQL:

php -S localhost:8000 -t public

This works but offers no domain, HTTPS, or PHP version management — fine for quick experiments.

#Step 3 — Configure the environment

The composer script creates .env from .env.example, generates the app key, and handles the basics:

composer run setup

…or do it manually, step by step:

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

Edit .env and set the app URL and database to match your setup (see below).

#App URL

#Database

#MySQL / MariaDB

Set the connection to MySQL and fill in your credentials. With a default XAMPP/Herd install the values are:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=coop
DB_USERNAME=root
DB_PASSWORD=

Create the database first (via phpMyAdmin, Herd's database UI, or the MySQL client):

CREATE DATABASE coop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

#SQLite (quick start)

The included .env.example defaults to SQLite, which needs no server:

touch database/database.sqlite

Keep DB_CONNECTION=sqlite and leave the MySQL keys commented out.

#Step 4 — Install PHP & JavaScript dependencies

composer install
npm install

#Step 5 — Migrate and seed

php artisan migrate --seed

The seeders create the initial permissions/roles and starter data. Run php artisan storage:link so uploaded files can be served.

#Step 6 — Frontend assets

In production-style use, build the compiled assets:

npm run build

During development, instead keep the asset builder watching your files (leave this running in a separate terminal):

npm run dev

#Step 7 — Serve the app

#Step 8 — Verify

• Member dashboard — open /app and log in as a member.
• Management area — open /app/{tenant}/management (e.g. /app/PSN0000159/management) as an administrator.
• API — see the API Reference and authenticate with POST /api/auth/login.

#Testing

php artisan test

Tests run against an in-memory SQLite database (see phpunit.xml), so nothing needs to be added to MySQL for the suite to pass.

#Code style

vendor/bin/pint --dirty

#Troubleshooting