mirror of
https://github.com/unraid/api.git
synced 2026-01-04 07:29:48 -06:00
bb9b539732
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 -->
93 lines
2.1 KiB
Markdown
93 lines
2.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# Start Docker container (builds dependencies automatically)
|
|
pnpm run docker:build-and-run
|
|
|
|
# Inside the container, build the plugin
|
|
pnpm build
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Build the API release (`api/deploy/release/`)
|
|
2. Build the web standalone components (`web/dist/`)
|
|
3. Start Docker container with HTTP server on port 5858
|
|
4. 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
|
|
|
|
1. Initialize environment:
|
|
|
|
```bash
|
|
pnpm run env:init
|
|
```
|
|
|
|
2. Validate environment:
|
|
|
|
```bash
|
|
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
|
|
|
|
1. **Watch not updating files**
|
|
|
|
- Check that source directories exist
|
|
- Verify file permissions
|
|
|
|
2. **Build failures**
|
|
|
|
- Ensure .env file exists
|
|
- Check Docker setup if using containerized build
|
|
- Verify source files are present
|
|
|
|
3. **Installation issues**
|
|
- Confirm http-server is running
|
|
- Check your local IP is correct
|
|
- Verify plugin file permissions
|