[Foundry P1] Install & validate foundryvtt-rest-api on the production Foundry instance #4

New issue

Open

opened 2026-06-23 00:42:30 +00:00 by rbrooks · 1 comment

rbrooks commented

2026-06-23 00:42:30 +00:00

Owner

Do this first, before any adapter code. The REST module is documented as version-sensitive, so confirm it works on the actual target instance before sinking adapter time.

Scope

Install and configure the ThreeHats/foundryvtt-rest-api module on the production Foundry instance.
Set up the API key on the Foundry side.
Document, in docs/, the required module version, API key setup steps, and the Foundry core version the integration is tested against.

Notes

The module has historically been sensitive to Foundry core upgrades. Record the tested module + core version pair and flag compatibility as a maintenance concern whenever either is updated.
Foundry is often hosted locally or behind a VPN - validate against the real instance, not a throwaway.

Done when

Module installed on prod Foundry, reachable from the backend, version pair documented.

Roadmap: FoundryVTT Bidirectional Integration, Phase 1 step 1.

**Do this first**, before any adapter code. The REST module is documented as version-sensitive, so confirm it works on the actual target instance before sinking adapter time. ## Scope - Install and configure the **ThreeHats/foundryvtt-rest-api** module on the production Foundry instance. - Set up the API key on the Foundry side. - Document, in `docs/`, the required module version, API key setup steps, and the Foundry **core version** the integration is tested against. ## Notes - The module has historically been sensitive to Foundry core upgrades. Record the tested module + core version pair and flag compatibility as a maintenance concern whenever either is updated. - Foundry is often hosted locally or behind a VPN - validate against the real instance, not a throwaway. ## Done when - Module installed on prod Foundry, reachable from the backend, version pair documented. _Roadmap: FoundryVTT Bidirectional Integration, Phase 1 step 1._

rbrooks added this to the v5.0.0 - FoundryVTT Phase 1: Foundation milestone

2026-06-23 00:42:30 +00:00

rbrooks added the

backend

enhancement

labels

2026-06-23 00:42:30 +00:00

rbrooks referenced this issue

2026-06-24 04:21:51 +00:00

[Foundry] Bidirectional integration — architecture & design reference #24

claude-bot referenced this issue

2026-07-15 22:02:32 +00:00

[Foundry] Decide & document connection topology: self-hosted relay vs direct URL, and the SSRF/URL-policy exemption #143

claude-bot referenced this issue

2026-07-15 22:03:23 +00:00

[Foundry] Token image on pushed actors #150

claude-bot commented

2026-07-27 23:15:00 +00:00

Contributor

Approach change: dev Foundry instance first (2026-07-27)

Decision from today's session: the Foundry pillar will be built against a dedicated dev Foundry instance, which does not exist yet. Standing one up is now the real first step of v4.0.0 — ahead of everything in this issue.

That partially supersedes this issue's "validate against the real instance, not a throwaway" instruction, so worth being precise about what still holds and what changes:

Still holds — and is now the thing to get right. The module is version-sensitive; that was the whole reason for insisting on the real instance. A dev instance is a perfectly good validation target provided it matches production's Foundry core version and module version. So the deliverable sharpens rather than weakens: record the tested (Foundry core version, foundryvtt-rest-api version) pair, and treat a drift between dev and prod on either as the compatibility risk to watch. A dev instance on a different core version would give false confidence — exactly what the original wording was guarding against.

Changes. Installing the module on production is no longer step one. Prod becomes a later verification step, once the adapter work is proven against dev.

Why a dev instance is worth the setup cost: this pillar writes into Foundry — actors, tokens, journal entries, live scenes (v4.2.0). Developing that against a live game world risks corrupting real campaign data, and there is no undo for a bad actor push. The same gap exists on the Discord side, incidentally: the dev bot has no DISCORD_BOT_TOKEN, so bot behaviour is currently only exercisable in production.

Suggested revised order for v4.0.0:

Stand up a dev Foundry instance, matched to production's core version.
Install and configure foundryvtt-rest-api on it; confirm reachability from the backend. (this issue)
Document the tested core + module version pair in docs/. (this issue)
Settle the connection topology and SSRF policy exemption — #143, which needs deciding before any connection code.
Then the adapter work: #5, #6, #7, #8.
Install and validate on production before the pillar ships.

No code has been written for this pillar yet, so nothing is invalidated by the change.

🤖 Generated with Claude Code

### Approach change: dev Foundry instance first (2026-07-27) Decision from today's session: **the Foundry pillar will be built against a dedicated dev Foundry instance**, which does not exist yet. Standing one up is now the real first step of v4.0.0 — ahead of everything in this issue. That partially supersedes this issue's "validate against the real instance, not a throwaway" instruction, so worth being precise about what still holds and what changes: **Still holds — and is now the thing to get right.** The module is version-sensitive; that was the whole reason for insisting on the real instance. A dev instance is a perfectly good validation target *provided it matches production's Foundry core version and module version*. So the deliverable sharpens rather than weakens: record the tested **(Foundry core version, `foundryvtt-rest-api` version)** pair, and treat a drift between dev and prod on either as the compatibility risk to watch. A dev instance on a different core version would give false confidence — exactly what the original wording was guarding against. **Changes.** Installing the module on production is no longer step one. Prod becomes a later verification step, once the adapter work is proven against dev. **Why a dev instance is worth the setup cost:** this pillar writes into Foundry — actors, tokens, journal entries, live scenes (v4.2.0). Developing that against a live game world risks corrupting real campaign data, and there is no undo for a bad actor push. The same gap exists on the Discord side, incidentally: the dev bot has no `DISCORD_BOT_TOKEN`, so bot behaviour is currently only exercisable in production. **Suggested revised order for v4.0.0:** 1. Stand up a dev Foundry instance, matched to production's core version. 2. Install and configure `foundryvtt-rest-api` on it; confirm reachability from the backend. *(this issue)* 3. Document the tested core + module version pair in `docs/`. *(this issue)* 4. Settle the connection topology and SSRF policy exemption — [#143](https://git.rhoving.com/rbrooks/Quest-Board/issues/143), which needs deciding before any connection code. 5. Then the adapter work: #5, #6, #7, #8. 6. Install and validate on production before the pillar ships. No code has been written for this pillar yet, so nothing is invalidated by the change. 🤖 Generated with [Claude Code](https://claude.com/claude-code)