gitchegumi/homelab
gitchegumi/homelab
Watch
1
0
Fork
You've already forked homelab
 0
Code Issues 1 Pull requests Projects 1 Wiki Activity Actions

Design and build a self-service multi-tenant Foundry VTT hosting platform #19

New issue
Closed
opened 2026-08-31 16:54:15 -05:00 by portegumi · 1 comment
portegumi commented 2026-08-31 16:54:15 -05:00
Collaborator
Copy link

Description

Design and build a self-service Foundry Virtual Tabletop hosting platform for approved users. This is a product-development effort rather than a direct migration of the existing Foundry container.

The platform will present a dashboard at https://foundry.gitchegumi.com where each Dungeon Master can create and manage an isolated Foundry VTT instance using their own valid Foundry license.

The control-plane application should be maintained in a separate repository. The homelab repository will retain the environment-specific UDS package configuration, release pinning, storage configuration, ingress configuration, and operational documentation.

Required user experience

  • A user signs into foundry.gitchegumi.com.
  • A first-time approved user can create an account or authenticate through the selected identity provider.
  • The user supplies their own valid Foundry VTT license.
  • The platform provisions an isolated Foundry instance and persistent volume.
  • Each instance receives 5 GiB of storage by default.
  • The user can view instance status and access their Foundry server from the dashboard.
  • Each instance receives a stable HTTPS endpoint. Evaluate a scheme such as <instance>.foundry.gitchegumi.com.
  • Instance data survives pod recreation, node movement, application upgrades, and control-plane restarts.

Administrative capabilities

  • View users and provisioned instances.
  • Provision, start, stop, restart, and suspend instances.
  • Increase an instance's storage allocation.
  • View current storage allocation and usage.
  • Select or approve the Foundry version used by an instance.
  • View backup and restore status.
  • Retire an instance with an explicit data-retention decision.
  • Review operational status without displaying stored license keys.

PVC reduction is not expected to work in place. Reducing storage may require provisioning a replacement volume and migrating the data.

Licensing and distribution constraints

  • Each concurrently accessible Foundry instance must use its own valid license.
  • A license must not be shared automatically between users or instances.
  • Foundry license keys must not appear in Git, application logs, metrics, events, container arguments, or public API responses.
  • Public repositories and images must not redistribute Foundry's proprietary software.
  • Determine a supported way to acquire and activate Foundry for each instance without embedding licensed artifacts in the public project.
  • Determine whether activation occurs through Foundry's normal first-run workflow or another officially supported mechanism.
  • Users must accept the applicable Foundry license agreement.

References:

Architecture discovery

Create an architecture decision record covering:

  • Control-plane web application and API technology.
  • Kubernetes operator/custom resource versus direct workload orchestration by the application backend.
  • Per-instance namespace versus shared namespace with enforced tenant isolation.
  • StatefulSet, Service, PVC, Secret, NetworkPolicy, and UDS Package design.
  • User authentication and administrative authorization.
  • License-secret encryption, rotation, and deletion.
  • Wildcard DNS and TLS for instance endpoints.
  • Foundry version selection and upgrade policy.
  • Backup, restore, suspension, and deletion workflows.
  • Storage expansion through the TrueNAS CSI driver.
  • Resource requests, limits, quotas, and protection against one instance affecting others.
  • Audit logging and safeguards against exposing tenant information.
  • Recovery behavior when a pod, node, volume attachment, or control-plane component fails.

Initial storage model

  • Each Foundry instance receives a dedicated persistent volume.
  • The default requested capacity is 5 GiB.
  • The selected StorageClass and access mode must follow the conventions established by issues #5 and #6.
  • Storage expansion must preserve all instance data.
  • Administrative quota changes must be auditable.
  • Instance deletion must not destroy retained data without an explicit administrative action.

Security requirements

  • Store license keys and application secrets outside the public repository.
  • Encrypt sensitive values at rest.
  • Prevent license keys from appearing in Kubernetes manifests rendered into Git.
  • Isolate network access and persistent storage between tenants.
  • Separate normal-user and platform-administrator permissions.
  • Protect provisioning and administrative endpoints against unauthorized use.
  • Apply resource quotas and limits to every provisioned instance.
  • Define rate limits and an approval policy for new account provisioning.

