Installation This guide will walk you through the process of installing Zuora Workflow Manager using Lando.
Prerequisites Make sure you have installed all system requirements before proceeding.
Step 1: Clone the repository Clone the GitHub repository to your local system:
git clone https://github.com/FrancoStino/zuora-workflows.git cd zuora-workflows
If you want to use the develop branch:
git clone -b develop https://github.com/FrancoStino/zuora-workflows.git cd zuora-workflows
Step 2: Start Lando Start the Lando environment. This command will automatically download and configure all necessary containers:
The first start may take several minutes to download the required Docker images.
Lando will automatically execute:
Start containers (PHP 8.4, MariaDB 11.4, Nginx, Redis)
Run composer install
Configure development environment
Expected output:
BOOMSHAKALAKA!!! Your app has started up correctly. Here are some vitals: NAME zuora-workflows LOCATION /path/to/zuora-workflows SERVICES appserver, database, cache APPSERVER URLS https://zuora-workflows.lndo.site
Step 3: Environment configuration Copy the environment variables example file:
Generate the Laravel application key:
lando artisan key:generate
Step 4: Database configuration Run migrations to create database tables:
Expected output:
Migration table created successfully. Migrating: 0001_01_01_000000_create_users_table Migrated: 0001_01_01_000000_create_users_table ...
If you receive database connection errors, make sure Lando is started correctly with lando info.
Step 5: Install frontend dependencies Install frontend dependencies with Yarn. You have two options:
Option 1: Use Yarn via Lando (recommended) This ensures all developers use the same Yarn version and works consistently across all operating systems:
Option 2: Use Yarn globally If you prefer to use Yarn installed locally on your system:
Compile frontend assets:
For development with hot-reload:
Step 6: Access the application Open your browser and navigate to:
https://zuora-workflows.lndo.site
Lando uses HTTPS with self-signed certificates. Your browser may show a security warning. Proceed anyway to access the application.
Step 7: Create administrator account On first access, you will be redirected to the setup page where you can create your administrator account:
Enter Name
Enter Email
Enter Password (minimum 8 characters)
Confirm password
Click Create Admin Account
Step 8: Start queue worker (optional) To process background jobs, start the queue worker:
This command is equivalent to:
lando artisan queue:work --verbose
Leave the queue worker running in a separate terminal window during development.
Step 9: Start scheduler (optional) To enable scheduled automatic synchronization:
This command is equivalent to:
lando artisan schedule:work
Verify installation Verify Lando services Check that all services are active:
Expected output:
{ "appserver" : { "type" : "php:8.4" , "urls" : [ "https://zuora-workflows.lndo.site" ] }, "database" : { "type" : "mariadb:11.4" , "creds" : { "database" : "zuora_workflows" , "user" : "zuora_workflows" , "password" : "zuora_workflows" } }, "cache" : { "type" : "redis:7.0" } }
Verify database Access the database to verify tables:
Run verification query:
SHOW TABLES; SELECT COUNT ( * ) FROM users;
Verify application Visit the application URL and verify:
✅ Login page loads correctly
✅ You can login with admin account
✅ Filament dashboard is accessible
✅ Menu items are visible
Useful Lando commands Application management lando start # Start containers lando stop # Stop containers lando restart # Restart containers lando rebuild # Rebuild containers lando destroy # Delete containers
Artisan commands lando artisan migrate # Run migrations lando artisan migrate:fresh # Recreate database lando artisan migrate:fresh --seed # Recreate and seed database lando artisan tinker # Interactive REPL
Database lando mariadb # Access database lando mariadb zuora_workflows # Access with specific database
Queue and scheduler lando queue # Start queue worker lando schedule # Start scheduler
Logs lando logs -f # View all logs lando logs -s appserver -f # PHP container logs
Yarn commands via Lando You can use Yarn through Lando to ensure consistent behavior across all team members and operating systems.
Benefits of using Lando Yarn:
Consistent version : All developers use the same Yarn versionCross-platform : Works identically on macOS, Windows, and LinuxIsolated : No need to install Yarn globally on your systemNo conflicts : Avoids version conflicts with other projects
Available Yarn commands: lando yarn install # Install frontend dependencies lando yarn run build # Compile assets for production lando yarn run dev # Development with hot-reload (HMR) lando yarn run preview # Preview production build
Usage example: # Install dependencies lando yarn install # Start development server with hot-reload lando yarn run dev # Build for production lando yarn run build
For new contributors, using lando yarn is recommended as it guarantees the same environment as other team members.
Composer lando composer install # Install PHP dependencies lando composer update # Update PHP dependencies
Troubleshooting Error: “Cannot connect to database” Verify that the database is started:
Restart Lando if necessary:
Error: “Permission denied” On Linux, you may need to adjust permissions:
sudo chown -R $USER : $USER .
Error: “Port already in use” If port 443 is already in use, modify .lando.yml:
proxy : appserver : - zuora-workflows.lndo.site:8443
Cache issues Clear application cache:
lando artisan cache:clear lando artisan config:clear lando artisan view:clear
Next steps Now that installation is complete, proceed with configuration:
Configuration Configure the application and Zuora credentials
