Deploying with Docker
This documentation has not yet been tested with PostGraphile V5. Please get in touch if you have used it!
本文档尚未在 PostGraphile V5 中经过完整实测。如果你已在实际项目中使用过相关方案,欢迎与我们联系反馈!
PostGraphile has an official Docker image which is suitable to use if you don't need custom plugins and are deploying PostGraphile as standalone:
如果你不需要自定义插件,且希望独立部署 PostGraphile,可以直接使用官方 Docker 镜像:
Our Docker images are versioned:
官方 Docker 镜像按以下规则进行版本标记:
-
graphile/postgraphile:5will give you the latest stable in the "v5.x.x" line (no alphas, betas, rcs); this is the recommended version to usegraphile/postgraphile:5指向“v5.x.x”分支中最新的稳定版(不包含 alpha、beta、rc 版本);推荐优先使用该标签 -
Every new versioned git tag will be available using the exact same tag; e.g.
v5.6.7-alpha.8would becomegraphile/postgraphile:v5.6.7-alpha.8每个带版本号的新 git tag 都会对应生成一个同名镜像标签;例如
v5.6.7-alpha.8会发布为graphile/postgraphile:v5.6.7-alpha.8 -
Every new
vX.Y.Zgit tag (i.e. no alpha/beta/rc) will automatically releasegraphile/postgraphile:X-Yandgraphile/postgraphile:X-Y-Z每个正式版
vX.Y.Zgit tag(即不含 alpha/beta/rc 后缀)都会自动发布graphile/postgraphile:X-Y与graphile/postgraphile:X-Y-Z两个镜像标签 -
graphile/postgraphile:latestwill give you the latest stable (but beware of major version bumps!)graphile/postgraphile:latest指向最新的稳定版(但请注意,它可能会跨越主版本升级!) -
graphile/postgraphile:nextwill give you the equivalent of what's onmasterright now (i.e. pre-release/bleeding edge/nightly)graphile/postgraphile:next对应master分支的当前最新代码(即预发布 / 前沿构建 / nightly 版本)
From time to time graphile/postgraphile:5 may lag behind where it should be
because it's the only manual step in the above. If this happens, give Benjie a
poke over Discord and he'll push the latest v5.x.y tag to the v5 branch via
git push origin v5.x.y:v5.
由于上述流程中只有 graphile/postgraphile:5 需要手动更新,它偶尔可能会稍微滞后于最新版本。如果遇到这种情况,可以在 Discord 上提醒 Benjie,他会通过 git push origin v5.x.y:v5 将最新的 v5.x.y 标签推送到 v5 分支。
A request was made for clarification on why there are Docker versions with dots and other Docker versions with dashes; hopefully this clears things up:
曾有用户询问为什么有些 Docker 标签使用点号(.)而另一些使用短横线(-),这里统一说明一下:
-
XandX-Yare the versions that you should use, they will be updated over time with compatible bug fixes.X和X-Y是日常推荐使用的标签,它们会随着兼容的 Bug 修复持续更新。 -
X-Y-Zfor completeness, and may include alpha/beta/etc versions of that specific release in futureX-Y-Z用于补全具体小版本标签,未来可能会包含该特定版本的 alpha/beta 等预发布构建 -
vX.Y.Z-foo.Aor whatever are the explicit git tags which will only ever build once and will not be kept up to date as the project advances. Use these if you need to pin an explicit version... explicitly.vX.Y.Z-foo.A等对应精确的 git tag,它们只会构建一次,之后不会随项目推进而更新。当你需要严格锁定到某个精确版本时,可以使用这类标签。
Custom Dockerfile自定义 Dockerfile
Should you want to deploy a more custom app then a custom Dockerfile is likely in order. To reduce the size of your final image, we recommend using a multi-stage build.
如果你需要部署高度定制化的应用,通常需要编写自定义 Dockerfile。为了减小最终镜像体积,建议采用多阶段构建(multi-stage build)。
There's a few critical things to keep in mind:
有几个关键细节需要注意:
-
PostGraphile CLI listens, by default, on
localhost; you may need to override this, e.g. withpreset.grafserv.host = "0.0.0.0"PostGraphile CLI 默认仅监听
localhost;在容器环境中通常需要覆盖此配置,例如设置preset.grafserv.host = "0.0.0.0" -
PostGraphile needs to be able to connect to your database; ensure that Docker is networked such that this is possible
PostGraphile 必须能够访问你的数据库;请确保 Docker 网络配置允许容器连接到数据库服务
To speed up builds, we recommend you pay attention to your .dockerignore file;
here's an example to get you started:
为了加快构建速度,建议合理配置 .dockerignore 文件,以下是一个基础示例:
# .dockerignore
.env
.git
.github
.next
.vscode
node_modules
*Dockerfile*
*docker-compose*
**/dist
**/__tests__
The content of your Dockerfile will vary greatly depending on your repository
setup, but here's an example for inspiration, using Yarn v4:
Dockerfile 的具体写法会因仓库结构而异,下面给出一个基于 Yarn v4 的参考示例:
# Dockerfile
# Global args, set before the first FROM, shared by all stages
ARG NODE_ENV="production"
ARG GRAPHILE_ENV="production"
################################################################################
# Build stage 1 - `yarn build`
FROM node:24-alpine AS builder
# Import our shared args
ARG NODE_ENV
ARG GRAPHILE_ENV
# Cache node_modules for as long as possible
COPY .yarn/ /app/.yarn/
COPY .yarnrc.yml package.json yarn.lock tsconfig.json /app/
WORKDIR /app/
RUN ["corepack", "enable"]
RUN ["yarn", "install", "--immutable"]
# Copy over the server source code
COPY src/ /app/src/
# Finally run the build script
RUN ["yarn", "run", "build"]
################################################################################
# Build stage 2 - COPY the relevant things (multiple steps)
FROM node:24-alpine AS clean
# Import our shared args
ARG NODE_ENV
ARG GRAPHILE_ENV
# Copy over selectively just the tings we need, try and avoid the rest
COPY /app/.yarnrc.yml /app/package.json /app/yarn.lock /app/
COPY /app/.yarn/releases/ /app/.yarn/releases/
COPY /app/dist/ /app/dist/
################################################################################
# Build stage FINAL - COPY everything, once, and then do a clean `yarn install`
FROM node:24-alpine
# Import our shared args
ARG NODE_ENV
ARG GRAPHILE_ENV
EXPOSE 5678
WORKDIR /app/
# Copy everything from stage 2, it's already been filtered
COPY /app/ /app/
# Install yarn ASAP because it's the slowest
RUN ["corepack", "enable"]
RUN ["yarn", "workspaces", "focus", "-A", "--production"]
LABEL description="My PostGraphile-powered server"
ENV HOST="0.0.0.0"
ENV NODE_ENV=$NODE_ENV
ENV GRAPHILE_ENV=$GRAPHILE_ENV
ENTRYPOINT ["yarn", "start:production"]
Build via:
使用以下命令构建镜像:
docker build -t mypostgraphileproject .
This builds the Docker image from the Dockerfile in the current directory, and tags it as mypostgraphileproject.
该命令会基于当前目录中的 Dockerfile 构建镜像,并为其打上 mypostgraphileproject 标签。
Run via:
使用以下命令运行容器:
docker run \
--rm \
-it \
-p 5678:5678 \
-e DATABASE_URL="postgres://username:password@host:port/db" \
mypostgraphileproject
-
--rmremoves the container automatically when it exits--rm:容器退出时自动清理删除 -
-itruns the container interactively with TTY attached, useful for logs and Ctrl-C-it:以交互式终端(TTY)模式运行容器,方便查看实时日志以及使用 Ctrl-C 中止 -
-p 5678:5678publishes port 5678 from the container to port 5678 on the host-p 5678:5678:将容器内的 5678 端口映射到宿主机的 5678 端口 -
-e DATABASE_URL=…sets the database connection string at runtime-e DATABASE_URL=…:在运行时设置数据库连接字符串 -
mypostgraphileprojectis the image to run (named via-tin thedocker buildcommand abovemypostgraphileproject:指定要运行的镜像名称(即前面docker build命令中通过-t指定的名称)
See it working in benjie/ouch.
可在 benjie/ouch 中查看实际运行效果。
Use the docker argument --add-host=host.docker.internal:host-gateway and the
connection string postgres://username:password@host.docker.internal/mydb to
connect to the mydb db on the host machine. For this to work, you'll also need
to ensure your listen_address is set correctly:
如果数据库运行在宿主机上,可在 Docker 中传入 --add-host=host.docker.internal:host-gateway 参数,并使用连接字符串 postgres://username:password@host.docker.internal/mydb 来连接宿主机的 mydb 数据库。此外,还需要确保 PostgreSQL 的 listen_address 配置正确:
# ...
listen_address = 'localhost,172.17.0.1'
port = 5432
# ...
And you may need to restart PostgreSQL after you've started the Docker daemon so that the port binds correctly.
同时,在启动 Docker 守护进程后,你可能需要重启一次 PostgreSQL,以确保监听端口正常绑定。