Add instructions for building Next.js client with SSG locally in Docker Compose (#1918)

* docs(deployment/docker-compose.md): Add a section Building Next.js client locally with SSG

Added detailed instructions for building a Next.js client with Static Site Generation (SSG) in a Docker Compose environment. The steps include adjustments to the compose.prod.yaml file, starting the php service container, optional creation of a .env file for the Next.js client, building the pwa service, and finally bringing up the full project. This setup ensures the Next.js client can access the API at build time for static page generation.

* docs(create-client/nextjs.md): Generating a production build locally with docker compose

Updated the Next.js documentation to include instructions for generating a production build locally using Docker Compose. The update provides a link to the detailed steps in the Docker Compose deployment guide.

* docs(deployment/kubernetes.ms): Added Docker build command for SSG in Kubernetes doc

Added optional Docker build command for SSG projects in Kubernetes doc. This command allows the PWA to access a locally running API during the build process, useful for generating static pages at build time.

* docs(deployement/docker-compose): add a step to override the php env variables

To ensure TRUSTED_HOSTS and MERCURE_PUBLIC_URL remain valid when altering SERVER_NAME to use an HTTP scheme or include a port, these variables must be overridden. This adjustment accommodates configurations where SERVER_NAME deviates from the standard HTTPS format or includes port specifications.

* docs(deployement/docker-compose): adapt docs for variables update

---------

Co-authored-by: JH <[email protected]>

Author: J3m5

create-client/nextjs.md

@@ -98,6 +98,10 @@ yarn dev
 
 Go to `http://localhost:3000/books/` to start using your app.
 
+## Generating a production build locally with docker compose
+
+If you want to generate a production build locally with docker compose, follow [these instructions](../deployment/docker-compose.md)
+
 ## Screenshots
 
 ![List](images/nextjs/create-client-nextjs-list.png)

deployment/docker-compose.md

@@ -89,8 +89,10 @@ Go to `https://your-domain-name.example.com` and enjoy!
 
 Alternatively, if you don't want to expose an HTTPS server but only an HTTP one, run the following command:
 
-```console
-SERVER_NAME=:80 \
+```bash
+SERVER_NAME=http://localhost \
+MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
+TRUSTED_HOSTS='^localhost|php$' \
 APP_SECRET=ChangeMe \
 CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \
 docker compose -f -compose.yaml -f compose.prod.yaml up --wait
@@ -114,3 +116,66 @@ As a shortcut, `private_ranges` may be configured to trust all private IP ranges
 +    trusted_proxies private_ranges
 +}
 ```
+
+## Building Next.js client locally with SSG
+
+When deploying API Platform with Docker Compose and you need to build a Next.js client that utilizes Static Site Generation (SSG), a specific setup is required.  
+This setup ensures the Next.js client can access the API at build time to generate static pages.
+
+### Configuration Steps
+
+#### 1. Adjust the compose.prod.yaml file
+
+Modify the pwa service to ensure network communication between the pwa and php services during the build:
+
+```yaml
+  pwa:
+    build:
+      context: ./pwa
+      target: prod
+      network: host
+      extra_hosts:
+        - php=127.0.0.1
+```
+
+#### 2. Build and start the php service
+
+Begin by starting the php service container:
+
+```bash
+SERVER_NAME=http://localhost \
+MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
+TRUSTED_HOSTS='^localhost|php$' \
+APP_SECRET=!ChangeMe! \
+CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \
+POSTGRES_PASSWORD=!ChangeMe! \
+docker compose -f compose.yaml -f compose.prod.yaml up -d --build --wait php
+```
+
+#### 3. Optional: Env file with create-client
+
+If your are using the [create-client](../create-client/nextjs.md) generator inside your Next.js client, you need to create a `.env` file in the `pwa` directory with the `NEXT_PUBLIC_ENTRYPOINT` environment variable to ensure the Next.js client knows where to find the API:
+
+```dotenv
+NEXT_PUBLIC_ENTRYPOINT=http://php
+```
+
+#### 4. Build the pwa service
+
+```bash
+docker compose -f compose.yaml -f compose.prod.yaml build pwa
+```
+
+#### 5. Finally, bring up the full project
+
+```bash
+SERVER_NAME=http://localhost \
+MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
+TRUSTED_HOSTS='^localhost|php$' \
+APP_SECRET=!ChangeMe! \
+CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \
+POSTGRES_PASSWORD=!ChangeMe! \
+docker compose -f compose.yaml -f compose.prod.yaml up -d --wait
+```
+
+These steps ensure the Next.js client can statically generate pages by accessing the API during the build process.

deployment/kubernetes.md

@@ -44,6 +44,12 @@ docker build -t gcr.io/test-api-platform/caddy:0.1.0 -t gcr.io/test-api-platform
 docker build -t gcr.io/test-api-platform/pwa:0.1.0 -t gcr.io/test-api-platform/pwa:latest pwa --target prod
 ```
 
+Optional: If your pwa project use Static Site Generation (SSG) and you need to build it against the API running locally, you can build the pwa with the command below.
+
+```bash
+docker build -t gcr.io/test-api-platform/pwa:0.1.0 -t gcr.io/test-api-platform/pwa:latest pwa --target prod --network=host --add-host php=127.0.0.1
+```
+
 #### 2. Push your images to your Docker registry
 
 ```console
@@ -53,12 +59,12 @@ docker push gcr.io/test-api-platform/caddy
 docker push gcr.io/test-api-platform/pwa
 ```
 
-Optional push the version images:
+Optional: push the version images:
 
 ```console
-docker push gcr.io/test-api-platform/php:0.1.0 
-docker push gcr.io/test-api-platform/caddy:0.1.0 
-docker push gcr.io/test-api-platform/pwa:0.1.0 
+docker push gcr.io/test-api-platform/php:0.1.0
+docker push gcr.io/test-api-platform/caddy:0.1.0
+docker push gcr.io/test-api-platform/pwa:0.1.0
 ```
 
 The result should look similar to these images.
@@ -114,7 +120,7 @@ Replace the values with the image parameters from the stage above.
 The parameter `php.appSecret` is the `AppSecret` from ./.env
 Fill the rest of the values with the correct settings.
 For available options see /helm/api-platform/values.yaml.
-If you want a test deploy you can set corsAllowOrigin='*'
+If you want a test deploy you can set corsAllowOrigin='\*'
 
 After a successful installation, there is a message at the end.
 You can copy these commands and execute them to set a port-forwarding and
@@ -166,7 +172,7 @@ You can upgrade with the same command from the installation and pass all paramet
 ### 2. Use :latest tags
 
 Infos about [best practices for tagging images for Kubernetes](https://kubernetes.io/docs/concepts/containers/images/)
-You have to use the *.image.pullPolicy=Always see the last 3 parameters.
+You have to use the \*.image.pullPolicy=Always see the last 3 parameters.
 
 ```console
 PHP_POD=$(kubectl --namespace=bar get pods -l app=php -o jsonpath="{.items[0].metadata.name}")