COMP 5590 SENIOR FINAL PROJECT - Chemical Inventory System

LAMP Stack Template

This repo is a modified version of the SprintCube docker-compose-lamp repo.

The original README for that repo is a useful thing and can be found in this repo as README.original.md.

Setup Instructions

1. Database Configuration

Before starting the application, you need to configure your database settings:

1. Open initial.env and modify the following values:

   MYSQL_DATABASE=your_database_name
   MYSQL_USER=your_username
   MYSQL_PASSWORD=your_password
   

2. Copy these same values to www/database/database-defaults.php:

   return  [
       'host' => 'database',
       'port' =>  '3306',
       'dbname' => 'your_database_name', // Same as MYSQL_DATABASE
       'charset' => 'utf8mb4',
       'username' => 'your_username', // Same as MYSQL_USER
       'password' => 'your_password'  // Same as MYSQL_PASSWORD
   ];

3. Update the database name in /sql/createTables.sql:

   USE your_database_name; -- Same as MYSQL_DATABASE in initial.env

2. Initialize the Application

1. Run the starter script to set up your environment:

   ./start.sh

2. Install NPM dependencies for Tailwind CSS:

   npm install
   

3. Execute the SQL script to create your database tables:

   • Connect to the MySQL database using the Database Client extension
   • Open /sql/createTables.sql and run it to initialize all tables

3. Working with Tailwind CSS

When making UI changes, you'll need to have Tailwind watching for changes:

npx @tailwindcss/cli -i ./www/public/css/input.css -o ./www/public/css/output.css --watch

This command compiles your Tailwind CSS styles and automatically updates when you make changes.

LAMP Details

This particular LAMP stack consists of:

• Ubuntu Linux 20.04.6 LTS (Focal Fossa)
• Apache 2.4.59
• MySQL Server 8.4.0 / Client 8.0.37
• PHP 8.3

Features of the Chemical Inventory System

• Barcode-based inventory management for chemicals
• Mobile-responsive design for on-the-go inventory management
• Camera-based barcode scanning using QuaggaJS
• Inventory reconciliation tools
• Chemical location tracking
• Search and filtering functionality

VS Code Extension Details

The following extensions are installed the first time the Codespace is started:

• Code Spell Checker

  No excuses for misspellings now. You can add words to the .cspell.json file to have a custom dictionary for the repo.

• Database Client

  Allows you to do simple DB tasks in a light GUI without the need for an external tool.

• Live Server

  Provides instant feedback as you save your work, for both PHP and JS development. If you want it to work properly with PHP, you'll need the browser extension as well.

• PHP Debug

  Works with the installed Xdebug module to allow reasonably simple debugging of PHP code.

• PHP Intelephense

  A PHP code completer, linter, and formatter. Kinda.

• Prettier

  Opinionated code formatter for JS.

If you're using a desktop version of VS Code, you may see other extensions as well - it depends on whether you're synchronizing you're settings or not.

Using This Beastie

initial Codespace start

The very first time your Codespace starts up, you need to enter ./start.sh (the dot slash are necessary). This runs a script that does the gruntwork necessary to get everything up and running so that you can start coding. The whole process takes about 100 seconds to complete. Subsequent spinups will be significantly faster.

where to put your work

The document root for this particular LAMP stack is www/html/public, which is mapped to the www/public folder you see. With simple applications, you can dump all your files there. With more complex applications (like The Project and later labs), publicly accessible files should go in www/public, but you will put many other files one level "up", directly in www.

database connection

Use the included Database Client extension to create a connection to needed databases. Use the username and password you set in initial.env for your connection.

various tips

• If both ports (80 and 3306) aren't showing, open up a terminal and run these two commands in this order:

  1. docker compose down
  2. docker compose up -d

• If things are acting wonky, push all work that you don't want to lose, then try the following things - in order from least drastic to most drastic - stopping when things aren't wonky anymore:

  1. Ctrl+Shift+P > Reload Window
  2. Ctrl+Shift+P > Rebuild Container > Rebuild button (Not the Full Rebuild!)
  3. Delete the Codespace, then create a new one. (Don't forget to push beforehand!)

File Details

If you're interested, here's what the different files in this repo are for. If a file/directory isn't mentioned here, it's because I don't think it's important...or don't know what it's for. 😏

• .devcontainer/devcontainer.json

  Used primarily to install extensions.

• .vscode/launch.json

  Used when debugging a PHP page; forces use of Xdebug for debugging with the proper settings.

• .vscode/settings.json

  Sets a variety of Workspace settings. I'm opinionated, so if you want to tinker with this stuff, go right ahead!

• bin/

  Contains all the Dockerfiles for the PHP+Apache and mySQL/mariaDB containers. If you want to make tweaks with the installations of those services, pop open the files in the directory corresponding to the version you want to tweak and go to town.

• config/php/php.ini

  Need to have the Xdebug 3 settings here to use Xdebug properly.

• logs/apache2/*.log

  The log files for Apache are stored here. They're quite useful sometimes, especially for debugging (esp. error.log), so if you're having trouble understanding why a page isn't working, this can be a great place to check.

• .cscpelljson

  OK words for CSpell. Opinionated.

• .eslintrc.json

  Settings file for eslint. Opinionated.

• .prettierrc

  Settings file for Prettier. Opinionated.

• docker-compose.yml

  Stitches together php/apache and mysql containers. Modified from the original one provided by the SprintCube docker-compose-lamp repo - stripped out things we don't need for the course.

• initial.env

  Fills in all the variables for the docker-compose.yml files. Copied to .env as part of the start.sh script. Not meant to be put into version control.

• initial.htaccess

  Tells Apache to behave in useful ways, without needing to go digging around in Apache configuration files - which aren't accessible in this Codespace anyway. Copied to www/.htaccess as part of the start.sh script. Not meant to be put into version control.

• package.json

  Contains npm dependencies, particularly for Tailwind CSS.