octo-funnel/octoprint_tailscale_funnel/BUILDING.md

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:

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:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate.bat

3. Install Build Dependencies

Install the required Python packages:

pip install setuptools wheel octoprint

4. Build the Plugin

Navigate to the plugin directory and run the setup script:

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

First, install the zip utility if not already installed:

sudo apt install zip  # On Ubuntu/Debian/Raspbian

Then create a proper zip file:

# Remove any existing zip file
rm -f dist/OctoPrint-Tailscale-Funnel-*.zip

# Extract the tar.gz file and create a proper zip archive
mkdir -p tmp_extract
tar -xzf dist/octoprint_tailscale_funnel-*.tar.gz -C tmp_extract
cd tmp_extract/octoprint_tailscale_funnel-*
zip -r ../../dist/OctoPrint-Tailscale-Funnel-0.1.0.zip .
cd ../..
rm -rf tmp_extract

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-<version>.tar.gz
│   ├── octoprint_tailscale_funnel-<version>-py3-none-any.whl
│   └── OctoPrint-Tailscale-Funnel-<version>.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:

pip install octoprint

Permission Errors

If you encounter permission errors during installation, you may need to use the --user flag:

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:

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
• Tailscale Documentation
• Python Packaging Documentation

Project Structure

The project follows a standard structure:

.
├── README.md                    # Project overview and usage instructions
├── LICENSE                      # License file
├── .gitignore                   # Files and directories to exclude from Git
├── octoprint_tailscale_funnel/  # Plugin source code
│   ├── BUILDING.md              # This document
│   ├── README.md                # Plugin-specific README
│   ├── LICENSE                  # Plugin license (copy of root LICENSE)
│   ├── setup.py                 # Plugin setup and metadata
│   ├── requirements.txt         # Python dependencies
│   ├── MANIFEST.in              # Files to include in distribution
│   ├── octoprint_tailscale_funnel/  # Plugin Python package
│   │   ├── __init__.py          # Main plugin implementation
│   │   ├── tailscale_interface.py   # Tailscale command interface
│   │   └── status_monitor.py    # Status monitoring functionality
│   ├── static/                  # Static assets (CSS, JS)
│   │   ├── css/                 # CSS stylesheets
│   │   ├── js/                  # JavaScript files
│   │   └── less/                # LESS stylesheets
│   ├── templates/               # HTML templates
│   └── tests/                   # Unit tests