# 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.bat
```

### 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

First, install the zip utility if not already installed:
```bash
sudo apt install zip  # On Ubuntu/Debian
```

Then create a proper zip file:
```bash
# 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:

```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
├── 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