165 lines
4.9 KiB
Markdown
165 lines
4.9 KiB
Markdown
# 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/Raspbian
|
|
```
|
|
|
|
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 |