Skip to content
A web application to support RoboJackets internal operations
PHP Vue HTML Shell
Branch: master
Clone or download
mergify Merge pull request #900 from RoboJackets/renovate/popper.js-1.x
Update dependency popper.js to v1.16.0
Latest commit 300fef8 Oct 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Don't cache node_modules, npm ci tosses it anyway Jun 9, 2019
.github/workflows Create GitHub action to automatically approve Renovate PRs Oct 6, 2019
.phan Fix phan config style Jun 4, 2019
app Remove use Oct 16, 2019
bootstrap Apply fixes from StyleCI Jun 4, 2019
config Add global weekly attendance report Oct 2, 2019
database Implement notification Sep 13, 2019
public
resources Add expired override card Oct 9, 2019
routes Merge branch 'master' into josh/nova-event-rsvp-link Oct 10, 2019
storage
.editorconfig Set up CircleCI Jun 5, 2019
.env.example Add global weekly attendance report Oct 2, 2019
.gitattributes Laravel Base Jun 1, 2017
.gitignore Ignore everything in the resources/views/vendor/nova folder but the u… Jun 9, 2019
.mergify.yml Delete head branch with mergify Oct 6, 2019
.shiftrc Clean up a few minor things Jun 5, 2019
.stickler.yml Tell Stickler to ignore the migrations directory Nov 19, 2018
.styleci.yml Switch to PHP-only config style Jul 21, 2018
CONTRIBUTING.md Fix typo in CONTRIBUTING.md Sep 10, 2019
LICENSE Fix license file with Copyright details Jul 29, 2019
README.md
SECURITY.md Update SECURITY.md Jul 11, 2019
artisan Shift core files Jul 6, 2018
composer.json Update dependency laravel/nova to v2.5.0 Oct 15, 2019
composer.lock Update dependency laravel/nova to v2.5.0 Oct 15, 2019
eslint.config Initial Stickler CI configuration Jul 7, 2018
package-lock.json Update dependency popper.js to v1.16.0 Oct 16, 2019
package.json Update dependency popper.js to v1.16.0 Oct 16, 2019
phpcs.xml CodeSniffer fixes Jun 7, 2019
phpmd.xml More PHPMD suppressions Jun 2, 2019
phpstan.neon Fix Socialite PHPStan rule Oct 6, 2019
post-deploy-hook.sh Move into the normal directory tree Sep 10, 2019
pre-deploy-hook.sh Fix join for dtt Jan 17, 2019
renovate.json Disable major updates in Renovate Oct 6, 2019
server.php
swagger.yaml feat: update swagger with new DuesTransactionController permissions, … Oct 1, 2018
webpack.mix.js Fix issue with Laravel Mix v4 Jun 8, 2019

README.md

Apiary

GitHub license Maintainability

Apiary is a tool for managing the membership and operations of RoboJackets, a student organization at Georgia Tech.

Motivation

This project grew out of frustration with the limitations imposed by Georgia Tech's student organization management system, OrgSync. We found that while it may be an excellent tool for managing small groups, it does not scale very well. To that end, we've tried to design an application that can better support our student organization at its current size, and grow and develop along with our group.

This project has been tailored to support the specific workflow of RoboJackets and is not currently built in a manner that would be easily adaptable to another organization. The decision to limit the scope of this project was made in light of the extensive approvals process to access the amount of student data we currently store. We believe it is unlikely that another org will be able and willing to navigate that process.

Getting Help

Getting Started with Local Development

If you've never worked with Laravel before, we recommend watching the Laravel from Scratch webcast series to get you up to speed quickly.

Apiary is written entirely in languages that can be run from any operating system; however, support is only provided for Linux environments. All instructions below assume that the user is running on a modern, Debian-based Linux distribution.

For an easier setup, you may wish to use Laravel Homestead. Homestead is a pre-packaged Vagrant box maintained by the Laravel creators designed for Laravel development. It takes care of most of the server configuration so that you can get up and running quickly. If you opt to use Homestead, all steps listed below should be performed inside the Vagrant box, rather than on the host machine.

Laravel Mix is used to compile browser assets. Currently, we're concatenating and minifying all of our JS and CSS. This step is also where we compile our SCSS into CSS. In your local dev environment, you should run npm run dev the first time you clone the repo and any time the assets change. Laravel Mix is a simple wrapper around webpack, which you really don't need to know about at this point. However, the fact that we use Webpack as a module bundler means that the process to reference JavaScript and CSS is a little bit different. It also means that if you add new CSS or JS files into the project, you need to reference them in webpack.mix.js to be compiled. See the relevant Laravel documentation for more details.

Most of the backend code lives under app/Http, with templates under resources/views and resources/assets/js, but you're encouraged to browse through the project tree to get a better feel of where different components live. The php artisan command can generate new classes for you in the correct locations automatically - run it with no parameters to see all the options.

Install dependencies

