📖 Looking for karrio's legacy docs? Visit docs.karrio.io

Plugin Mounting

This guide explains how to mount external plugins and extensions into your Karrio Docker containers without rebuilding the images. This approach allows you to add custom functionality, carrier integrations, and business logic to Karrio while maintaining easy updates and deployments.

Overview

Karrio supports loading plugins from a mounted directory, enabling you to:

  • Add custom carrier integrations
  • Implement custom business logic
  • Integrate with external systems
  • Extend functionality without modifying core code
  • Deploy updates without rebuilding containers

Docker Compose Configuration

All the provided Docker Compose files include plugin mounting configuration. The plugin directory is mounted using the KARRIO_PLUGINS environment variable, which defaults to ./plugins if not specified.

Environment Variable

In your .env file
1KARRIO_PLUGINS=./plugins

Volume Mounting

In all Docker Compose configurations, you’ll find this volume mount:

1services:
2  api:
3    volumes:
4      - ${KARRIO_PLUGINS:-./plugins}:/karrio/plugins
5
6  worker:
7    volumes:
8      - ${KARRIO_PLUGINS:-./plugins}:/karrio/plugins

This configuration:

  • Mounts your local ./plugins directory to /karrio/plugins inside the container
  • Uses the KARRIO_PLUGINS environment variable if set, defaults to ./plugins
  • Makes plugins available to both the API server and background worker

Environment Variables

Configure plugin behavior using environment variables:

.env file
1KARRIO_PLUGINS=./plugins
2ENABLE_ALL_PLUGINS_BY_DEFAULT=True

Plugin Discovery and Loading

Karrio automatically discovers and loads plugins from the mounted directory. The plugin loading process:

  1. Discovery: Karrio scans /karrio/plugins for directories containing __init__.py
  2. Metadata: Reads plugin metadata from the METADATA variable
  3. Registration: Registers carriers, hooks, and services based on plugin type
  4. Initialization: Calls any initialization functions

Debugging Plugin Loading

Check if your plugins are being discovered:

View plugin loading logs
1docker-compose logs api | grep -i plugin
2
3# Check mounted plugins directory
4docker-compose exec api ls -la /karrio/plugins

Working with Existing Plugins

Installing Third-Party Plugins

  1. Download or clone the plugin to your plugins directory:
1cd plugins
2git clone https://github.com/example/karrio-custom-carrier.git custom_carrier

Best Practices

Security

  • Never commit secrets to your plugin code
  • Use environment variables for configuration
  • Validate all inputs in your plugin code
  • Sanitize data before external API calls

Performance

  • Cache expensive operations when possible
  • Use async operations for external API calls
  • Implement proper error handling and timeouts
  • Monitor resource usage of your plugins

Maintenance

  • Document your plugins thoroughly
  • Version your plugins properly
  • Test plugins before deployment
  • Keep dependencies up to date

Troubleshooting

Plugin Not Loading

  1. Check directory structure:
1docker-compose exec api find /karrio/plugins -name "*.py" | head -10
  1. Verify plugin metadata:
1docker-compose exec api python -c "
2import sys
3sys.path.append('/karrio/plugins')
4import my_plugin
5print(my_plugin.METADATA)
6"
  1. Check logs for errors:
1docker-compose logs api | grep -i error

Import Errors

  1. Verify Python path:
1docker-compose exec api python -c "import sys; print(sys.path)"
  1. Test imports manually:
1docker-compose exec api python -c "
2import sys
3sys.path.append('/karrio/plugins')
4try:
5    import my_plugin
6    print('Plugin imported successfully')
7except ImportError as e:
8    print(f'Import error: {e}')
9"

Permission Issues

If you encounter permission errors:

Fix ownership of plugins directory
1sudo chown -R $USER:$USER plugins/
2
3# Fix permissions
4chmod -R 755 plugins/