feat: add NaviMusic template

[andre-carbajal]

Summary

• Adds a NaviMusic blueprint for deploying the Discord music bot with Dokploy Add NaviMusic #1058 .
• Configures Discord, Spotify, and optional YouTube credentials through the template environment fields.
• Pins the Docker image to anvian/navi-music:4.2.2 and includes catalog metadata and logo.

Validation

• node build-scripts/generate-meta.js --check

Notes

NaviMusic is a Discord bot and does not expose an HTTP service, so the template does not define a domain or ports. A live deployment should be tested in a Dokploy instance with valid Discord credentials.

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

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

[Copilot]

Pull request overview

Adds a new Dokploy blueprint under blueprints/navi-music/ to deploy the NaviMusic Discord music bot, including pinned image version, template env inputs for credentials, and catalog metadata.

Changes:

• Added docker-compose.yml for the navi-music service using anvian/navi-music:4.2.2 and wiring required/optional credentials via env vars.
• Added template.toml exposing Discord/Spotify/YouTube-related environment fields in Dokploy.
• Added meta.json (and logo asset) to register the template in the catalog.

Reviewed changes

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

File	Description
blueprints/navi-music/docker-compose.yml	Defines the NaviMusic service with pinned image and env var wiring.
blueprints/navi-music/template.toml	Declares Dokploy template env fields for required/optional credentials.
blueprints/navi-music/meta.json	Adds catalog metadata (id/name/version/links/tags/logo).

Comments suppressed due to low confidence (1)

blueprints/navi-music/template.toml:9

• Same issue here: the quoted "# ..." line is a literal env string without '='. Prefer a TOML comment so config.env remains a list of real KEY=VALUE entries only.

  "# Optional YouTube authentication. See NaviMusic's README for how to obtain these values.",
  "YOUTUBE_POTOKEN=",

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

blueprints/navi-music/template.toml:8

• The env array includes a quoted string starting with # ("# Optional YouTube authentication..."). Dokploy expects config.env entries to be KEY=VALUE strings; this quoted comment would be treated as an environment entry without =, which can break parsing/validation or produce an invalid env item.

  "# Optional YouTube authentication. See NaviMusic's README for how to obtain these values.",

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

blueprints/navi-music/template.toml:10

• YOUTUBE_OAUTH2 is treated as mandatory upstream (the app throws on startup when the OAuth token is blank), but this template currently presents the YouTube credentials without indicating that YOUTUBE_OAUTH2 must be provided. With the current defaults (empty string), deployments will crash-loop unless users proactively fill it in.

  "SPOTIFY_CLIENT_ID=",
  "SPOTIFY_CLIENT_SECRET=",
  "YOUTUBE_POTOKEN=",
  "YOUTUBE_VISITOR=",
  "YOUTUBE_OAUTH2=",

[Siumauricio]

Thanks for the contribution! I deploy-tested this template and unfortunately it cannot work as a one-click template in its current state — the container cannot boot with any placeholder configuration, so every fresh deploy ends in a permanent crash-loop.

What I tested

1. Template defaults (all env vars empty), locally and on a live Dokploy instance:

docker run -e DISCORD_TOKEN= -e SPOTIFY_CLIENT_ID= -e SPOTIFY_CLIENT_SECRET= \
  -e YOUTUBE_POTOKEN= -e YOUTUBE_VISITOR= -e YOUTUBE_OAUTH2= anvian/navi-music:4.2.2

Result: exit 1 at Spring startup:

Caused by: java.lang.RuntimeException: YouTube OAuth token is mandatory.
Please provide a valid 'app.youtube.oauth2' in application.properties or as an environment variable.
	at net.andrecarbajal.naviMusic.config.AudioConfig.setupAudioSources(AudioConfig.kt:43)

On Dokploy the deploy itself finishes "done", but the container then sits in a restarting loop forever (restart: unless-stopped), which is a bad first-run experience for users.