Acceptance criteria

  • A separate repository exists for the Foundry hosting control plane.
  • The architecture decision record is reviewed and committed.
  • The public dashboard is available at foundry.gitchegumi.com.
  • A first-time approved user can provision an instance using their own Foundry license.
  • Two users with separate licenses can run isolated instances concurrently.
  • Each instance receives a dedicated 5 GiB persistent volume by default.
  • An administrator can increase an instance's storage allocation.
  • Each instance receives a stable HTTPS endpoint.
  • Instance data survives pod recreation and node rescheduling.
  • Tenant storage, secrets, network access, and administrative permissions are isolated.
  • License keys do not appear in Git, logs, metrics, events, or public API output.
  • Backup and restore are demonstrated for one instance.
  • Instance suspension, upgrade, and retirement workflows are documented and tested.
  • The deployment is packaged and managed through the established UDS workflow.
  • Rollback and disaster-recovery procedures are documented.

Dependencies

  • #5 — Dynamic TrueNAS-backed Kubernetes storage
  • #6 — StorageClass, PersistentVolume, and data-protection conventions
  • #11 — Repeatable application migration and rollback runbook
  • #13 — Secret scanning and Forgejo Actions safeguards

Out of scope for the initial issue

  • Billing or paid subscription management.
  • Public registration without an approval mechanism.
  • Selling or sublicensing Foundry licenses.
  • Automatically providing users with a shared platform-owned Foundry license.
  • Publishing Foundry binaries in a public repository or container image.
