Add instructions for building Next.js client with SSG locally in Docker Compose

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}")