Shipper Documentation
Welcome to the Shipper documentation! This comprehensive guide covers everything you need to know about deploying applications with Shipper.
Quick Links
- Main README - Overview and quick start guide
- Roadmap - Planned features and Ploi.io configurations not yet supported
- Configuration Guide - Complete shipper.yml configuration reference
- PR Previews - Set up preview environments for pull requests
- Sites Management - Managing site lifecycle and deployment
- Database Management - Database configuration and operations
- GitHub Actions - Automated deployments with GitHub Actions
- GitHub Action Usage - Using Shipper as a reusable GitHub Action
- Build System - Understanding the build and release process
- Strict Standards - Code quality and type safety standards
Getting Started
New to Shipper?
- Read the main README - Understand what Shipper is and its features
- Configuration Guide - Learn how to configure
shipper.yml - GitHub Actions Setup - Set up automated deployments
Common Tasks
Setting Up Deployments
- Configure shipper.yml - Define your projects and profiles
- Set up GitHub Actions workflows - Automate your deployments
- Configure PR previews - Enable preview environments
Managing Resources
- Create and manage sites - Site lifecycle management
- Configure databases - Database setup and management
- Deploy applications - Trigger deployments
Advanced Topics
- Use Shipper as a GitHub Action - Reusable action integration
- Understanding the build system - Binary building and releases
- Code quality standards - Type safety and best practices
Documentation Structure
Configuration
CONFIGURATION.md - Complete configuration guide
- Provider configuration (Ploi)
- Project setup
- Profile configuration
- Database configuration
- Environment variables
- Complete examples
- Best practices
PR Previews
PR_PREVIEWS.md - Preview deployment guide
- How preview deployments work
- Configuration for previews
- GitHub Actions workflows
- Domain strategy
- Database management
- Automatic cleanup
- Troubleshooting
Sites Management
SITES.md - Site lifecycle guide
- Site creation and updates
- Domain configuration
- Repository setup
- Deployment process
- Site commands (validate, plan, apply, destroy)
- Multiple projects
- Security and monitoring
Database Management
DATABASES.md - Database features guide
- Database configuration
- Variable interpolation
- Database lifecycle
- Password management
- Multiple databases
- Migrations
- Backups and restore
- Preview databases
GitHub Actions
GITHUB_ACTIONS.md - CI/CD automation guide
- Production deployments
- Staging deployments
- Preview deployments
- Cleanup workflows
- Workflow patterns
- Notifications
- Security best practices
GitHub Action
GITHUB_ACTION.md - Reusable action guide
- Using Shipper as a GitHub Action
- Action inputs and outputs
- Usage examples
- Version management
- Migration guide
- Troubleshooting
Build System
BUILD_SYSTEM.md - Build and release guide
- How the binary is built
- Box configuration
- Release process
- Distribution methods
- Reusable GitHub Action
- Version management
Strict Standards
STRICT_STANDARDS.md - Code quality guide
- Type safety rules
- PHPStan configuration
- Laravel Pint setup
- Testing with Pest
- Best practices
- Continuous integration
Key Features
Declarative Configuration
Define your entire deployment infrastructure in shipper.yml:
- Multiple projects
- Multiple environments (production, staging, preview)
- Database configurations
- Provider settings
Plan and Apply Workflow
Like infrastructure-as-code tools:
- Plan: Preview what changes will be made
- Apply: Execute the deployment
- Validate: Check configuration before deploying
Automatic Resource Management
Shipper handles:
- Site creation and configuration
- Database provisioning
- SSL certificates
- Environment variables
- Deployment tracking
GitHub Actions Integration
- Automated deployments on push
- PR preview environments
- Automatic cleanup
- Deployment status reporting
Support and Resources
Getting Help
- Issues: Report bugs or request features on GitHub Issues
- Discussions: Ask questions on GitHub Discussions
- Documentation: Browse this comprehensive documentation
Contributing
Contributions are welcome! See the main repository for contribution guidelines.
License
Shipper is open-source software licensed under the MIT license.
Common Workflows
Setting Up a New Project
- Create
shipper.ymlin your repository root - Configure provider credentials
- Define your project and profiles
- Add GitHub Actions workflows
- Set repository secrets (PLOI_API_KEY)
- Push to trigger first deployment
Example: See Configuration Guide
Adding PR Previews
- Add preview profile to project configuration
- Configure preview domain pattern
- Add preview database configuration
- Create preview deployment workflow
- Create cleanup workflow
- Test with a pull request
Example: See PR Previews Guide
Deploying Multiple Projects
- Define multiple projects in
shipper.yml - Use matrix strategy in workflows
- Deploy all projects or specific ones
- Monitor deployment status
Example: See Sites Management
Troubleshooting
Configuration Issues
Deployment Issues
GitHub Actions Issues
Best Practices
- Always validate configuration before deploying
- Use plan command to preview changes
- Enable PR previews for better testing
- Automate cleanup of preview environments
- Use environment variables for secrets
- Pin versions in production
- Monitor deployments for issues
- Backup databases before major changes
- Test in staging before production
- Document your setup for your team
Updates and Changelog
Check the releases page for:
- New features
- Bug fixes
- Breaking changes
- Migration guides
Next Steps
Choose your path:
New User? → Configuration Guide
Setting up CI/CD? → GitHub Actions Guide
Need PR Previews? → PR Previews Guide
Managing Databases? → Database Guide
Want to Contribute? → Strict Standards