# Building the Tailscale Funnel Plugin This document describes how to build the Tailscale Funnel plugin for OctoPrint from source. ## Prerequisites Before building the plugin, ensure you have the following installed on your system: * Python 3.7 or higher * pip (Python package installer) * git (optional, for version control) ## Build Process ### 1. Clone the Repository If you haven't already, clone the repository: ```bash git clone https://gitea.elpatron.me/elpatron/octo-funnel.git cd octo-funnel ``` ### 2. Create a Virtual Environment It's recommended to use a virtual environment to isolate the build dependencies: ```bash python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` ### 3. Install Build Dependencies Install the required Python packages: ```bash pip install setuptools wheel octoprint ``` ### 4. Build the Plugin Navigate to the plugin directory and run the setup script: ```bash cd octoprint_tailscale_funnel python setup.py sdist bdist_wheel ``` This will create distribution files in the `dist/` directory: - A source distribution (tar.gz) - A wheel distribution (whl) ### 5. Create OctoPrint-Compatible Package OctoPrint's plugin manager expects a zip file with a specific naming convention. Create it by copying and renaming the tar.gz file: ```bash cp dist/octoprint_tailscale_funnel-*.tar.gz dist/OctoPrint-Tailscale-Funnel-*.zip ``` The resulting file `OctoPrint-Tailscale-Funnel-*.zip` can be uploaded to OctoPrint through the plugin manager. ## Directory Structure After a successful build, the project directory will contain: ``` octoprint_tailscale_funnel/ ├── dist/ │ ├── octoprint_tailscale_funnel-.tar.gz │ ├── octoprint_tailscale_funnel--py3-none-any.whl │ └── OctoPrint-Tailscale-Funnel-.zip ├── build/ │ └── ... (temporary build files) ├── OctoPrint_Tailscale_Funnel.egg-info/ │ └── ... (package metadata) └── ... (source files) ``` ## Troubleshooting ### ImportError: No module named 'octoprint_setuptools' If you encounter this error, make sure you've installed OctoPrint in your virtual environment: ```bash pip install octoprint ``` ### Permission Errors If you encounter permission errors during installation, you may need to use the `--user` flag: ```bash pip install --user setuptools wheel octoprint ``` ### Package Directory Issues If you see warnings about package directories, ensure the setup.py file is correctly configured with the appropriate package structure. ## Cleaning Up To clean up build artifacts: ```bash rm -rf build/ dist/ *.egg-info/ ``` This will remove all generated files and allow you to rebuild from scratch. ## Versioning The plugin version is defined in `setup.py`. To release a new version: 1. Update the `plugin_version` variable in `setup.py` 2. Rebuild the plugin following the steps above 3. The new version will be reflected in the generated filenames ## Additional Resources * [OctoPrint Plugin Development Documentation](https://docs.octoprint.org/en/master/plugins/getting-started.html) * [Tailscale Documentation](https://tailscale.com/kb/) * [Python Packaging Documentation](https://packaging.python.org/) ## Project Structure The project follows a standard structure: ``` . ├── README.md # Project overview and usage instructions ├── .gitignore # Files and directories to exclude from Git ├── octoprint_tailscale_funnel/ # Plugin source code │ ├── BUILDING.md # This document │ ├── setup.py # Plugin setup and metadata │ ├── __init__.py # Main plugin implementation │ ├── tailscale_interface.py # Tailscale command interface │ ├── status_monitor.py # Status monitoring functionality │ ├── requirements.txt # Python dependencies │ ├── MANIFEST.in # Files to include in distribution │ ├── static/ # Static assets (CSS, JS) │ ├── templates/ # HTML templates │ └── tests/ # Unit tests ```