armyguy255a/foundryvtt

foundryvtt-docker

镜像概述和主要用途

foundryvtt-docker是一个用于快速部署Foundry Virtual Tabletop（虚拟桌面）服务器的Docker镜像。该镜像设计注重安全性、可靠性、紧凑性和易用性，能够让用户在几分钟内启动并运行一个Foundry Virtual Tabletop实例。它仅需用户提供下载Foundry Virtual Tabletop发行版所需的凭据或URL即可完成部署。

核心功能和特性

• 快速部署：几分钟内即可完成Foundry Virtual Tabletop服务器的搭建
• 安全可靠：设计遵循安全最佳实践，确保服务器稳定运行
• 多种部署方式：支持使用凭据、临时URL或Docker Compose进行部署
• 灵活配置：通过环境变量或Docker Secrets支持Foundry的所有配置选项
• 跨平台支持：兼容amd64、arm/v6、arm/v7、arm64、ppc64le、s390x等多种架构
• 版本控制：提供多种镜像标签，支持稳定版、测试版及特定版本的部署
• 数据持久化：通过卷挂载确保配置、数据和日志的持久化存储

先决条件

• 已安装Docker环境
• 拥有FoundryVTT.com账户及已购买的软件许可证

使用方法和配置说明

使用Docker和凭据运行

以下命令可启动Foundry Virtual Tabletop服务器，需要提供foundryvtt.com的凭据以安装和授权服务器：

console
docker run \
  --env FOUNDRY_USERNAME='<你的用户名>' \
  --env FOUNDRY_PASSWORD='<你的密码>' \
  --publish 30000:30000/tcp \
  --volume <你的数据目录>:/data \
  felddy/foundryvtt:release

如果使用bash或类似shell，可在Docker命令前添加空格，防止凭据被记录到shell历史中（参考HISTCONTROL）。

使用Docker和临时URL运行

或者，可从Foundry网站的用户个人资料页面获取临时下载令牌。在"已购买许可证"页面，点击标准Node.js下载链接右侧的[🔗]图标，获取软件的临时下载URL：

console
docker run \
  --env FOUNDRY_RELEASE_URL='<临时URL>' \
  --publish 30000:30000/tcp \
  --volume <你的数据目录>:/data \
  felddy/foundryvtt:release

使用Docker Compose运行

推荐使用docker compose管理服务器，docker-compose.yml文件能更可靠地启动和维护容器并记录配置。Foundry的所有配置选项都可通过环境变量指定。

1. 创建类似以下的docker-compose.yml文件，提供凭据作为环境变量值：

   yaml
   version: "3.8"
   
   services:
     foundry:
       image: felddy/foundryvtt:release
       hostname: my_foundry_host
       init: true
       restart: "unless-stopped"
       volumes:
         - type: bind
           source: <你的数据目录>
           target: /data
       environment:
         - FOUNDRY_PASSWORD=<你的密码>
         - FOUNDRY_USERNAME=<你的用户名>
         - FOUNDRY_ADMIN_KEY=atropos
       ports:
         - target: 30000
           published: 30000
           protocol: tcp
   

2. 启动容器并后台运行：

   console
   docker compose up --detach
   

3. 通过以下地址访问Web应用：http://localhost:30000

如果一切顺利，你将看到许可协议提示，然后使用FOUNDRY_ADMIN_KEY变量设置的"管理员访问密钥"登录。

使用密钥

此容器还支持通过Docker Secrets传递敏感值。使用密钥传递凭据等敏感值比环境变量更安全。密钥json文件可任意命名（本示例使用secrets.json），但必须如以下示例所示在容器内映射为config.json。有关所有支持的密钥，请参见下面的密钥部分。

1. 创建包含要设置的值的secrets.json文件：

   json
   {
     "foundry_admin_key": "atropos",
     "foundry_password": "你的密码",
     "foundry_username": "你的用户名"
   }
   

2. 在docker-compose.yml文件中添加密钥：

   yaml
   version: "3.8"
   
   secrets:
     config_json:
       file: secrets.json
   
   services:
     foundry:
       image: felddy/foundryvtt:release
       hostname: my_foundry_host
       init: true
       restart: "unless-stopped"
       volumes:
         - type: bind
           source: <你的数据目录>
           target: /data
       environment:
       ports:
         - target: 30000
           published: 30000
           protocol: tcp
       secrets:
         - source: config_json
           target: config.json
   

更新容器

此容器默认禁用Foundry的"更新软件"选项卡。要升级到新版本的Foundry，请拉取更新的镜像版本。

使用Docker Compose更新

1. 从Docker Hub拉取新镜像：

   console
   docker compose pull
   

2. 重新创建运行中的容器：

   console
   docker compose up --detach
   

使用Docker更新

1. 停止运行中的容器：

   console
   docker stop <容器ID>
   

2. 拉取新镜像：

   console
   docker pull felddy/foundryvtt:release
   

3. 按照前面的运行说明启动容器。

镜像标签

此容器的镜像使用Foundry Virtual Tabletop的语义化版本及其关联的更新通道进行标记。建议大多数用户使用:release标签。

有关所有支持标签的列表，请参见Docker Hub上的https://hub.docker.com/r/felddy/foundryvtt/tags%E3%80%82

卷

环境变量

必填组合

必须设置以下三种环境变量组合之一，容器才能定位并安装Foundry Virtual Tabletop发行版。尽管可以一起指定所有变量，但它们按以下优先级顺序进行评估：

1. FOUNDRY_RELEASE_URL，或
2. FOUNDRY_USERNAME和FOUNDRY_PASSWORD，或
3. CONTAINER_CACHE

凭据变量

注意： FOUNDRY_USERNAME和FOUNDRY_PASSWORD也可以使用密钥而不是环境变量进行设置。

预签名URL变量

预缓存发行版变量

可以下载发行版并将其放入缓存目录。发行版的名称必须为以下形式：foundryvtt-0.8.9.zip

可选变量

密钥

从源代码构建

使用此git仓库作为构建上下文在本地构建镜像：

console
docker build \
  --build-arg VERSION=0.8.9 \
  --tag felddy/foundryvtt:0.8.9 \
  https://github.com/felddy/foundryvtt-docker.git#develop

跨平台构建

要创建与其他平台兼容的镜像，可以使用Docker的buildx功能：

1. 使用上面的"Clone"按钮或命令行将项目复制到你的机器：