This code is under active development and not stable for production use! If you're feeling super brave, then by all means give it a try. But if you just want to use MonkeyPod, you should probably go with the hosted version.
MonkeyPod Application Scaffolding
Open-source, laravel-based application for nonprofit accounting and other management tools.
Here be dragons!
Setting up and running this application requires extensive experience with Laravel along with general technical expertise. This is not a one-click install-and-run situation like Wordpress. This code provides a foundation to build on for your own application, but is not plug-n-play. If those sentences are intimidating rather than exciting, then you'll be better off using the hosted service, which takes 5-minutes to set up and includes lots of additional bells and whistles.
For the purposes of this checklist we'll assume you're using GitHub for source control, but these instructions could easily be adapted if you prefer something else. We'll also assume that you're using Laravel Homestead or another server setup that is fully equipped and configured for Laravel. Steps like installing a database and configuring nginx are beyond the scope of these instructions.
Setup a new Git repository for your application. (We'll call it "myapp" here.)
Pull down the app from GitHub:
git init myapp
cd myapp && git pull email@example.com:monkeypod-io/app.git
Set your project as the remote origin:
git remote add origin firstname.lastname@example.org:[YourUser]/myapp.git
Set the official distribution as the upstream remote (this will allow you to pull in changes from future versions):
git remote add upstream email@example.com:monkeypod-io/app.git
Install composer dependencies:
Install npm dependencies:
npm run [dev|prod]
Create .env file:
cp .env.example .env
Generate application key
php artisan key:generate
Configure database environment variables in .env
Configure your organization settings:
Publish vendor assets (minimally migrations, but anything else you'd like to customize):
php artisan vendor:publish
Migrate and seed the database:
php artisan migrate && php artisan db:seed
Sign up for 3rd-party services on which MonkeyPod relies and configure .env variables accordingly:
Configure remaining environment variables in .env
Create an initial admin user account:
php artisan make:admin
Customizing or Extending MonkeyPod
The strongly recommended way to extend or customize MonkeyPod is through the use of modules. This will keep your changes isolated and make it easier to stay up to date with changes in the main app. Speaking of which...
MonkeyPod modules extend the basic functionality with additional capabilities. Current official modules include:
- Blueprint (budgeting)
- Clockwork (recurring transactions)
- Eyewitness (CRM action feeds)
- Gutenberg (printing)
- Pigeonhole (customizable CRM attributes)
- Pipeline (customizable CRM sales funnels, a.k.a. "moves management")
- Spidersense (relationship/connection tracking)
More official modules are in the works. In the meantime, you can always create your own, in which case we'd love to hear about it!
How Modules Work
MonkeyPod's module system is built on the excellent laravel-modules package by Nicolas Widart. Before attempting to develop or modify a MonkeyPod module, you should have a basic understanding of how laravel-modules works by default. However, MonkeyPod uses a few of its own conventions and adds some additional features. Mostly these relate to adding or extending core functionality.
By using basic laravel-modules functionality, MonkeyPod modules can add:
- models and associated policies, observers, validators, etc.
- routes, controllers, and related Http classes
- views and related assets
- tabs to qualified existing views
MonkeyPod-specific module behavior goes a bit further:
MonkeyPod relies on several different application configuration files, all of which can be extended by modules. These include:
- monkeypod-actions — Actions that apply to specific models, such as "Edit", or "Delete", or "Re-activate"
- monkeypod-navigation — The application's main navigation menus
- monkeypod-permissions — Default role-based permissions for use by policy authorizations
- monkeypod-tabs ‐ Tabbed-views
- monkeypod-validation — Model-level validation rules and messages
MonkeyPod modules may define their own actions.php, permissions.php, tabs.php, and validation.php config files, which will be merged recursively with the application's configuration. This allow modules to inject content and behaviors into core application logic without having to touch any code outside the module itself. To add additional navigation menus, you can edit the monkeypod-navigation.php file and reference whatever additional navigation classes you like.
Deeper Modification of Core Behavior
Unfortunately, it isn't always possible to meet a module's requirements through configuration alone. Sometimes we
need to extend or supplement the capabilities of a MonkeyPod/Core model, for example. This should be done sparingly and
with caution, as it introduces the potential for conflicts and confusing, unmaintainable code. That caveat aside,
the preferred mechanism for addressing this situation is a series of "ExtendsXYZ" traits that live in the
app\Models\Concerns\Extended directory. Modules may include their own traits, which must be manually added
to the relevant "extender traits" as part of the installation process.
NOTE: Future versions of MonkeyPod will likely abandon this convention in favor of decorators or another cleaner approach.
When you have a half-dozen modules all trying to cohabitate peacefully, it can be difficult to keep track of overlapping dependencies. MonkeyPod uses semantic version (with its own twist) to try to bring some order to this chaos.
Pre 1.0 Versions
Any versions in the 0.X.Y range should be considered unstable and under active development. Generally speaking, if there is a release number at all, then someone is using the code somewhere. But especially at the lower ends of this version range, you should assume that the code is liable to change at any time, including basic APIs, interfaces, etc. If you are using pre-1.0 MonkeyPod code, make sure you have sufficient test coverage to spot any breakages before they are deployed.
Starting at 1.0.0, MonkeyPod code should be considered relatively stable. We aim to follow semantic versioning conventions, whereby bugfixes bump the patch number, new features bump the minor number, and breaking changes bump the major number.
MonkeyPod departs from strict semantic versioning, however, in the interest of making it easier to keep track of inter-module compatability. To that end, module developers should make sure that all releases in a particular major version range should be compatible with the monkeypod/app and monkeypod/core releases in the same major version range. If this principle is respected, then cross-module compatability should not generally be an issue, since modules are designed to be totally isolated from each other.