Project Resources

• OpenSGF: Join our weekly meetings!
• Code of Conduct: Please read before participating
• Discord: Click "Join" on OpenSGF website
• Project Documentation: Product Requirement Documents (PRDs)
• Project Management: Claim a PRD and/or update PRD status here

Project Setup

• Install PHP
• Install Composer
• Install Docker
  • For Mac: Docker Desktop | Orbstack
  • For Windows: Docker Desktop
  • For Linux: Docker Desktop
• Navigate to the project directory and run composer install
• Duplicate the .env.example: cp .env.example .env
• Generate a new APP_KEY: sail artisan key:generate. This will automatically update the .env file for the APP_KEY value.
• For running sail commands, by default, you are required to enter the full path to the executable in vendor/bin/sail. Most devs prefer to create an alias in their shell so they only have to type sail. Read the sail docs about configuring a sail alias. Further documentation will assume an alias exists in your shell.

Installing Current Project Dependencies

• All project contributors should run these commands every week to ensure your local project is using the current project dependencies.
  • composer install
  • npm install
  • npm run build

Updating the Project Dependencies

• The project maintainer should run these commands every week to ensure the project is using the latest dependencies, then merge composer.lock and package-lock.json along with any files that needed to be fixed.
  • composer update
  • npm update
  • npm run build
  • composer lint
  • composer analyse

Starting the Project

• Start the project: sail up -d
• Run DB migration scripts only on initial setup and after creating new migrations sail artisan migrate --seed
• Run the inertia frontend: npm run dev
• View the project in your browser at http://localhost
  • The URL port number is configured in the .env file as APP_PORT

Project Linting

• Navigate to the project directory and run composer lint

Project Static Analysis

• Navigate to the project directory and run composer analyse

Viewing and Generating Database Diagrams

The file ./database/schema.dbml can be opened with a tool such as dbdiagram.io. There are also e VS Code extensions such as DBML Live Preview that can view these.

To regenerate the file use the artisan command sail artisan dbml:generate

Shutting Down the Project

• To stop the containers run sail down

Resetting the Database

• To purge your MySQL database, run sail down -v, then sail up -d, then sail artisan migrate:fresh --seed. (⚠️ WARNING: This will purge EVERYTHING from your database! ⚠️)

Testing emails

• The default mail credentials in .env point to a mailpit docker container which captures all delivered emails. You can view these emails by visiting http://localhost:8025

Frontend Development

• Use shadcn components within resources/js/Components/ui when building pages
• Any new custom reusable components should be accompanied by a storybook story in the stories directory