2. Non-empty placeholder for YOUTUBE_OAUTH2 (e.g. placeholder): also exit 1 — useOauth2(oAuthToken, true) eagerly calls YoutubeOauth2Handler.setRefreshToken → refresh against Google's OAuth endpoint → IOException: Invalid status code for oauth2 token fetch: 400 → Spring context fails.

So the only way the container starts at all is with a valid YouTube OAuth2 refresh token (obtained via an interactive device-code flow) — before the Discord token even comes into play. There is no placeholder value a template can ship that lets the app boot. (Side note: the upstream README still says "If YOUTUBE_OAUTH2 is missing, follow the console instructions on the first run", but since 4.1.1 the app throws instead — the docs seem stale.)

Suggested fix (upstream)

You already handle a blank DISCORD_TOKEN gracefully in BotConfiguration (log an error and keep the app running). Applying the same pattern to the YouTube source would fix this:

• When YOUTUBE_OAUTH2 is blank, skip useOauth2(...) (or lazy-init the YouTube source manager) and log a clear warning instead of throwing in AudioConfig.setupAudioSources, so the container boots and users can add credentials via Dokploy's environment settings afterwards.
• Publish a patch release + Docker tag, and bump the template to it.

The template itself is otherwise in good shape (per-blueprint meta.json, pinned image, no host ports/container_name, mirrors the upstream compose, no domain needed for a bot), and the project checks out as real and actively maintained — so once the image can boot without third-party credentials, this should be good to re-test and merge. Happy to re-run the deploy test when a fixed version is available.

[Copilot]

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]

Update: I found a way to make this work as a one-click template without waiting for an upstream release, and pushed the fix to this branch (29388e2).

Root cause (re-verified today)

• anvian/navi-music:4.2.2 is unchanged since July (same digest 7a6f2ee3...), and there is still no newer release/tag upstream, so the boot behavior is exactly what we measured before: AudioConfig.setupAudioSources throws YouTube OAuth token is mandatory when YOUTUBE_OAUTH2 is blank, and any non-valid placeholder dies eagerly on the Google token refresh (Invalid status code for oauth2 token fetch: 400). No placeholder configuration can ever boot 4.1.1/4.2.1/4.2.2 — the enforcement was introduced in upstream commit 987c5053 (v4.1.1).
• 4.1.0 is the newest published image without that enforcement. I read its source and deploy-tested it: with a blank YOUTUBE_OAUTH2 it simply registers the non-OAuth YouTube clients, blank Spotify credentials are caught and logged (SpotifyTokenProvider.refreshAccessToken swallows the error), and a blank/invalid DISCORD_TOKEN is logged (Bot token not specified!) instead of thrown.
• One remaining wrinkle: with no Discord token there are no JDA threads to keep the JVM alive, so the app exits 0 after startup and restart: unless-stopped turns that into a quiet restart loop on first deploy.

Fix applied

1. Pinned the image to anvian/navi-music:4.1.0 (with a comment in the compose explaining why newer tags cannot be used).
2. Wrapped the entrypoint: if the app exits 0 (empty/invalid token — the graceful paths above), the container prints "NaviMusic is idle. Set DISCORD_TOKEN ... then redeploy." and idles via tail -f /dev/null, so users land on a running container with clear instructions in the logs. Non-zero exits still propagate to the restart policy, so real crashes are not masked.
3. Marked the YouTube variables as optional in template.toml, bumped meta.json to 4.1.0, and merged latest canary.

Deploy test (live Dokploy instance, template defaults, all env empty)

• Deploy finished done in 21s; container running with ExitCode 0, RestartCount 0 after 90+ seconds (no flapping).
• Logs end with: ERROR ... Bot token not specified! followed by NaviMusic is idle. Set DISCORD_TOKEN (and optionally Spotify/YouTube credentials) in the Environment tab, then redeploy.

@andre-carbajal once upstream ships a release that boots with a blank YOUTUBE_OAUTH2 (e.g. skipping useOauth2 instead of throwing, as suggested earlier), we can bump the tag back to latest — the entrypoint wrapper is forward-compatible with that change.