mirror/api

mirror of https://github.com/unraid/api.git synced 2026-01-01 06:01:18 -06:00

Files

Pujit Mehrotra bb9b539732 chore: fix local plugin builds & docs (#1851 )

Raised by [MitchellThompkins](https://github.com/MitchellThompkins) in
#1848

- Documents how to use Docker to build a local Connect plugin
- Local Plugin flow will now build workspace packages before proceeding
with plugin infra + build
- Removes recommendation to run `pnpm build:watch` from root, as this
race conditions and build cache issues.
- Makes `pnpm dev` from root parallel, preventing servers from blocking
each other.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Updated development workflow documentation to emphasize Docker-based
plugin builds
* Restructured development modes into three workflows: local Docker
builds, direct deployment, and development servers
  * Updated build and deployment instructions

* **Chores**
  * Modified dev script for parallel execution
  * Refactored build scripts with improved dependency handling

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2025-12-18 16:33:37 -05:00

2.1 KiB

Raw Blame History

Unraid Plugin Builder

Tool for building and testing Unraid plugins locally as well as packaging them for deployment.

Development Workflow

1. Build the Plugin

Note: Building the plugin requires Docker.

Once your changes are ready, build the plugin package:

# Start Docker container (builds dependencies automatically)
pnpm run docker:build-and-run

# Inside the container, build the plugin
pnpm build

This will:

Build the API release (api/deploy/release/)
Build the web standalone components (web/dist/)
Start Docker container with HTTP server on port 5858
Build the plugin package (when you run pnpm build)

The plugin files will be created in ./deploy/ and served automatically.

2. Install on Unraid

Install the plugin on your Unraid development machine by visiting:

http://SERVER_NAME.local/Plugins

Then paste the following URL into the Unraid Plugins page:

http://YOUR_LOCAL_DEV_MACHINE_IP:5858/plugins/local/dynamix.unraid.net.plg

Replace SERVER_NAME with your development machine's hostname.

Development Tips

The HTTP server includes CORS headers for local development
Check the Unraid system log for plugin installation issues

Environment Setup

Initialize environment:
```
pnpm run env:init
```
Validate environment:
```
pnpm run env:validate
```

Available Commands

Build Commands

build - Build the plugin package (run inside Docker container)
docker:build - Build the Docker container
docker:run - Run the builder in Docker
docker:build-and-run - Build dependencies and start Docker container

Environment Commands

env:init - Create initial .env file
env:validate - Validate environment setup
env:clean - Remove .env file

Troubleshooting

Watch not updating files
- Check that source directories exist
- Verify file permissions
Build failures
- Ensure .env file exists
- Check Docker setup if using containerized build
- Verify source files are present
Installation issues
- Confirm http-server is running
- Check your local IP is correct
- Verify plugin file permissions

2.1 KiB Raw Blame History