Development Quickstart

July 3, 2025 ยท View on GitHub

This guide will assist you in setting up your development environment for NGINX Gateway Fabric, covering the steps to build, install, and execute tasks necessary for submitting pull requests. By following this guide, you'll have a fully prepared development environment that allows you to contribute to the project effectively.

Table of Contents

Setup Your Development Environment

Follow these steps to set up your development environment.

  1. Install:

    go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest

    brew install pre-commit

  2. Fork the project repository

  3. Clone your repository with ssh, and install the project dependencies:

    git clone git@github.com:<YOUR-USERNAME>/nginx-gateway-fabric.git
cd nginx-gateway-fabric

    and then run

    pre-commit install

    in the project root directory to install the git hooks.

    make deps

  4. Finally, add the original project repository as the remote upstream:

    git remote add upstream git@github.com:nginx/nginx-gateway-fabric.git

Build the Binary and Images

Setting GOARCH

The Makefile uses the GOARCH variable to build the binary and container images. The default value of GOARCH is amd64.

If you are deploying NGINX Gateway Fabric on a kind cluster, and the architecture of your machine is not amd64, you will want to set the GOARCH variable to the architecture of your local machine. You can find the value of GOARCH by running go env. Export the GOARCH variable in your ~/.zshrc or ~/.bashrc.

echo "export GOARCH=< Your architecture (e.g. arm64 or amd64) >" >> ~/.bashrc
source ~/.bashrc

or for zsh:

echo "export GOARCH=< Your architecture (e.g. arm64 or amd64) >" >> ~/.zshrc
source ~/.zshrc

Build the Binary

To build the binary, run the make build command from the project's root directory:

make GOARCH=$GOARCH build

This command will build the binary and output it to the /build/.out directory.

Build the Images

To build the NGINX Gateway Fabric and NGINX container images from source run the following make command:

make GOARCH=$GOARCH TAG=$(whoami) build-images

This will build the docker images nginx-gateway-fabric:<your-user> and nginx-gateway-fabric/nginx:<your-user>.

Build the Images with NGINX Plus

Note: You will need a valid NGINX Plus license certificate and key named nginx-repo.crt and nginx-repo.key in the root of this repo to build the NGINX Plus image. You will also need a valid NGINX Plus JSON Web Token (JWT) to deploy NGF with NGINX Plus. That JWT should be stored in the license.jwt file in the root of the nginx-gateway-fabric/ directory. See the documentation for instructions on how to download and set up the JWT. Additionally, you need to set the NGINX Plus usage endpoint in your environment. For development and testing, export PLUS_USAGE_ENDPOINT=<N1 staging endpoint>.

To build the NGINX Gateway Fabric and NGINX Plus container images from source run the following make command:

make TAG=$(whoami) build-images-with-plus

This will build the docker images nginx-gateway-fabric:<your-user> and nginx-gateway-fabric/nginx-plus:<your-user>.

Deploy on Kind

  1. Create a kind cluster:

    To create a kind cluster with dual (IPv4 and IPv6) enabled:

    make create-kind-cluster

    To create a kind cluster with IPv6 or IPv4 only, edit kind cluster config located at nginx-gateway-fabric/config/cluster/kind-cluster.yaml:

    kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
networking:
  ipFamily: ipv6
  apiServerAddress: 127.0.0.1

  2. Load the previously built images onto your kind cluster:

    kind load docker-image nginx-gateway-fabric:$(whoami) nginx-gateway-fabric/nginx:$(whoami)

    or

    kind load docker-image nginx-gateway-fabric:$(whoami) nginx-gateway-fabric/nginx-plus:$(whoami)

  3. Install Gateway API CRDs:

    kubectl kustomize config/crd/gateway-api/standard | kubectl apply -f -

    If you're implementing experimental Gateway API features, install Gateway API CRDs from the experimental channel:

    kubectl kustomize config/crd/gateway-api/experimental | kubectl apply -f -

  4. Install NGF using your custom image and expose NGF with a NodePort Service:

    • To install with Helm (where your release name is my-release):

      helm install my-release ./charts/nginx-gateway-fabric --create-namespace --wait --set nginx.service.type=NodePort --set nginxGateway.image.repository=nginx-gateway-fabric --set nginxGateway.image.tag=$(whoami) --set nginxGateway.image.pullPolicy=Never --set nginx.image.repository=nginx-gateway-fabric/nginx --set nginx.image.tag=$(whoami) --set nginx.image.pullPolicy=Never -n nginx-gateway

    • To install NGINX Plus with Helm (where your release name is my-release):

      helm install my-release ./charts/nginx-gateway-fabric --create-namespace --wait --set nginx.service.type=NodePort --set nginxGateway.image.repository=nginx-gateway-fabric --set nginxGateway.image.tag=$(whoami) --set nginxGateway.image.pullPolicy=Never --set nginx.image.repository=nginx-gateway-fabric/nginx-plus --set nginx.image.tag=$(whoami) --set nginx.image.pullPolicy=Never --set nginx.plus=true -n nginx-gateway

    For more information on Helm configuration options see the Helm README.

    • To install with manifests:

      The mainifests files are genarated using Helm from the examples directory. To generate a custom one you can modify the values.yaml file in the example you want to use with the desired values and follow the instructions about manifests generation.

      If the only change is the image repository and tag, you can update the kustomization.yaml file in deploy/ with the desired values and deployment mainifest and run the following commands:

       kubectl apply --server-side -f deploy/crds.yaml
 kubectl kustomize deploy | kubectl apply -f -

For more information on how to use the manifests, see the deployment manifests documentation.

Run Examples

To make sure NGF is running properly, try out the examples.

Run the Unit Tests

To run all the unit tests, run the make unit-test command from the project's root directory:

make unit-test

For more details on testing, see the testing documentation.

Gateway API Conformance Testing

To run Gateway API conformance tests, please follow the instructions on this page.

Run the Linter

To lint the code, run the following make command from the project's root directory:

make lint

Note fieldalignment errors can be fixed by running: fieldalignment -fix <path-to-package>

Run the Helm Linter

Run the following make command from the project's root directory to lint the Helm Chart code:

make lint-helm

Update all the generated files

To update all the generated files, run the following make command from the project's root directory:

make generate-all