KwartzlabOS (kOS for short) is a member management and access control system originally designed for Kwartzlab Makerspace in Kitchener, Ontario.
Installation of Docker is required for the Docker setup development path. Please make sure both the docker and docker compose commands are available as they are used throughout setup.
NOTE: Different installation methods of Docker provide Docker Compose under different names. The following instructions reference Docker Compose as docker compose. If however your environment uses docker-compose, use that instead.
Begin by navigating to the directory where you want to clone kOS in your terminal, then run the following:
git clone https://github.com/kwartzlab/kos-base.gitThis will clone the repository from GitHub. Once cloned, navigate into the new directory:
cd kos-baseAs part of the repository we have an example environment file with a '.example' extension. Create a copy of this file with the example extension removed.
cp .env.example .envFiles provided in the repository are pre-configured to build Kos from the application source code previously cloned in the last step. The Kos Docker image is built in steps. Once each step completes, it's stored in a cache for later to speed up following builds.
To build the application image, run:
docker compose buildIf the build fails, the composer dependencies may be out of date. A short term solution is to delete the "composer.lock" file.
With the application image built, we can now stand up Kos with necessary dependencies. To run Kos, run:
docker compose upWhen Kos is ready, you should see a message in your console like this:
INFO Server running on [http://0.0.0.0:8000].
Open your browser and navigate to http://localhost:8000/. You should be presented with the login page. See details below to login.
To shut down Kos, go back to your terminal and press Control+C. You can remove resources once shut down with:
docker compose downOnce you've tested running Kos for the first time, you can optionally run Kos in the background instead. To run Kos in the background, run:
docker compose up -dphpunit is available within the container to test the built image. To unit test the image, run the following command in another terminal with the Kos container running.
docker compose exec app ./vendor/bin/phpunitphpMyAdmin is a PHP based web interface for MySQL databases. phpMyAdmin has been pre-configured to connect to and manage the Kos database for local debugging. To access the interface, navigate to http://localhost:8001/ with Kos running.
Commit hooks have been installed in this repository to perform checks prior to committing code back to the main code base. These hooks are installed and maintained into your local repository based on the configration maintained in this repository.
First install pre-commit, follow the steps outlined in the Pre-Commit docs https://pre-commit.com/. This is usually as simple as pip install pre-commit or brew install pre-commit.
Then install the hooks to your local repository by running pre-commit install from the base directory of the repository.
Once pre-commit is installed, every time you commit changes, you will see a sequence of checks run to verify that your changes meet our coding standards. If all checks pass, the changes will be committed. If the checks don't all pass, the commit will be cancelled and you will be prompted to refactor and resubmit. Many of the checks in the pre-commit configuration can and will perform automatic remediation of issues it finds. In this case, remediation is as simple as re-adding the effected files with modified changes and re-committing.
kOS requires the following external dependencies:
note: this has only been tested on ubuntu, your millage may very
php 8.0 or higher https://www.php.net/manual/en/install.php
sudo apt install phpenable php extensions mbstring xml curl mysql sqlite3
*nix - install packages (only tested on ubuntu, your mileage may very)
sudo apt install php-mbstring php-xml php-curl php-mysql php-sqlite3 php-gd php-xdebugwindows - modify php.ini file
php -r "phpinfo();" | grep php.iniextension=mbstringmysql 5.6 or higher https://dev.mysql.com/doc/mysql-installation-excerpt/5.7/en/
sudo apt install mysqlconsider running secure install if this is your first time installing
sudo mysql_secure_installation utility
sqlite3 https://www.sqlite.org/download.html
sudo apt install sqlite3Begin by navigating to the directory where you want to clone kOS in your terminal, then run the following:
git clone https://github.com/kwartzlab/kos-base.gitThis will clone the repository from GitHub. Once cloned, navigate into the new directory:
cd kos-baseAnd then install the package dependencies:
composer installThis will install everything needed to run the application.
note: if install fails it\'s most likely due to incorrect dependencies. Check the dependency section to see if anything was missed.
Start mysql as the root user (sudo mysql in *nix).
In the mysql prompt execute the following commands:
create database homestead;
CREATE USER 'homestead'@'localhost' IDENTIFIED BY 'secret';
GRANT all on `homestead`.* TO 'homestead'@'localhost';Next, copy and paste the .env.example file to a new .env file.
This will contain all the environment information your application needs, such as database credentials.
You will need to determine what these values need to be for your local setup yourself.
php artisan key:generateYou should now have a database without tables. The following command adds tables from the migrations up until now.
php artisan migrateYou now have everything you need for the application to run, but your database is woefully empty. You will need users, forms, etc. for the application to reasonably be used and tested locally. This will seed everything you need for the application to run locally, such as test users and submission forms. Run the following command:
php artisan db:seedOne user of every role will be created. (see Test Users section)
The phpunit.xml file is configured to run unit tests in an in-memory sqlite database. Most IDEs have a built-in solution for running tests, but if you choose to run tests through your CLI, you can run the entire test suite by running:
./vendor/bin/phpunitThis will run every test in the application. To run specific tests, you can filter by class name:
./vendor/bin/phpunit --filter=HttpsProtocolTestphp artisan serveThe following users are created for each role:
superuser-dev@kwartzlab.ca (Superuser role)bod-dev@kwartzlab.ca (Board of Directors role)kfa-dev@kwartzlab.ca (Key Fob Assigner role)bookkeeper-dev@kwartzlab.ca (Bookkeeper role)Every user is created with the password secret.
Set up a free development SMTP server. No emails will actually be sent!
Use the following to send the new member email to a specific address. Can be used in the production instance too.
php artisan email:memberapp --email=<members email> --recipient=<your email>Communication & key synchronization with kOS is done via an SSL-encrypted API allowing for unlimited custom hardware possibilities.
Yes I know this is janky, but it works for now.
cd /var/www/kos-base/
sudo -u www-data ./deploy.sh