ToolJet 本地开发环境搭建指南用 Docker Compose 实现服务编排、热重载与 VSCode 调试【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文是面向ToolJet 贡献者的本地开发环境搭建指南围绕 Docker Compose 讲解如何一键拉起 ToolJet 的前端client、后端server、插件构建plugins、PostgreSQL、Redis 与 PostgREST 全栈服务。读完本文你将掌握从克隆仓库、生成安全密钥到启动开发容器、运行单元 / e2e 测试以及在 VSCode 中远程调试 Docker 内 Node.js 服务的完整流程。适用范围说明本文流程面向开发 / 贡献场景若你只是想在本地或服务器上部署运行 ToolJet自托管请参照仓库中的 Setup 章节其中包含 Docker、Kubernetes、Helm 等多种部署路径如果只是快速体验可先阅读 Try ToolJet。前置条件在开始之前请确保本机已安装最新版本的docker与docker compose插件Docker Desktop 自带 compose 子命令Linux 环境需单独安装 compose plugin。Windows 用户特别注意建议使用 Docker Desktop 的 WSL2 后端并且所有命令必须在WSL2 终端中执行而不是 PowerShell 或 CMD。同时由于 Windows 默认行尾符为 CRLF从deploy/docker/.env.internal.example复制生成的.env文件需要把行尾符调整为LF否则环境变量解析会出错。仓库根目录的 docker-compose.yaml 是本次开发环境的服务编排核心共定义 6 个服务plugins、client、server、redis、postgrest、postgres。启动后的端口映射如下服务容器内监听宿主机映射作用client80828082ToolJet 前端webpack dev serverserver30003000ToolJet NestJS 后端 APIpostgrest30003001PostgREST为 ToolJet Database 提供 REST 接口postgres54325432主数据库服务端数据redis63796379缓存与队列支持其中server通过depends_on依赖postgres、redis、postgrest且其容器环境变量中把REDIS_HOSTredis、PG_HOSTpostgres、PGRST_HOSTpostgrest直接指向 compose 服务名即容器间通过服务名互联。本地开发环境搭建步骤1. Fork 并克隆仓库以 GitHub 协作模式为例先进入上游 ToolJet 仓库页面点击Fork按钮在自己账号下生成一份副本随后把这份 fork 克隆到本地git clone your-forked-tooljet-repo-url cd ToolJet2. 准备 .env 环境变量文件ToolJet 在启动时需要大量环境变量数据库连接、加密密钥、SSO 配置等。本地开发用的是内部internal环境模板将其复制为项目根目录的.envcp ./deploy/docker/.env.internal.example .env模板文件本身位于 deploy/docker/.env.internal.example其中已预置了TOOLJET_HOSThttp://localhost:8082、数据库名、PGRST_HOSTpostgrest等开发默认值。更完整的变量说明含生产部署所需项可查阅仓库文档 env-vars.md。3. 用脚本自动填充安全密钥.env中以下几项属于必须安全随机生成的敏感密钥逐个手写既不安全也易出错LOCKBOX_MASTER_KEYToolJet 用于加密数据源凭据等敏感信息的 Lockbox 主密钥SECRET_KEY_BASE用于会话与签名等安全操作的密钥基PGRST_JWT_SECRETPostgREST 签发/校验 JWT 的密钥PG_PASS/TOOLJET_DB_PASSPostgreSQL 用户密码。官方提供了一个一键填充脚本直接执行即可chmod x ./deploy/docker/internal.sh ./deploy/docker/internal.sh从源码看deploy/docker/internal.sh 的逻辑非常清晰先source .env加载现有配置然后逐一检查上述键值是否为空为空则调用openssl rand生成并回写.envLOCKBOX_MASTER_KEY用openssl rand -hex 3264 位十六进制SECRET_KEY_BASE用openssl rand -hex 64128 位十六进制PGRST_JWT_SECRET用openssl rand -hex 32PG_PASS与TOOLJET_DB_PASS通过openssl rand -base64 12处理后截取 16 位最后根据生成的密码拼接出PGRST_DB_URI并回写。也就是说这个脚本是幂等的若相应键已存在则跳过打印提示可安全重复执行。4. 构建开发镜像并启动先构建镜像。由于 compose 中的client、server、plugins三个服务都使用仓库根目录作为构建上下文context: ./首次构建需要拉取基础镜像并安装 npm 依赖耗时较长docker compose build docker compose run --rm plugins npm run build:plugins第二条命令以一次性容器方式先构建插件包plugins产物供 server/client 使用。三个开发镜像分别由 docker/client.Dockerfile.dev、docker/server.Dockerfile.dev、docker/plugins.Dockerfile.dev 定义均基于node:22.15.1-bullseye并通过NODE_OPTIONS--max-old-space-size4096提高 Node 堆内存上限以避免前端构建、服务编译时内存溢出。随后启动全部服务docker compose up等 client 的 webpack dev server 与 server 的 NestJS watch 模式就绪后在浏览器访问http://localhost:8082即可看到 ToolJet 界面首次访问会引导创建管理员账号。需要停止开发环境时docker compose stopstop只是暂停容器数据卷postgres、redis保留下次docker compose up可快速恢复现场。代码改动与容器热重载开发镜像把宿主目录以 volume 方式挂载进容器client 挂载./frontend与./plugins运行npm run --prefix frontend startwebpack dev serverserver 挂载./server、./plugins以及根目录的.env/.env.test运行npm run --prefix server start:devNestJS watch 模式。因此修改前端或后端代码后对应容器会自动热重载无需手动重启。但以下两类变更需要额外处理涉及数据库迁移或新增 npm 依赖如果改动包含 TypeORM migration或在package.json中新增了依赖包需要重启 server 容器使新代码/依赖生效docker compose restart server需要为容器内新增系统级依赖若新增的功能要求安装某个二进制工具或系统库例如图像处理命令imagemagick就必须修改 docker/server.Dockerfile.dev在apt-get install列表中追加依赖然后重建镜像并重启docker compose build server docker compose up以文档中的示例为例改造后的 Dockerfile 大致形态如下原文档中该示例基于node:18.18.2-buster请注意当前仓库的 server 开发镜像实际基线为node:22.15.1-bullseye实践时应以仓库内现有 Dockerfile 为基准仅追加你需要的 apt 包FROM node:22.15.1-bullseye AS builder RUN apt-get update apt-get install -y \ build-essential \ postgresql-client \ freetds-dev \ libaio1 \ imagemagick RUN mkdir -p /app WORKDIR /app COPY ./server/package.json ./server/package-lock.json ./server/ RUN npm --prefix server install ENV NODE_ENVdevelopment COPY ./server/ ./server/ COPY ./docker/ ./docker/ COPY ./.env ../.env RUN [chmod, 755, entrypoint.sh]保存后依次执行docker compose build server与docker compose up新容器即包含imagemagick。在 Docker 中运行测试测试环境配置来自项目根目录的.env.test文件与.env相互独立。先创建并迁移测试数据库docker compose run --rm -e NODE_ENVtest server npm run db:create docker compose run --rm -e NODE_ENVtest server npm run db:migrate这些命令实际对应 server/package.json 中的脚本db:create调用ts-node ./scripts/create-database.tsdb:migrate依次执行 schema migration基于 TypeORM CLI与 data migration。运行单元测试docker compose run --rm server npm run --prefix server test运行 e2e端到端测试docker compose run --rm server npm run --prefix server test:e2e只运行某个特定的单元测试文件docker compose run --rm server npm --prefix server run test path-to-file--prefix server的作用是指定 npm 在server/目录下执行脚本对应源码中的test脚本为NODE_ENVtest ... jest --config jest.config.ts而path-to-file会透传给 Jest 作为匹配路径。Docker VSCode 联合调试仓库为 Docker 开发环境内置了一整套 VSCode 调试配置无需改动源码即可对容器内的前后端打断点、观察变量。调试基础设施.vscode/launch.json新增了Docker Debug Client与Docker Debug Server两个启动配置分别用于在容器中调试前端与后端.vscode/tasks.json管理调试场景下的 docker compose 命令任务可一键以 detached后台模式启动 client/server 容器docker-compose-debug.yaml调试用 compose overlay核心是为server增加宿主机 9229 端口映射并把启动命令切换为带调试参数的npm run --prefix server start:debug -- --debug 0.0.0.0:9229使 NestJS 以 Node 调试模式监听 9229。启动调试会话以调试模式启动全部服务基础编排文件 调试覆盖文件叠加docker-compose -f docker-compose.yaml -f docker-compose-debug.yaml up --build随后在 VSCode 中操作用 VSCode 打开 ToolJet 项目目录点击左侧活动栏的Run and Debug调试图标进入调试视图在启动配置下拉框中按需选择Docker Debug Server后端或Docker Debug Client前端点击运行即可挂载调试器。该方案的价值在于把断点调试能力从宿主机延伸到容器内你可以在 server 的 NestJS 控制器、服务或拦截器中直接打断点配合 VSCode 的实时变量检查、调用栈与单步执行定位问题统一、可版本化的调试配置也让团队成员共享同一套开发体验降低了新人上手门槛。常见问题排查如果在本地启动 ToolJet 过程中遇到构建失败、容器启动异常或数据库连接问题建议按以下顺序自查确认.env必备密钥已生成重跑./deploy/docker/internal.sh可安全补齐缺失项确认本机 5432/6379/8082/3000 等端口未被其他进程占用确认数据库迁移已执行、.env.test已为测试环境正确创建若改动涉及 Dockerfile 或 compose 编排务必执行docker compose build后再up避免使用陈旧镜像。若上述排查仍无法解决可在项目的 GitHub Issues 提交新 issue或加入 ToolJet 的 Slack 社区获取帮助反馈时请附上.env脱敏后的配置、docker compose 日志与复现步骤。小结借助仓库自带的 docker-compose.yaml 与三份.env/ Dockerfile 模板贡献者只需cp internal.sh compose up三步即可获得一个带数据库、缓存、REST 网关与前后端热重载的完整开发环境。结合.env.test测试库、docker compose run的测试命令以及docker-compose-debug.yaml提供的 9229 调试端口整套工作流覆盖了写代码 → 热更新 → 自动化测试 → 断点调试的贡献闭环可帮助你在不污染本机 Node/PostgreSQL 环境的前提下高效参与 ToolJet 开发。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet 本地开发环境搭建指南：用 Docker Compose 实现服务编排、热重载与 VSCode 调试
ToolJet 本地开发环境搭建指南用 Docker Compose 实现服务编排、热重载与 VSCode 调试【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本文是面向ToolJet 贡献者的本地开发环境搭建指南围绕 Docker Compose 讲解如何一键拉起 ToolJet 的前端client、后端server、插件构建plugins、PostgreSQL、Redis 与 PostgREST 全栈服务。读完本文你将掌握从克隆仓库、生成安全密钥到启动开发容器、运行单元 / e2e 测试以及在 VSCode 中远程调试 Docker 内 Node.js 服务的完整流程。适用范围说明本文流程面向开发 / 贡献场景若你只是想在本地或服务器上部署运行 ToolJet自托管请参照仓库中的 Setup 章节其中包含 Docker、Kubernetes、Helm 等多种部署路径如果只是快速体验可先阅读 Try ToolJet。前置条件在开始之前请确保本机已安装最新版本的docker与docker compose插件Docker Desktop 自带 compose 子命令Linux 环境需单独安装 compose plugin。Windows 用户特别注意建议使用 Docker Desktop 的 WSL2 后端并且所有命令必须在WSL2 终端中执行而不是 PowerShell 或 CMD。同时由于 Windows 默认行尾符为 CRLF从deploy/docker/.env.internal.example复制生成的.env文件需要把行尾符调整为LF否则环境变量解析会出错。仓库根目录的 docker-compose.yaml 是本次开发环境的服务编排核心共定义 6 个服务plugins、client、server、redis、postgrest、postgres。启动后的端口映射如下服务容器内监听宿主机映射作用client80828082ToolJet 前端webpack dev serverserver30003000ToolJet NestJS 后端 APIpostgrest30003001PostgREST为 ToolJet Database 提供 REST 接口postgres54325432主数据库服务端数据redis63796379缓存与队列支持其中server通过depends_on依赖postgres、redis、postgrest且其容器环境变量中把REDIS_HOSTredis、PG_HOSTpostgres、PGRST_HOSTpostgrest直接指向 compose 服务名即容器间通过服务名互联。本地开发环境搭建步骤1. Fork 并克隆仓库以 GitHub 协作模式为例先进入上游 ToolJet 仓库页面点击Fork按钮在自己账号下生成一份副本随后把这份 fork 克隆到本地git clone your-forked-tooljet-repo-url cd ToolJet2. 准备 .env 环境变量文件ToolJet 在启动时需要大量环境变量数据库连接、加密密钥、SSO 配置等。本地开发用的是内部internal环境模板将其复制为项目根目录的.envcp ./deploy/docker/.env.internal.example .env模板文件本身位于 deploy/docker/.env.internal.example其中已预置了TOOLJET_HOSThttp://localhost:8082、数据库名、PGRST_HOSTpostgrest等开发默认值。更完整的变量说明含生产部署所需项可查阅仓库文档 env-vars.md。3. 用脚本自动填充安全密钥.env中以下几项属于必须安全随机生成的敏感密钥逐个手写既不安全也易出错LOCKBOX_MASTER_KEYToolJet 用于加密数据源凭据等敏感信息的 Lockbox 主密钥SECRET_KEY_BASE用于会话与签名等安全操作的密钥基PGRST_JWT_SECRETPostgREST 签发/校验 JWT 的密钥PG_PASS/TOOLJET_DB_PASSPostgreSQL 用户密码。官方提供了一个一键填充脚本直接执行即可chmod x ./deploy/docker/internal.sh ./deploy/docker/internal.sh从源码看deploy/docker/internal.sh 的逻辑非常清晰先source .env加载现有配置然后逐一检查上述键值是否为空为空则调用openssl rand生成并回写.envLOCKBOX_MASTER_KEY用openssl rand -hex 3264 位十六进制SECRET_KEY_BASE用openssl rand -hex 64128 位十六进制PGRST_JWT_SECRET用openssl rand -hex 32PG_PASS与TOOLJET_DB_PASS通过openssl rand -base64 12处理后截取 16 位最后根据生成的密码拼接出PGRST_DB_URI并回写。也就是说这个脚本是幂等的若相应键已存在则跳过打印提示可安全重复执行。4. 构建开发镜像并启动先构建镜像。由于 compose 中的client、server、plugins三个服务都使用仓库根目录作为构建上下文context: ./首次构建需要拉取基础镜像并安装 npm 依赖耗时较长docker compose build docker compose run --rm plugins npm run build:plugins第二条命令以一次性容器方式先构建插件包plugins产物供 server/client 使用。三个开发镜像分别由 docker/client.Dockerfile.dev、docker/server.Dockerfile.dev、docker/plugins.Dockerfile.dev 定义均基于node:22.15.1-bullseye并通过NODE_OPTIONS--max-old-space-size4096提高 Node 堆内存上限以避免前端构建、服务编译时内存溢出。随后启动全部服务docker compose up等 client 的 webpack dev server 与 server 的 NestJS watch 模式就绪后在浏览器访问http://localhost:8082即可看到 ToolJet 界面首次访问会引导创建管理员账号。需要停止开发环境时docker compose stopstop只是暂停容器数据卷postgres、redis保留下次docker compose up可快速恢复现场。代码改动与容器热重载开发镜像把宿主目录以 volume 方式挂载进容器client 挂载./frontend与./plugins运行npm run --prefix frontend startwebpack dev serverserver 挂载./server、./plugins以及根目录的.env/.env.test运行npm run --prefix server start:devNestJS watch 模式。因此修改前端或后端代码后对应容器会自动热重载无需手动重启。但以下两类变更需要额外处理涉及数据库迁移或新增 npm 依赖如果改动包含 TypeORM migration或在package.json中新增了依赖包需要重启 server 容器使新代码/依赖生效docker compose restart server需要为容器内新增系统级依赖若新增的功能要求安装某个二进制工具或系统库例如图像处理命令imagemagick就必须修改 docker/server.Dockerfile.dev在apt-get install列表中追加依赖然后重建镜像并重启docker compose build server docker compose up以文档中的示例为例改造后的 Dockerfile 大致形态如下原文档中该示例基于node:18.18.2-buster请注意当前仓库的 server 开发镜像实际基线为node:22.15.1-bullseye实践时应以仓库内现有 Dockerfile 为基准仅追加你需要的 apt 包FROM node:22.15.1-bullseye AS builder RUN apt-get update apt-get install -y \ build-essential \ postgresql-client \ freetds-dev \ libaio1 \ imagemagick RUN mkdir -p /app WORKDIR /app COPY ./server/package.json ./server/package-lock.json ./server/ RUN npm --prefix server install ENV NODE_ENVdevelopment COPY ./server/ ./server/ COPY ./docker/ ./docker/ COPY ./.env ../.env RUN [chmod, 755, entrypoint.sh]保存后依次执行docker compose build server与docker compose up新容器即包含imagemagick。在 Docker 中运行测试测试环境配置来自项目根目录的.env.test文件与.env相互独立。先创建并迁移测试数据库docker compose run --rm -e NODE_ENVtest server npm run db:create docker compose run --rm -e NODE_ENVtest server npm run db:migrate这些命令实际对应 server/package.json 中的脚本db:create调用ts-node ./scripts/create-database.tsdb:migrate依次执行 schema migration基于 TypeORM CLI与 data migration。运行单元测试docker compose run --rm server npm run --prefix server test运行 e2e端到端测试docker compose run --rm server npm run --prefix server test:e2e只运行某个特定的单元测试文件docker compose run --rm server npm --prefix server run test path-to-file--prefix server的作用是指定 npm 在server/目录下执行脚本对应源码中的test脚本为NODE_ENVtest ... jest --config jest.config.ts而path-to-file会透传给 Jest 作为匹配路径。Docker VSCode 联合调试仓库为 Docker 开发环境内置了一整套 VSCode 调试配置无需改动源码即可对容器内的前后端打断点、观察变量。调试基础设施.vscode/launch.json新增了Docker Debug Client与Docker Debug Server两个启动配置分别用于在容器中调试前端与后端.vscode/tasks.json管理调试场景下的 docker compose 命令任务可一键以 detached后台模式启动 client/server 容器docker-compose-debug.yaml调试用 compose overlay核心是为server增加宿主机 9229 端口映射并把启动命令切换为带调试参数的npm run --prefix server start:debug -- --debug 0.0.0.0:9229使 NestJS 以 Node 调试模式监听 9229。启动调试会话以调试模式启动全部服务基础编排文件 调试覆盖文件叠加docker-compose -f docker-compose.yaml -f docker-compose-debug.yaml up --build随后在 VSCode 中操作用 VSCode 打开 ToolJet 项目目录点击左侧活动栏的Run and Debug调试图标进入调试视图在启动配置下拉框中按需选择Docker Debug Server后端或Docker Debug Client前端点击运行即可挂载调试器。该方案的价值在于把断点调试能力从宿主机延伸到容器内你可以在 server 的 NestJS 控制器、服务或拦截器中直接打断点配合 VSCode 的实时变量检查、调用栈与单步执行定位问题统一、可版本化的调试配置也让团队成员共享同一套开发体验降低了新人上手门槛。常见问题排查如果在本地启动 ToolJet 过程中遇到构建失败、容器启动异常或数据库连接问题建议按以下顺序自查确认.env必备密钥已生成重跑./deploy/docker/internal.sh可安全补齐缺失项确认本机 5432/6379/8082/3000 等端口未被其他进程占用确认数据库迁移已执行、.env.test已为测试环境正确创建若改动涉及 Dockerfile 或 compose 编排务必执行docker compose build后再up避免使用陈旧镜像。若上述排查仍无法解决可在项目的 GitHub Issues 提交新 issue或加入 ToolJet 的 Slack 社区获取帮助反馈时请附上.env脱敏后的配置、docker compose 日志与复现步骤。小结借助仓库自带的 docker-compose.yaml 与三份.env/ Dockerfile 模板贡献者只需cp internal.sh compose up三步即可获得一个带数据库、缓存、REST 网关与前后端热重载的完整开发环境。结合.env.test测试库、docker compose run的测试命令以及docker-compose-debug.yaml提供的 9229 调试端口整套工作流覆盖了写代码 → 热更新 → 自动化测试 → 断点调试的贡献闭环可帮助你在不污染本机 Node/PostgreSQL 环境的前提下高效参与 ToolJet 开发。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考