Skip to content

README.md

Latest commit

 

History

History
195 lines (152 loc) · 6.92 KB

README.md

File metadata and controls

195 lines (152 loc) · 6.92 KB

Polydock Engine

⚠️ Warning: Experimental Project
Polydock Engine is currently in active development and has not yet reached a stable production release. This project should be considered experimental.

If you are interested in using Polydock Engine in a production setting, please contact Bryan Gruneberg (bryan@workshoporange.co) from Workshop Orange, one of the sponsoring organizations.

Polydock Engine is a Laravel-based application management and deployment platform that enables organizations to offer self-service trials and deployments of their applications on top of Lagoon platforms (such as amazee.io). While Lagoon empowers developers to use Kubernetes without deep technical knowledge, Polydock Engine focuses on enabling non-technical users to deploy and manage multiple instances of the same application through a user-friendly interface.

Implemented Features

Application Management

  • Multi-store support for organizing applications by region and organization
  • Public and private stores with marketplace visibility control
  • Trial availability flags for controlling which apps can be offered as trials
  • Automated trial lifecycle management with configurable email notifications
  • Customizable trial durations and notification schedules
  • Automatic trial expiration and cleanup

User Management

  • Group-based access control
  • Role-based permissions (Owner, Member)
  • Email-based user registration
  • Automatic group creation for new trial users

Trial Registration System

  • Remote registration API
  • Support for multiple registration types:
    • Standard trial requests
    • Unlisted region requests
    • Test/simulation modes for developing and testing registration workflows
  • Registration validation
  • Privacy policy and AUP acceptance tracking
  • Support for unclaimed app instances to be claimed by a user when registering

Trial Management System

  • Configurable trial durations
  • Automated email notifications:
    • Mid-trial status updates
    • One day remaining reminders
    • Trial completion notices
  • Customizable email templates with markdown support
  • Automatic trial expiration handling
  • Trial status tracking and monitoring

Webhook System

  • Store-level webhook configuration
  • Automatic retry with exponential backoff
  • Detailed webhook call tracking
  • Event-based notifications for:
    • Registration status changes
    • Trial provisioning updates
  • Robust error handling and logging

Deployment Integration

  • Integration with Lagoon deployment system
  • Region-specific deployment configuration
  • Project prefix management for multi-tenant deployments
  • Git-based deployment source control
  • App level configurable deployment and trial claim scripts scripts
  • App level configurable lagoon services and container definitions for running the scripts

Planned Features

Enhanced Trial Management

  • Usage quotas and limits
  • Trial extension workflows
  • Custom trial workflows

Advanced Monitoring

  • Trial usage analytics
  • Store performance metrics
  • Registration conversion tracking
  • Webhook reliability monitoring

Extended Integration

  • Additional deployment platform support
  • SSO integration options
  • Custom domain management
  • Automated DNS provisioning

Administrative Features

  • Advanced user management
  • Billing integration
  • Usage reporting
  • Enhanced audit logging

Technical Details

Technology Stack

Development Environment

This project uses Laravel Sail with Lagoon integration ("Sail on Lagoon") for local development and production deployment.

Prerequisites

Local Development Setup

  1. Clone the repository:
git clone https://github.com/freedomtech-hosting/polydock-engine.git
cd polydock-engine
  1. Install dependencies:
composer install
  1. Configure environment variables:
cp .env.example .env

(reconfigure the .env file as needed)

  1. Start the development server:
./vendor/bin/sail up

(use -d to run in detached mode)

  1. Run migrations:
./vendor/bin/sail artisan migrate

5.1 (optional) Run the seed command to create a default user:

./vendor/bin/sail artisan db:seed

(See DatabaseSeeder.php for details on the default users, groups, apps that are created)

  1. Access the application at http://localhost

Production Deployment

amazee.io kindly sponsors a production instance of Polydock Engine for development purposes. This respository is connected via webhook to the production instance and will automatically deploy changes when a push is made to the main branch, the dev branch, or the staging branch.

NB: The Polydock Enginge hosted for development purposes on amazee.io is only configured to deploy Polydock Applicaitons to a testing (non-production) Lagoon Kubernetes cluster.

For acceess to the production development environment, please contact Bryan Gruneberg (bryan@workshoporange.co) from Workshop Orange.

Queue Processing with Laravel Horizon

  • Dedicated queue workers for different job types
    • Default queue for general processing
    • Webhook queue for external notifications
    • Trial management queue for automated trial processes
  • Automatic scaling based on load
  • Configurable retry policies with exponential backoff
  • Real-time queue monitoring dashboard (see /horizon)
  • Job failure tracking and debugging
  • Environment-specific worker configurations defaults:
    • Production: Up to 10 concurrent processes
    • Local: 3 processes for development
    • Separate supervisor for webhook processing

Sponsoring Organizations

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Please ensure that you:

  • Follow our coding standards
  • Write tests for new features
  • Update documentation as needed
  • Follow the pull request process outlined in the contributing guide

License

This project is licensed under the MIT License - see the LICENSE.md file for details.