## Description Design and build a self-service Foundry Virtual Tabletop hosting platform for approved users. This is a product-development effort rather than a direct migration of the existing Foundry container. The platform will present a dashboard at `https://foundry.gitchegumi.com` where each Dungeon Master can create and manage an isolated Foundry VTT instance using their own valid Foundry license. The control-plane application should be maintained in a separate repository. The homelab repository will retain the environment-specific UDS package configuration, release pinning, storage configuration, ingress configuration, and operational documentation. ## Required user experience - A user signs into `foundry.gitchegumi.com`. - A first-time approved user can create an account or authenticate through the selected identity provider. - The user supplies their own valid Foundry VTT license. - The platform provisions an isolated Foundry instance and persistent volume. - Each instance receives 5 GiB of storage by default. - The user can view instance status and access their Foundry server from the dashboard. - Each instance receives a stable HTTPS endpoint. Evaluate a scheme such as `<instance>.foundry.gitchegumi.com`. - Instance data survives pod recreation, node movement, application upgrades, and control-plane restarts. ## Administrative capabilities - View users and provisioned instances. - Provision, start, stop, restart, and suspend instances. - Increase an instance's storage allocation. - View current storage allocation and usage. - Select or approve the Foundry version used by an instance. - View backup and restore status. - Retire an instance with an explicit data-retention decision. - Review operational status without displaying stored license keys. PVC reduction is not expected to work in place. Reducing storage may require provisioning a replacement volume and migrating the data. ## Licensing and distribution constraints - Each concurrently accessible Foundry instance must use its own valid license. - A license must not be shared automatically between users or instances. - Foundry license keys must not appear in Git, application logs, metrics, events, container arguments, or public API responses. - Public repositories and images must not redistribute Foundry's proprietary software. - Determine a supported way to acquire and activate Foundry for each instance without embedding licensed artifacts in the public project. - Determine whether activation occurs through Foundry's normal first-run workflow or another officially supported mechanism. - Users must accept the applicable Foundry license agreement. References: - https://foundryvtt.com/article/faq/ - https://foundryvtt.com/article/license/ ## Architecture discovery Create an architecture decision record covering: - Control-plane web application and API technology. - Kubernetes operator/custom resource versus direct workload orchestration by the application backend. - Per-instance namespace versus shared namespace with enforced tenant isolation. - StatefulSet, Service, PVC, Secret, NetworkPolicy, and UDS Package design. - User authentication and administrative authorization. - License-secret encryption, rotation, and deletion. - Wildcard DNS and TLS for instance endpoints. - Foundry version selection and upgrade policy. - Backup, restore, suspension, and deletion workflows. - Storage expansion through the TrueNAS CSI driver. - Resource requests, limits, quotas, and protection against one instance affecting others. - Audit logging and safeguards against exposing tenant information. - Recovery behavior when a pod, node, volume attachment, or control-plane component fails. ## Initial storage model - Each Foundry instance receives a dedicated persistent volume. - The default requested capacity is 5 GiB. - The selected StorageClass and access mode must follow the conventions established by issues #5 and #6. - Storage expansion must preserve all instance data. - Administrative quota changes must be auditable. - Instance deletion must not destroy retained data without an explicit administrative action. ## Security requirements - Store license keys and application secrets outside the public repository. - Encrypt sensitive values at rest. - Prevent license keys from appearing in Kubernetes manifests rendered into Git. - Isolate network access and persistent storage between tenants. - Separate normal-user and platform-administrator permissions. - Protect provisioning and administrative endpoints against unauthorized use. - Apply resource quotas and limits to every provisioned instance. - Define rate limits and an approval policy for new account provisioning. ## Acceptance criteria - [ ] A separate repository exists for the Foundry hosting control plane. - [ ] The architecture decision record is reviewed and committed. - [ ] The public dashboard is available at `foundry.gitchegumi.com`. - [ ] A first-time approved user can provision an instance using their own Foundry license. - [ ] Two users with separate licenses can run isolated instances concurrently. - [ ] Each instance receives a dedicated 5 GiB persistent volume by default. - [ ] An administrator can increase an instance's storage allocation. - [ ] Each instance receives a stable HTTPS endpoint. - [ ] Instance data survives pod recreation and node rescheduling. - [ ] Tenant storage, secrets, network access, and administrative permissions are isolated. - [ ] License keys do not appear in Git, logs, metrics, events, or public API output. - [ ] Backup and restore are demonstrated for one instance. - [ ] Instance suspension, upgrade, and retirement workflows are documented and tested. - [ ] The deployment is packaged and managed through the established UDS workflow. - [ ] Rollback and disaster-recovery procedures are documented. ## Dependencies - #5 — Dynamic TrueNAS-backed Kubernetes storage - #6 — StorageClass, PersistentVolume, and data-protection conventions - #11 — Repeatable application migration and rollback runbook - #13 — Secret scanning and Forgejo Actions safeguards ## Out of scope for the initial issue - Billing or paid subscription management. - Public registration without an approval mechanism. - Selling or sublicensing Foundry licenses. - Automatically providing users with a shared platform-owned Foundry license. - Publishing Foundry binaries in a public repository or container image.
portegumi added this to the App Migration milestone 2026-08-31 16:54:15 -05:00
gitchegumi commented 2026-09-02 16:53:48 -05:00
Owner
Copy link

transfered to homelab org

transfered to homelab org
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
app-migration
Migration of existing applications into Kubernetes

  
ci-cd
Forgejo Actions, runners, GitOps, and delivery automation

  
cluster
RKE2 cluster bootstrap and node lifecycle

  
Discussion
Use this label when the issue is meant to be a discussion. These items will not be actioned on, but may lead to new issues with action items.

  
documentation
Architecture, inventory, conventions, and runbooks

  
gpu
NVIDIA enablement and GPU workload scheduling

  
networking
Cluster networking, load balancing, addressing, and DNS

  
security
Security controls and secret-handling safeguards

  
storage
TrueNAS, CSI, NFS, iSCSI, and local persistent storage

  
uds
Defense Unicorns UDS prerequisites and deployment

No labels
app-migration
ci-cd
cluster
Discussion
documentation
gpu
networking
security
storage
uds
Milestone
Clear milestone
No items
No milestone
App Migration
Projects
Clear projects
No items
No project
Homelab k8s Setup
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Depends on
#5 Select and configure dynamic TrueNAS-backed Kubernetes storage
gitchegumi/homelab
#6 Define StorageClass, PersistentVolume, and data-protection conventions
gitchegumi/homelab
#11 Create a repeatable application migration and rollback runbook
gitchegumi/homelab
#13 Add secret scanning for commits and Forgejo Actions
gitchegumi/homelab
Reference
gitchegumi/homelab#19
No description provided.