elpatron/octo-funnel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Activity

Initial commit: Tailscale Funnel plugin for OctoPrint with build documentation

Browse Source
This commit is contained in:
Markus F.J. Busche
2025-09-20 13:29:20 +02:00
commit 87f0792eb7
18 changed files with 1724 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
.qoder/quests/octoprint-tailscale-plugin.md Normal file
View File

@@ -0,0 +1,213 @@
# OctoPrint Tailscale Funnel Plugin Design Document
## 1. Overview
The OctoPrint Tailscale Funnel Plugin is designed to make the OctoPrint web interface publicly accessible via Tailscale Funnel. This plugin will enable users to securely access their OctoPrint instance from anywhere on the internet without needing to configure port forwarding, dynamic DNS, or deal with complex firewall settings.
### 1.1 Purpose
The primary purpose of this plugin is to provide a simple, secure way for OctoPrint users to access their 3D printer's web interface remotely using Tailscale's Funnel feature, which creates encrypted tunnels from the public internet to local services.
### 1.2 Scope
This plugin will:
- Integrate with the existing Tailscale installation on the system
- Provide a user interface within OctoPrint to enable/disable Funnel access
- Configure and manage Tailscale Funnel for the OctoPrint web service
- Display the public URL for accessing OctoPrint remotely
- Handle authentication and security considerations
## 2. Architecture
### 2.1 System Components
The plugin consists of the following components:
1. **Plugin Core**: The main plugin implementation that integrates with OctoPrint's plugin system
2. **Tailscale Interface**: Component that communicates with the Tailscale daemon via CLI
3. **Web UI**: Frontend elements that allow users to configure and monitor Funnel status
4. **Settings Management**: Component that stores and retrieves plugin configuration
5. **Status Monitor**: Background service that monitors the Funnel connection status
### 2.2 Component Interaction Diagram
```mermaid
graph TD
A[OctoPrint Web Interface] --> B[Plugin Core]
B --> C[Tailscale Interface]
B --> D[Web UI]
B --> E[Settings Management]
B --> F[Status Monitor]
C --> G[Tailscale Daemon]
D --> A
E --> B
F --> C
```
### 2.3 Plugin Integration Points
The plugin will integrate with OctoPrint through several mixin types:
- StartupPlugin: Initialize Tailscale integration on startup
- SettingsPlugin: Manage plugin configuration
- AssetPlugin: Provide custom JavaScript and CSS assets
- TemplatePlugin: Add UI elements to OctoPrint's interface
- BlueprintPlugin: Create custom API endpoints for plugin functionality
## 3. Plugin Features
### 3.1 Core Functionality
| Feature | Description |
|---------|-------------|
| Funnel Enable/Disable | Toggle Tailscale Funnel for OctoPrint web interface |
| Status Monitoring | Display current Funnel connection status |
| Public URL Display | Show the public URL for accessing OctoPrint |
| Configuration Management | Store and retrieve plugin settings |
### 3.2 User Interface
The plugin will add a new section to OctoPrint's settings panel with the following elements:
1. **Status Indicator**: Shows whether Funnel is currently enabled or disabled
2. **Enable/Disable Button**: Toggle to turn Funnel on or off
3. **Public URL Display**: Shows the public URL when Funnel is enabled
4. **Status Messages**: Displays current status and any error messages
### 3.3 Security Considerations
1. The plugin will require explicit user consent before enabling Funnel
2. All communication with Tailscale will be done through the local CLI
3. The plugin will not store any authentication credentials
4. Users will be warned about the security implications of making their printer accessible from the internet
## 4. Implementation Details
### 4.1 Plugin Structure
The plugin will follow a standard OctoPrint plugin structure with separate directories for Python code, static assets (JavaScript and CSS), templates, and documentation files.
### 4.2 Main Plugin Implementation
The main plugin class will implement several OctoPrint mixins:
- StartupPlugin: Initialize Tailscale integration on startup
- SettingsPlugin: Manage plugin configuration
- AssetPlugin: Provide custom JavaScript and CSS assets
- TemplatePlugin: Add UI elements to OctoPrint's interface
- BlueprintPlugin: Create custom API endpoints for plugin functionality
### 4.3 Tailscale Integration
The plugin will interact with Tailscale through subprocess calls to the Tailscale command-line tool to check status, enable/disable Funnel, and retrieve connection information.
### 4.4 Configuration Options
The plugin will store the following settings:
| Setting | Description | Default |
|---------|-------------|---------|
| enabled | Whether Funnel is enabled | False |
| port | Port to expose via Funnel | 80 |
| confirm_enable | Require confirmation before enabling | True |
## 5. API Endpoints
### 5.1 Custom API Routes
The plugin will expose the following API endpoints:
| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/plugin/tailscale_funnel/status | GET | Get current Funnel status |
| /api/plugin/tailscale_funnel/enable | POST | Enable Tailscale Funnel |
| /api/plugin/tailscale_funnel/disable | POST | Disable Tailscale Funnel |
### 5.2 API Response Format
All API responses will follow a standardized format that includes a status indicator, descriptive message, and data payload.
## 6. Frontend Implementation
### 6.1 JavaScript Components
The frontend will include a view model that:
- Fetches current Funnel status from the backend
- Provides methods to enable/disable Funnel
- Updates the UI with status information
- Handles user interactions
### 6.2 UI Elements
The settings panel will include:
- Toggle switch for enabling/disabling Funnel
- Read-only field displaying the public URL
- Status indicator showing connection state
- Action buttons for enabling/disabling
- Warning messages about security implications
## 7. Error Handling
### 7.1 Common Error Conditions
| Error | Cause | Handling |
|-------|-------|----------|
| Tailscale not installed | Missing tailscale command | Show installation instructions |
| Not connected to tailnet | Tailscale not logged in | Prompt user to login |
| Insufficient permissions | User can't run tailscale | Show permission error |
| Funnel not enabled | Admin setting | Show configuration instructions |
### 7.2 User Feedback
The plugin will provide clear feedback for all operations:
- Success messages when operations complete
- Error messages with troubleshooting suggestions
- Progress indicators during operations
- Status updates in real-time
## 8. Testing Strategy
### 8.1 Unit Tests
Unit tests will cover:
- Tailscale command execution
- Status parsing logic
- Configuration management
- API endpoint responses
### 8.2 Integration Tests
Integration tests will verify:
- Proper communication with Tailscale daemon
- Correct UI updates based on status changes
- Settings persistence
- Error handling scenarios
### 8.3 Manual Testing
Manual testing will validate:
- UI appearance and usability
- End-to-end enable/disable workflow
- Error message clarity
- Cross-platform compatibility
## 9. Deployment
### 9.1 Installation Requirements
- OctoPrint 1.3.0 or higher
- Tailscale installed and configured on the system
- Python 3.7 or higher
### 9.2 Installation Process
1. Install Tailscale on the system
2. Install the plugin through OctoPrint's plugin manager
3. Configure plugin settings in OctoPrint's settings panel
4. Enable Funnel through the plugin interface
### 9.3 Dependencies
The plugin will have minimal dependencies:
- Standard Python libraries for subprocess management
- OctoPrint's built-in plugin framework
- Tailscale CLI (installed separately by user)