docs: Clarify how to setup Docker with custom Server File (#10702)

Clarify how to setup Docker with custom Server File.

While the Docker documentation does instruct how to user Docker with the
custom server file, the instructions could be easily missed.

In the follow support issue
https://community.redwoodjs.com/t/unknown-directive-live-in-docker/7150/7
redwoodJS was setup to use Docker and also GraphQL with Realtime.

Realtime (and live queries) worked with rw dev, api set and also Docker
dev -- but not production Docker.

In production Docker, the server file was never run and therefore the
plugin to setup GraphQL with the useRedwoodRealtime plugin never
happened ... and thus the live directive wasn't understood nor were
GraphQL subscripts added to the schema.

Here api server, simply ran the GraphQL function as expected, but the
plugin was never invoked so Realtime was never configured or added to
the schema.

This happened because by default, production Docker launch the plain
vanilla api server -- it didn't launch server file that uses
`createServer` to setup a separate GraphQL server and also add in the
realtime plugin.

This PR:

* adds comment to the Dockerfile to make one aware of the command change
* suggests an alternative way of not using the default command in the
production docker config
* clarifies Docker docs to point to the config command change

.changesets/10702.md

@@ -0,0 +1,15 @@
+- docs(docker): Clarify how to setup Docker with custom Server File (#10702) by @dthyresson
+
+Clarify how to setup Docker with custom Server File.
+
+While the Docker documentation does instruct how to user Docker with the custom server file, the instructions could be easily missed.
+
+In the follow support issue https://community.redwoodjs.com/t/unknown-directive-live-in-docker/7150/7 redwoodJS was setup to use Docker and also GraphQL with Realtime.
+
+Realtime (and live queries) worked with rw dev, api set and also Docker dev -- but not production Docker.
+
+In production Docker, the server file was never run and therefore the plugin to setup GraphQL with the useRedwoodRealtime plugin never happened ... and thus the live directive wasn't understood nor were GraphQL subscripts added to the schema.
+
+Here api server, simply ran the GraphQL function as expected, but the plugin was never invoked so Realtime was never configured or added to the schema.
+
+This happened because by default, production Docker launch the plain vanilla api server  -- it didn't launch server file that uses `createServer` to setup a separate GraphQL server and also add in the realtime plugin.

docs/docs/docker.md

@@ -55,7 +55,11 @@ docker compose -f ./docker-compose.dev.yml run --rm -it console /bin/bash
 root@...:/home/node/app# yarn rw prisma migrate dev
 ```
 
-## The Dockerfile in detail
+:::important 
+If you are using a [Server File](#using-the-server-file) then you should [change the command](#command) that runs the `api_serve` service.
+:::
+
+## Dockerfile
 
 The documentation here goes through and explains every line of Redwood's Dockerfile.
 If you'd like to see the whole Dockerfile for reference, you can find it [here](https://github.com/redwoodjs/redwood/tree/main/packages/cli/src/commands/experimental/templates/docker/Dockerfile) or by setting it up in your project: `yarn rw experimental setup-docker`.
@@ -256,21 +260,37 @@ Here's where we really take advantage of multi-stage builds by copying from the
 At this point all the building has been done. Now we can just grab the artifacts without having to lug around the dev dependencies.
 
 There's one more thing that was built: the prisma client in `node_modules/.prisma`.
-We need to grab it too.
+We need to grab it, too.
+
+Lastly, the default command is to start the api server using the bin from the `@redwoodjs/api-server` package.
+You can override this command if you have more specific needs.
 
 ```Dockerfile
 ENV NODE_ENV=production
 
+# default api serve command
+# ---------
+# If you are using a custom server file, you must use the following
+# command to launch your server instead of the default api-server below.
+# This is important if you intend to configure GraphQL to use Realtime.
+#
+# CMD [ "./api/dist/server.js" ]
 CMD [ "node_modules/.bin/rw-server", "api" ]
 ```
 
-Lastly, the default command is to start the api server using the bin from the `@redwoodjs/api-server` package.
-You can override this command if you have more specific needs.
+:::important 
+If you are using a [Server File](#using-the-server-file) then you must change the command that runs the `api_serve` service to `./api/dist/server.js` as shown above.
+
+Not updating the command will not completely configure the GraphQL Server and not setup [Redwood Realtime](./realtime.md), if you are using that.
+:::
+
 
 Note that the Redwood CLI isn't available anymore. (It's a dev dependency.)
 To access the server bin, we have to find its path in `node_modules`.
 Though this is somewhat discouraged in modern yarn, since we're using the `node-modules` node linker, it's in `node_modules/.bin`.
 
+
+
 ### The `web_build` stage
 
 This `web_build` builds the web side:
@@ -508,27 +528,35 @@ With the server file, there's no indirection. Just use `node`:
 yarn node api/dist/server.js
 ```
 
-:::info You have to build first
+### Building
 
 You can't run the server file directly with Node.js; it has to be built first:
 
+
 ```
 yarn rw build api
 ```
 
 The api serve stage in the Dockerfile pulls from the api build stage, so things are already in the right order there. Similarly, for `yarn rw dev`, the dev server will build and reload the server file for you. 
 
-:::
 
-That means you can swap the `CMD` instruction in the api server stage:
+### Command
+
+That means you will swap the `CMD` instruction in the api server stage:
 
 ```diff
   ENV NODE_ENV=production
 
 - CMD [ "node_modules/.bin/rw-server", "api" ]
-+ CMD [ "yarn", "node", "api/dist/server.js" ]
++ CMD [ "api/dist/server.js" ]
 ```
 
+:::important 
+If you are using a [Server File](#using-the-server-file) then you must change the command that runs the `api_serve` service to `./api/dist/server.js` as shown above.
+
+Not updating the command will not completely configure the GraphQL Server and not setup [Redwood Realtime](./realtime.md), if you are using that.
+:::
+
 ### Configuring the server
 
 There's two ways you can configure the server.

packages/cli/src/commands/experimental/templates/docker/Dockerfile

@@ -94,8 +94,16 @@ COPY --chown=node:node --from=api_build /home/node/app/node_modules/.prisma /hom
 
 ENV NODE_ENV=production
 
+# default api serve command
+# ---------
+# If you are using a custom server file, you must use the following
+# command to launch your server instead of the default api-server below.
+# This is important if you intend to configure GraphQL to use Realtime.
+#
+# CMD [ "./api/dist/server.js" ]
 CMD [ "node_modules/.bin/rw-server", "api" ]
 
+
 # web serve
 # ---------
 FROM node:20-bookworm-slim as web_serve

packages/cli/src/commands/experimental/templates/docker/docker-compose.prod.yml

@@ -6,6 +6,11 @@ services:
       context: .
       dockerfile: ./Dockerfile
       target: api_serve
+    # Without a command specified, the Dockerfile's api_serve CMD will be used.
+    # If you are using a custom server file, you should either use the following
+    # command to launch your server or update the Dockerfile to do so.
+    # This is important if you intend to configure GraphQL to use Realtime.
+    # command: "./api/dist/server.js"
     ports:
       - "8911:8911"
     depends_on: