feat: add official Pullbox Unraid templates

.github/workflows/validate.yml

@@ -0,0 +1,26 @@
+name: Validate
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: unraid-templates-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  templates:
+    name: Templates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Validate repository metadata and templates
+        run: make validate

.gitignore

@@ -1,2 +1,4 @@
 .DS_Store
 Thumbs.db
+__pycache__/
+*.py[cod]

Makefile

@@ -0,0 +1,4 @@
+.PHONY: validate
+
+validate:
+	python3 -m unittest discover -s tests -v

README.md

@@ -1,32 +1,145 @@
-# Community Apps Starter Template
-
-Use this repository as a GitHub template when you want a clean starting point for a new Community Apps submission repository.
-
-## Quick Start
-
-1. Click **Use this template** on GitHub and create your own repository.
-2. Replace the placeholder values in `ca_profile.xml`, `templates/example-app.xml`, and `plugins/example-plugin.xml`.
-3. Replace `icon.svg` with your own repository icon, or update `ca_profile.xml` to point at a hosted icon you control.
-4. Keep one XML file per Docker app under `templates/`.
-5. Keep one XML wrapper per plugin under `plugins/`.
-6. Delete the example files you do not need.
-7. Commit and push your repository.
-8. Run **Validate** and **Scan** in the Community Apps submit flow: `/submit`.
-
-## Starter Files
-
-- `README.md`: onboarding notes for whoever maintains the repository.
-- `LICENSE`: starter MIT license text. Replace the placeholder copyright line.
-- `.gitignore`: keeps common OS junk out of the repo.
-- `icon.svg`: starter repository icon referenced by `ca_profile.xml`.
-- `ca_profile.xml`: repository overview and support metadata shown in Community Apps.
-- `templates/example-app.xml`: starter Docker application template.
-- `plugins/example-plugin.xml`: starter plugin wrapper.
-
-## Submission Notes
-
-- Keep `ca_profile.xml` in the repository root.
-- Every Docker app entry needs a `<Repository>` tag.
-- Every plugin entry needs a `<PluginURL>` tag.
-- Keep each template's `TemplateURL` pointed at the raw GitHub URL for that exact XML file.
-- Use an OSI-approved license before submitting.
+# Pullbox for Unraid Community Applications
+
+This repository contains the official Unraid Community Applications templates
+for [Pullbox](https://pullbox.app) and its optional production direct-download
+providers.
+
+## Available applications
+
+| Application | Purpose | Image |
+| --- | --- | --- |
+| Pullbox | Comic library management, acquisition, imports, and reading | `ghcr.io/pullboxapp/pullbox:latest` |
+| Pullbox Provider - GetComics | GetComics discovery and supported artifact-route resolution | `ghcr.io/pullboxapp/pullbox-provider-getcomics:latest` |
+| Pullbox Provider - Anna's Archive | Anna's Archive discovery and member fast-download resolution | `ghcr.io/pullboxapp/pullbox-provider-annas-archive:latest` |
+
+The provider containers are optional and independently versioned. The synthetic
+provider image in the provider source repository is a protocol test tool, not a
+production application, and is intentionally not published here.
+
+## Install Pullbox
+
+Once this repository is accepted into Community Applications:
+
+1. Open **Apps** in Unraid and search for **Pullbox**.
+2. Review the path mappings and fixed-user permission requirement.
+3. Install Pullbox and open its WebUI.
+4. Complete the first-run account setup.
+
+Pullbox runs as the fixed non-root UID/GID `65532:65532`; it does not use
+`PUID` or `PGID`. Follow the
+[NAS and Unraid permissions guide](https://pullbox.app/docs/getting-started/nas-and-unraid-permissions)
+before first start.
+
+## Recommended provider network
+
+Keep Pullbox and its providers on the same user-defined private Docker network.
+This allows Pullbox to use stable container names and keeps provider API ports
+off the LAN.
+
+Create the network once from the Unraid terminal:
+
+```bash
+docker network create pullbox
+```
+
+Choose `pullbox` as **Network Type** for the Pullbox, GetComics, and Anna's
+Archive templates. If Pullbox was already installed, edit its container,
+select the `pullbox` network, and apply the change before installing providers.
+
+With the recommended network, leave each provider's optional fallback port
+blank and register these endpoints in **Pullbox -> Settings -> Direct
+Downloads**:
+
+| Provider | Endpoint |
+| --- | --- |
+| GetComics | `http://Pullbox-Provider-GetComics:8780` |
+| Anna's Archive | `http://Pullbox-Provider-Annas-Archive:8780` |
+
+Select Pullbox's acknowledgement for unencrypted HTTP on a trusted private
+network when registering either endpoint.
+
+## Bridge-network fallback
+
+The providers can also work without the dedicated network. Leave the
+containers on `bridge`, assign a distinct host port in each provider's optional
+**Fallback API Port** field, and register the Unraid server's private LAN
+address in Pullbox. For example:
+
+| Provider | Suggested host port | Example endpoint |
+| --- | --- | --- |
+| GetComics | `8780` | `http://192.168.1.20:8780` |
+| Anna's Archive | `8781` | `http://192.168.1.20:8781` |
+
+Replace the example address with the Unraid server's LAN address. Do not use
+`localhost`, because that refers to the Pullbox container itself. Do not
+port-forward provider API ports to the internet. Public or remote provider
+endpoints must use HTTPS.
+
+## Provider tokens and registration
+
+Generate a different bearer token for each provider. From the Unraid terminal:
+
+```bash
+openssl rand -hex 32
+```
+
+Enter the token in the provider template, then enter the same token when
+registering that provider in Pullbox. Provider tokens must contain at least 32
+characters. Pullbox stores them encrypted and does not expose them again.
+
+After installing a provider:
+
+1. Open **Settings -> Direct Downloads** in Pullbox.
+2. Select **Add Provider**.
+3. Enter the private-network or bridge-fallback endpoint.
+4. Enter the matching bearer token.
+5. Acknowledge private HTTP when using a trusted private address.
+6. Test, save, configure, and enable the provider.
+
+Anna's Archive member fast-download credentials are entered later in Pullbox's
+provider settings. They are not container environment variables.
+
+## Template contract
+
+The templates preserve the production container contracts:
+
+- Pullbox exposes `8585/tcp` and mounts `/data`, `/comics`, `/downloads`, and
+  optional `/imports` paths.
+- Provider services expose `8780/tcp` only inside their container network by
+  default and require no host volumes.
+- Provider services run as UID/GID `65532:65532` with a read-only root
+  filesystem, all Linux capabilities dropped, `no-new-privileges`, and a
+  bounded `/tmp` tmpfs.
+- Every provider receives only its own bearer token. It does not receive
+  Pullbox paths, its database, or unrelated credentials.
+
+Keep these templates synchronized with Pullbox's production
+[`docker/docker-compose.yml`](https://github.com/pullboxapp/pullbox/blob/main/docker/docker-compose.yml)
+and the provider
+[deployment contract](https://github.com/pullboxapp/pullbox-direct-providers#deployment-and-registration).
+
+## Validation and submission
+
+Run the local repository contract before submitting changes:
+
+```bash
+make validate
+```
+
+After changes reach `main`, run **Validate** and **Scan** through the
+[Unraid Community Applications submission flow](https://ca.unraid.net/submit).
+
+## Support
+
+- [Documentation](https://pullbox.app/docs/)
+- [Direct-download setup](https://pullbox.app/docs/configuration/direct-downloads)
+- [GitHub issues](https://github.com/pullboxapp/pullbox/issues)
+- [Discord](https://discord.gg/mg6GQkATaA)
+
+Security reports should follow the private reporting instructions in Pullbox's
+[`SECURITY.md`](https://github.com/pullboxapp/pullbox/blob/main/SECURITY.md).
+
+## License
+
+The templates in this repository are licensed under GPL-3.0-or-later, matching
+Pullbox and the official direct-download providers. See `LICENSE` for details.

ca_profile.xml

@@ -1,24 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
 <CommunityApplications>
-  <!-- Required profile -->
-  <Profile>
-    Describe what users will find in this repository, which apps or plugins you maintain, and where they should go for support.  Markdown supported
-  </Profile>
-  <!-- Optional icon -->
-  <Icon>https://raw.githubusercontent.com/YOUR_GITHUB_USERNAME/YOUR_REPO_NAME/main/icon.svg</Icon>
-  <!-- Optional web page -->
-  <WebPage>https://github.com/YOUR_GITHUB_USERNAME/YOUR_REPO_NAME</WebPage>
-  <!-- Optional support and donation links -->
-  <Forum>https://forums.unraid.net/topic/YOUR_SUPPORT_TOPIC</Forum>
-  <!-- Optional Discord link -->
-  <Discord>https://discord.gg/YOUR_INVITE_CODE</Discord>
-  <!-- Optional donation link -->
-  <DonateLink>https://github.com/sponsors/YOUR_GITHUB_USERNAME</DonateLink>
-  <!-- Optional donation text -->
-  <DonateText>Support this project</DonateText>
-  <!-- Optional photos -->
-  <Photo>URL to any photos</Photo>
-  <!-- You can add multiple photos by adding multiple <Photo> tags -->
-  <!-- Optional videos -->
-  <Video>URL to any video.  Youtube URLs are recommended</Video>
-  <!-- You can add multiple videos by adding multiple <Video> tags -->
-</CommunityApplications>
+  <Profile>Official Unraid Community Applications templates for Pullbox and its optional GetComics and Anna's Archive direct-download providers. Pullbox is a self-hosted comic library manager for monitoring, acquisition, imports, browser reading, and release discovery. Documentation and support are available at https://pullbox.app/docs/.</Profile>
+  <Icon>https://raw.githubusercontent.com/pullboxapp/unraid-templates/main/icon.png</Icon>
+  <WebPage>https://pullbox.app</WebPage>
+  <Discord>https://discord.gg/mg6GQkATaA</Discord>
+</CommunityApplications>