Hello! Thanks for visiting! mirrorctl is still a young project, and the documentation is still a work-in-progress.
Guide
Tutorial
Next Steps

Next Steps

Congratulations! You’ve completed the mirrorctl tutorial and learned how to create, secure, and manage Debian repository mirrors. This page provides guidance on where to go next.

What You’ve Learned

Through this tutorial, you’ve covered:

  • Creating and configuring repository mirrors
  • Working with snapshots for versioning and rollback
  • Implementing a staging-to-production workflow
  • Expanding mirrors across architectures, suites, and sections
  • Securing mirrors with PGP and TLS verification
  • Performing common maintenance operations
  • Troubleshooting issues and monitoring mirror health

Advanced Topics

Ready to go deeper? Explore these advanced topics:

High Availability Mirrors

Set up redundant mirror infrastructure:

  • Configure multiple mirror servers with load balancing
  • Use rsync or snapshot replication between mirror servers
  • Implement health checks and automatic failover
  • Serve mirrors via CDN for global distribution

Custom Snapshot Workflows

Develop sophisticated snapshot strategies:

  • Create named snapshots for releases (e.g., “2025-q1-release”)
  • Maintain long-term retention snapshots for compliance
  • Implement automated testing before promotion
  • Use snapshots for multiple staging environments (dev, qa, prod)

Package Filtering

Fine-tune what gets mirrored:

  • Use exclude_patterns to filter out unwanted packages
  • Implement keep_versions policies for space optimization
  • Create specialized mirrors for specific use cases
  • Combine filters with partial architecture mirroring

Web Server Configuration

Optimize mirror serving:

  • Configure Nginx or Apache to serve mirrors efficiently
  • Enable HTTP/2 for better performance
  • Implement caching headers for client efficiency
  • Set up HTTPS with Let’s Encrypt for secure access
  • Configure directory listings and index files

Integration with Configuration Management

Automate mirror deployment:

  • Deploy mirrorctl with Ansible, Puppet, or Chef
  • Template configuration files for different environments
  • Automate PGP key distribution and updates
  • Manage mirror infrastructure as code

Documentation References

Dive deeper into specific topics:

Configuration Reference

Command Reference

How-To Guides

Explore task-oriented guides:

  • How-Tos - Practical guides for specific tasks

Production Deployment Considerations

Before deploying to production, consider:

Infrastructure Planning

  • Disk space: Plan for 2-3x repository size for snapshots and growth
  • Network bandwidth: Ensure sufficient bandwidth for syncs and client access
  • Server resources: Allocate appropriate CPU/RAM for sync operations
  • Backup strategy: Backup configuration files and critical snapshots

Security Hardening

  • File permissions: Restrict mirror directory permissions appropriately
  • Firewall rules: Limit inbound access to HTTP/HTTPS ports only
  • SELinux/AppArmor: Configure mandatory access controls if applicable
  • Update policies: Establish procedures for updating mirrorctl and keys

Monitoring and Alerting

  • Sync success monitoring: Alert on failed syncs
  • Disk space alerts: Warning before space runs out
  • Performance monitoring: Track sync duration and bandwidth
  • Security alerts: Monitor for verification failures

Documentation

Document your mirror infrastructure:

  • Configuration rationale and decisions
  • Sync schedules and maintenance windows
  • Rollback procedures and contact information
  • Disaster recovery plans

Common Use Cases

Corporate Internal Mirror

Organizations often maintain internal mirrors for:

  • Reduced external bandwidth usage
  • Faster package installation across the fleet
  • Consistent package versions across environments
  • Offline or air-gapped infrastructure support

Key features to use:

  • Staging workflow for tested updates
  • Snapshot retention for rollback
  • PGP and TLS verification for security
  • Scheduled syncs during maintenance windows

Development Mirror

Development teams use mirrors for:

  • Reproducible build environments
  • Pinned package versions
  • Custom package repositories
  • Testing new packages before deployment

Key features to use:

  • Named snapshots for releases
  • Package filtering to reduce size
  • Multiple mirrors (stable, testing, experimental)
  • Integration with CI/CD pipelines

Edge Location Mirror

Edge deployments benefit from local mirrors:

  • Low-latency package access
  • Reduced WAN traffic
  • Continued operation during network outages
  • Support for bandwidth-constrained locations

Key features to use:

  • Minimal architecture/section mirroring
  • Periodic sync from central mirror
  • Snapshot replication for consistency
  • Automated health monitoring

Example Production Configurations

Complete Production Setup

Here’s a full production configuration example:

# /etc/mirrorctl/mirror.toml
# Production mirror configuration

# Base directory for all mirrors
dir = "/var/www/apt/"

# Global TLS security settings
[tls]
min_version = "1.2"
insecure_skip_verify = false

# Snapshot configuration
[snapshot]
path = "/var/lib/mirrorctl/snapshots"
default_name_format = "2006-01-02T15-04-05Z"

[snapshot.prune]
keep_last = 10
keep_within = "60d"

# Logging
[log]
level = "info"
format = "json"

# Ubuntu main repository
[mirrors.ubuntu]
url = "https://archive.ubuntu.com/ubuntu/"
suites = ["noble", "jammy", "focal"]
sections = ["main", "universe", "restricted", "multiverse"]
architectures = ["amd64", "arm64"]
pgp_key_path = "/etc/mirrorctl/keys/ubuntu-archive-keyring.gpg"
publish_to_staging = true

# Ubuntu security repository
[mirrors.ubuntu-security]
url = "https://security.ubuntu.com/ubuntu/"
suites = ["noble-security", "jammy-security", "focal-security"]
sections = ["main", "universe", "restricted", "multiverse"]
architectures = ["amd64", "arm64"]
pgp_key_path = "/etc/mirrorctl/keys/ubuntu-archive-keyring.gpg"
publish_to_staging = true

# Ubuntu updates repository
[mirrors.ubuntu-updates]
url = "https://archive.ubuntu.com/ubuntu/"
suites = ["noble-updates", "jammy-updates", "focal-updates"]
sections = ["main", "universe", "restricted", "multiverse"]
architectures = ["amd64", "arm64"]
pgp_key_path = "/etc/mirrorctl/keys/ubuntu-archive-keyring.gpg"
publish_to_staging = true

Community and Support

Getting Help

If you encounter issues or have questions:

Contributing

mirrorctl is open source. Contribute by:

  • Reporting bugs and issues
  • Suggesting features and improvements
  • Contributing code and documentation
  • Sharing your use cases and configurations

Staying Updated

Keep up with mirrorctl developments:

  • Watch the GitHub repository for releases
  • Review Release Notes for new features
  • Subscribe to security advisories
  • Monitor the blog for announcements

Final Thoughts

You now have a solid foundation for using mirrorctl. The key to successful mirror management is:

  1. Start simple - Begin with minimal configuration and expand as needed
  2. Test thoroughly - Use staging before promoting to production
  3. Monitor actively - Track sync health and disk usage
  4. Document everything - Record your configuration decisions and procedures
  5. Automate wisely - Schedule syncs and monitoring, but test automation first

Thank you for completing the mirrorctl tutorial. Happy mirroring!

Ready to dive deeper? Explore the Reference Documentation or How-To Guides for advanced topics.

Common Operations