Skip to content

Commit 30dfdec

Browse files
mstrhakrmstrhakr
committed
feat: add distribution topics for Community Applications, Hosting, and Support Resources
1 parent a9fcc52 commit 30dfdec

3 files changed

Lines changed: 187 additions & 3 deletions

File tree

‎docs/distribution/hosting.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
layout: default
3+
title: Hosting Your Plugin
4+
parent: Distribution
5+
nav_order: 2
6+
---
7+
8+
# Hosting Your Plugin
9+
10+
Where and how to host your plugin files for distribution.
11+
12+
## Recommended: GitHub
13+
14+
GitHub is the most popular choice for hosting Unraid® plugins:
15+
16+
### Advantages
17+
18+
- **Free hosting** for public repositories
19+
- **Releases** feature for versioned downloads
20+
- **Raw file URLs** work directly with the Plugin Manager
21+
- **Version control** for your source code
22+
- **Issue tracking** for bug reports
23+
24+
### Setting Up GitHub Hosting
25+
26+
1. Create a public repository for your plugin
27+
2. Include your PLG file in the repository root
28+
3. Use GitHub Releases for versioned packages
29+
30+
### URL Structure
31+
32+
For raw file access, use:
33+
```
34+
https://raw.githubusercontent.com/USERNAME/REPO/BRANCH/filename.plg
35+
```
36+
37+
For releases:
38+
```
39+
https://github.com/USERNAME/REPO/releases/download/TAG/filename.txz
40+
```
41+
42+
## Alternative Hosting Options
43+
44+
### GitLab
45+
46+
Similar to GitHub with free public repositories and raw file access.
47+
48+
### Self-Hosted
49+
50+
You can host files on your own web server, but ensure:
51+
- HTTPS is available (recommended)
52+
- Files are publicly accessible
53+
- URLs are stable and won't change
54+
55+
## PLG File URL Requirements
56+
57+
Your PLG file URL must:
58+
- Be publicly accessible (no authentication)
59+
- Return the raw file content (not an HTML page)
60+
- Be stable for update checking
61+
62+
## Package Hosting
63+
64+
For your TXZ packages referenced in the PLG file:
65+
66+
```xml
67+
<FILE Name="/boot/config/plugins/&name;/&name;-&version;.txz" Run="upgradepkg --install-new">
68+
<URL>&gitURL;/releases/download/&version;/&name;-&version;.txz</URL>
69+
</FILE>
70+
```
71+
72+
Using GitHub Releases ensures:
73+
- Version-specific URLs that don't change
74+
- Download statistics
75+
- Easy rollback to previous versions
76+
77+
## Best Practices
78+
79+
1. **Use versioned URLs** - Don't overwrite files at the same URL
80+
2. **Keep old versions available** - Users may need to rollback
81+
3. **Use HTTPS** - Some systems may require secure connections
82+
4. **Test your URLs** - Verify files download correctly before publishing

‎docs/distribution/index.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ This section covers how to distribute and publish your Unraid plugins.
1010

1111
## Topics
1212

13-
- [Community Applications](community-applications.md) - Getting listed in the CA plugin store
14-
- [Hosting Your Plugin](hosting.md) - Where to host your plugin files
15-
- [Support Resources](support.md) - Providing user support
13+
- [Community Applications](community-applications) - Getting listed in the CA plugin store
14+
- [Hosting Your Plugin](hosting) - Where to host your plugin files
15+
- [Support Resources](support) - Providing user support
1616

1717
## Distribution Overview
1818

‎docs/distribution/support.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
layout: default
3+
title: Support Resources
4+
parent: Distribution
5+
nav_order: 3
6+
---
7+
8+
# Support Resources
9+
10+
Providing support for your plugin users.
11+
12+
## Unraid Forums
13+
14+
The [Unraid Forums](https://forums.unraid.net/) are the primary place for plugin support.
15+
16+
### Creating a Support Thread
17+
18+
1. Post in the **Plugin Support** section
19+
2. Use a clear title: `[Plugin] Your Plugin Name`
20+
3. Include in your first post:
21+
- Plugin description and features
22+
- Installation instructions
23+
- Requirements and compatibility
24+
- Known issues
25+
- Changelog
26+
- Links to source code
27+
28+
### Forum Best Practices
29+
30+
- **Monitor regularly** - Users expect responses within a few days
31+
- **Be patient** - Not all users are technical
32+
- **Update the first post** - Keep installation instructions current
33+
- **Document common issues** - Create a FAQ section
34+
35+
## GitHub Issues
36+
37+
If your plugin is hosted on GitHub, Issues provide structured bug tracking:
38+
39+
### Advantages
40+
41+
- Searchable history
42+
- Labels and milestones
43+
- Integration with commits and PRs
44+
- Markdown formatting
45+
46+
### Issue Templates
47+
48+
Create `.github/ISSUE_TEMPLATE/` templates for:
49+
- Bug reports
50+
- Feature requests
51+
52+
## Documentation
53+
54+
Good documentation reduces support burden:
55+
56+
### README.md
57+
58+
Include in your repository:
59+
- What the plugin does
60+
- Installation instructions
61+
- Configuration options
62+
- Troubleshooting steps
63+
64+
### In-Plugin Help
65+
66+
Consider adding help text directly in your plugin's settings page using the Dynamix help system.
67+
68+
## Community Applications Integration
69+
70+
When listed in CA, users can:
71+
- See your support thread link
72+
- Report issues through CA's interface
73+
- Access your documentation
74+
75+
Ensure your CA template includes:
76+
```xml
77+
<Support>https://forums.unraid.net/topic/XXXXX-your-plugin/</Support>
78+
```
79+
80+
## Handling Common Issues
81+
82+
### Installation Failures
83+
84+
Guide users to check:
85+
- `/var/log/plugins/plugin-name.plg` for installation logs
86+
- Network connectivity for downloads
87+
- Unraid version compatibility
88+
89+
### Plugin Not Working
90+
91+
Ask users for:
92+
- Unraid version
93+
- Plugin version
94+
- Relevant log entries
95+
- Steps to reproduce
96+
97+
## Version Support Policy
98+
99+
Be clear about which Unraid versions you support:
100+
- Current stable release
101+
- Previous stable release (recommended)
102+
- Beta/RC versions (optional)

0 commit comments

Comments
 (0)