This is a pretty conventional Laravel project, so we recommend following the official guide to get your workspace set up. At minimum, you will need PHP 7.1.3+, composer, npm, and a MySQL 5.7+ compatible database available on your machine.

If you're using Homestead, this section is taken care of for you out of the box.

You can install all of the required php extensions with:

$ sudo apt install php php-common php-cli php-mysql php-mbstring php-json php-opcache php-xml php-bcmath php-curl php-gd php-zip

Database Encryption

Due to the nature of the data stored in certain tables in Apiary, some tables require encryption. This is implemented with MySQL's Keyring. For migrations to run successfully, you must also have a proper keyring set up in your development and production environments.

To enable the Keyring functionality, edit your my.cnf as follows, then restart MySQL:

[mysqld]
early-plugin-load=keyring_file.so

To check if the Keyring plugin was enabled successfully, run the following command from a MySQL command line.

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS
       FROM INFORMATION_SCHEMA.PLUGINS
       WHERE PLUGIN_NAME LIKE 'keyring%';
+--------------+---------------+
| PLUGIN_NAME  | PLUGIN_STATUS |
+--------------+---------------+
| keyring_file | ACTIVE        |
+--------------+---------------+

Further documentation about MySQL Keyring can be found in the MySQL documentation.

Install Redis

Apiary uses Redis for queueing jobs, with Laravel Horizon used to manage them. You should be able to just install Redis and the corresponding PHP extension. Once you get Apiary configured below, you can run php artisan horizon to process jobs.

Install Apiary

Clone the repository onto your local machine:

$ git clone https://github.com/RoboJackets/apiary.git

If you a member of RoboJackets, reach out in #apiary on Slack and ask for a copy of a mostly configured .env file.

Copy the example environment file to configure Apiary for local development:

$ cp .env.example .env

For a basic development environment, you'll need to modify the following settings:

Key Value
APP_URL Set to the hostname of your local dev environment, ex. apiary.test.
DB_* Set appropriately for your database.
MAIL_* Mailgun is the suggested mail driver, but you can easily configure Mailtrap or a local mail server referencing the Laravel documentation.
CAS_HOSTNAME FQDN of the CAS server to use, ex. login.gatech.edu
CAS_REAL_HOSTS Should match CAS_HOSTNAME
CAS_LOGOUT_URL CAS logout URL, ex. https://login.gatech.edu/cas/logout
CAS_MASQUERADE If set, bypasses the CAS authentication flow and authenticates as the specified username.
CAS_MASQUERADE_gtGTID GTID number for the masquerading user (90xxxxxxx)
CAS_MASQUERADE_email_primary Primary email address for the masquerading user
CAS_MASQUERADE_givenName Given Name (First Name) for the masquerading user
CAS_MASQUERADE_sn SN (Second/Last Name) for the masquerading user

Installing dependencies

$ composer install && npm install

Please note that we are using Laravel Nova for some admin pages. You will be prompted for credentials when running Composer if an update to Nova is required. Get in touch with us in #apiary when this happens.

You will need to run these commands again in the future if there are any changes to required packages.

Before Your First Run

Generate an application key (run this only once for initial setup.)

$ php artisan key:generate

Run database migrations to set up tables (run this for initial setup and when any new migrations are added later.)

$ php artisan migrate

Seed the database tables with base content (run this only once for initial setup.)

$ php artisan db:seed

Generate static assets (run this every time Vue or JS files are edited.)

$ npm run dev

Starting the Local Development Server

You can use php's built in development web server to easily test your application without needing to configure a production-ready web server, such as nginx or apache. To start this server:

$ php artisan serve

This is not necessary if you are using Homestead - you should use the configured hostname from Homestead.yaml instead, ex. apiary.test.

Tips for Development

npm run watch

Automatically rebuilds your front-end assets whenever the files change on disk. It's the same as running npm run dev. Some platforms will need npm run watch-poll to see changes to files, rather than just watch.

php artisan tinker

Tinker allows you to interact with Apiary on the command line including the Eloquent ORM, jobs, events, and more. A good introduction to Tinker can be found here.

Moving to Production

.env

There are a few additional changes needed to .env when moving to production.

Key Value
APP_NAME MyRoboJackets (or other as you see fit)
APP_ENV production
APP_DEBUG false
APP_LOG_LEVEL info (or other as you see fit)
APP_URL DNS hostname for production environment
GA_UA Google Analytics identifier, if desired
SQUARE_* Square API credentials (Get these from the Square Developer Dashboard)

Horizon Configuration

Review the Laravel documentation on deploying Horizon to a production environment.

Also be sure to set up a cron job to run scheduled tasks - Horizon uses this to keep track of statistics.

Security reporting

Any security issues with the Apiary code or any RoboJackets-managed Apiary deployment (*.robojackets.org) should be reported to apiary@robojackets.org. This will notify our development and operations teams and you should receive a response within 8 business hours Eastern Time.

You can’t perform that action at this time.