Skip to content

feat: add Paperless-ngx and Gatus templates - #884

Merged
Siumauricio merged 5 commits into
Dokploy:canaryfrom
BinkyTwin:codex/add-paperless-ngx-template
Jul 8, 2026
Merged

Siumauricio merged 5 commits into
Dokploy:canaryfrom
BinkyTwin:codex/add-paperless-ngx-template

Conversation

@BinkyTwin

@BinkyTwin BinkyTwin commented May 20, 2026 •

Copy link
Copy Markdown
Contributor

/claim #152

Summary

  • add a Paperless-ngx template for self-hosted document management and OCR workflows
  • add a Gatus template for self-hosted endpoint monitoring and status dashboards
  • use pinned application/database/cache images with persistent volumes where needed
  • configure Dokploy domain/env/mount settings for generated secrets, public app URLs, SQLite persistence, and editable app configuration

Refs #152 as a partial template-bounty contribution.

Verification

  • node dedupe-and-sort-meta.js
  • node --import ./build-scripts/node_modules/tsx/dist/loader.mjs build-scripts/validate-template.ts --dir blueprints/paperless-ngx
  • node --import ./build-scripts/node_modules/tsx/dist/loader.mjs build-scripts/validate-template.ts --dir blueprints/gatus
  • node --import ./build-scripts/node_modules/tsx/dist/loader.mjs build-scripts/validate-docker-compose.ts --file blueprints/paperless-ngx/docker-compose.yml
  • node --import ./build-scripts/node_modules/tsx/dist/loader.mjs build-scripts/validate-docker-compose.ts --file blueprints/gatus/docker-compose.yml
  • git diff --check
  • docker compose -f blueprints/paperless-ngx/docker-compose.yml config
  • docker compose -f blueprints/gatus/docker-compose.yml config
  • docker manifest inspect ghcr.io/paperless-ngx/paperless-ngx:2.20.15
  • docker manifest inspect postgres:18-alpine
  • docker manifest inspect redis:8-alpine
  • docker manifest inspect ghcr.io/twin/gatus:v5.36.0

Copilot AI review requested due to automatic review settings May 20, 2026 19:16
@dosubot dosubot Bot added size:S This PR changes 10-29 lines, ignoring generated files. new-template labels May 20, 2026
@github-actions

github-actions Bot commented May 20, 2026 •

Copy link
Copy Markdown
built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name Status Preview Last Commit
templates ✅ Ready (View Log) Visit Preview 0999407

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new Dokploy blueprint for Paperless-ngx (document management + OCR), including its compose stack, Dokploy template configuration, logo asset, and a new meta.json entry so it appears in the central template index.

Changes:

  • Added paperless-ngx blueprint with Docker Compose services (Paperless-ngx + Postgres + Redis) and persistent volumes.
  • Added Dokploy template.toml for domain/env variable wiring (URL, secret key, DB password, timezone, OCR language).
  • Registered the template in meta.json and added a paperless-ngx.svg logo.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File Description
meta.json Adds the Paperless-ngx template entry (id/name/version/links/tags/logo).
blueprints/paperless-ngx/docker-compose.yml Defines Paperless-ngx + Postgres + Redis stack with healthchecks and volumes.
blueprints/paperless-ngx/template.toml Defines Dokploy variables, domain mapping, and env injection for the compose stack.
blueprints/paperless-ngx/paperless-ngx.svg Adds the template logo asset referenced by meta.json.

Comment thread blueprints/paperless-ngx/template.toml Outdated
main_domain = "${domain}"
postgres_password = "${password:32}"
paperless_secret_key = "${password:64}"
paperless_url = "https://${main_domain}"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjusted in 0c3d1cc: the default PAPERLESS_URL now uses http://${main_domain} to match the repository convention for app URL env vars behind Dokploy. Re-ran template validation, Docker Compose validation, metadata processing, git diff --check, and docker compose config with the updated URL.

Copilot AI review requested due to automatic review settings May 20, 2026 19:26
@dosubot dosubot Bot added size:M This PR changes 30-99 lines, ignoring generated files. and removed size:S This PR changes 10-29 lines, ignoring generated files. labels May 20, 2026
@BinkyTwin BinkyTwin changed the title feat: add Paperless-ngx template feat: add Paperless-ngx and Gatus templates May 20, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 7 changed files in this pull request and generated 1 comment.

Comment thread meta.json Outdated
@Siumauricio

Copy link
Copy Markdown
Contributor

Automated template check 🤖

This PR's template was imported into a test Dokploy instance (using the docker-compose.yml + template.toml from the PR head) and deployed, and its configured domains were then checked over HTTP.

Result: ❌ some issues need attention

gatus

  • Deploy: done (24s)
  • Domain checks:
    • gatus:8080 → HTTP 200 ✅

paperless-ngx

  • Deploy: error (49s)
  • Container states at failure time: paperless-ngx-1: created · paperless-ngx-db-1: restarting · paperless-ngx-broker-1: running
  • Issues:
    • the deployment finished with ERROR (see log below)
  • Deploy log (tail):
Container compose-transmit-redundant-panel-55g7yd-paperless-ngx-db-1 Error dependency paperless-ngx-db failed to start
dependency failed to start: container compose-transmit-redundant-panel-55g7yd-paperless-ngx-db-1 is unhealthy
Error: ❌ Docker command failed
Error occurred ❌, check the logs for details.

The test service is removed automatically after verification. Happy to re-test once the PR is updated.

Copilot AI review requested due to automatic review settings July 8, 2026 06:05

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

The postgres:18 image moved its data directory from
/var/lib/postgresql/data to /var/lib/postgresql, and its entrypoint
now fails hard when a volume is mounted at the old path. This made
paperless-ngx-db restart-loop and never reach healthy, so the deploy
errored with 'dependency paperless-ngx-db failed to start'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 8, 2026 07:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

@Siumauricio

Copy link
Copy Markdown
Contributor

Tested both templates on a live Dokploy instance.

gatus: worked out of the box — deployed cleanly and served HTTP 200 (Gatus title). No changes needed.

paperless-ngx: the deploy failed with dependency paperless-ngx-db failed to start — the postgres container was stuck in a restart loop and never became healthy. Root cause: the postgres:18 image moved its data directory from /var/lib/postgresql/data to /var/lib/postgresql, and its entrypoint now errors out when a volume is mounted at the old path. Fixed by changing the mount to paperless-db:/var/lib/postgresql (pushed in 0999407, matches what other postgres:18 blueprints in this repo do).

After the fix: deploy completed in ~41s and the app responded with HTTP 200 (Paperless-ngx sign in page).

@Siumauricio
Siumauricio merged commit 6bd5cd2 into Dokploy:canary Jul 8, 2026
4 checks passed

This branch was successfully deployed

1 active deployment
Preview — 09994075 Deployed Jul 8, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🙋 Bounty claim new-template size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants