nginx

README

NGINX Server Cloud Native Buildpack

The NGINX buildpack provides the NGINX binary distribution. The buildpack installs the NGINX binary distribution onto the $PATH which makes it available for subsequent buildpacks and/or the application image.

The NGINX buildpack is compatible with the following builder(s):

• Paketo Full Builder
• Paketo Base Builder

Integration

The NGINX CNB provides nginx as a dependency. Downstream buildpacks, like PHP Web CNB can require the nginx dependency by generating a Build Plan TOML file that looks like the following:

[[requires]]

  # The name of the NGINX dependency is "nginx". This value is considered
  # part of the public API for the buildpack and will not change without a plan
  # for deprecation.
  name = "nginx"

  # The version of the NGINX dependency is not required. In the case it
  # is not specified, the buildpack will provide the default version, which can
  # be seen in the buildpack.toml file.
  # If you wish to request a specific version, the buildpack supports
  # specifying a semver constraint in the form of "1.*", "1.17.*", or even
  # "1.17.9".
  version = "1.17.9"

  # The NGINX buildpack supports some non-required metadata options.
  [requires.metadata]

    # Setting the launch flag to true will ensure that the NGINX
    # dependency is available on the $PATH for the running application. If you are
    # writing an application that needs to run NGINX at runtime, this flag should
    # be set to true.
    launch = true

Usage

To package this buildpack for consumption:

$ ./scripts/package.sh

Data driven templates

The NGINX buildpack supports data driven templates for nginx config. You can use templated variables like {{port}}, {{env "FOO"}} and {{module "ngx_stream_module"}} in your nginx.conf to use values known at launch time.

A usage example can be found in the samples repository under the nginx directory.

PORT

Use {{port}} to dynamically set the port at which the server will accepts requests. At launch time, the buildpack will read the value of $PORT to set the value of {{port}}.

For example, to set an NGINX server to listen on $PORT, use the following in your nginx.conf file:

server {
  listen {{port}};
}

Then run the built image using the PORT variable set as follows:

docker run --tty --env PORT=8080 --publish 8080:8080 my-nginx-image

Environment Variables

This is a generic case of the {{port}} directive described ealier. To use the value of any environment variable $FOOVAR available at launch time, use the directive {{env "FOOVAR"}} in your nginx.conf.

For example, include the following in your nginx.conf file to enable or disable gzipping of responses based on the value of GZIP_DOWNLOADS:

gzip {{env "GZIP_DOWNLOADS"}};

Then run the built image using the GZIP_DOWNLOADS variable set as follows:

docker run --tty --env PORT=8080 --env GZIP_DOWNLOADS=off --publish 8080:8080 my-nginx-image

Loading dynamic modules

You can use templates to set the path to a dynamic module using the load_module directive.

• To load a user-provided module named ngx_foo_module, provide a modules/ngx_foo_module.so file in your app directory and add the following to the top of your nginx.conf file:

{{module "ngx_foo_module"}}

• To load a buildpack-provided module like ngx_stream_module, add the following to the top of your nginx.conf file. You do not need to provide an ngx_stream_module.so file:

{{module "ngx_stream_module"}}

Configurations

Specifying the NGINX Server version through buildpack.yml configuration is deprecated and will not be supported in NGINX Server Buildpack v1.0.0.

To migrate from using buildpack.yml please set the following environment variables at build time either directly (ex. pack build my-app --env BP_ENVIRONMENT_VARIABLE=some-value) or through a project.toml file

BP_NGINX_VERSION

The BP_NGINX_VERSION variable allows you to specify the version of NGINX Server that is installed.

BP_NGINX_VERSION=1.21.0

This will replace the following structure in buildpack.yml:

nginx:
  # this allows you to specify a version constraint for the nginx dependency
  # any valid semver constraints (e.g. 1.* and 1.21.*) are also acceptable
  version: "1.21.0"

BP_WEB_SERVER_ENABLE_PUSH_STATE

The BP_WEB_SERVER_ENABLE_PUSH_STATE variable enables push state based routing for Single-page applications relying on browser history API. NGINX Server will send the content at / in response to any requested endpoint. Usefull for React, Angular, Vue and other SPAs.

BP_NGINX_STUB_STATUS_PORT

The BP_NGINX_STUB_STATUS_PORT variable exposes a handful of NGINX Server metrics via the stub_status module which provides basic status information on provided port. This comes handy for monitoring the server. For example using NGINX Prometheus Exporter

Documentation

Index

• Constants
• Variables
• func Build(config Configuration, dependencyService DependencyService, ...) packit.BuildFunc
• func Detect(config Configuration, versionParser VersionParser) packit.DetectFunc
• type BindingsResolver
• type BuildPlanMetadata
• type Calculator
• type ConfigGenerator
• type Configuration
  • func LoadConfiguration(environ []string, bindingsResolver BindingsResolver, platformPath string) (Configuration, error)
• type DefaultConfigGenerator
  • func NewDefaultConfigGenerator(logs scribe.Emitter) DefaultConfigGenerator
  • func (g DefaultConfigGenerator) Generate(config Configuration) error
• type DependencyService
• type Parser
  • func NewParser() Parser
  • func (p Parser) ParseYml(workingDir string) (string, bool, error)
  • func (p Parser) ResolveVersion(cnbPath, version string) (string, error)
• type SBOMGenerator
• type VersionParser

Constants

const (
	NGINX = "nginx"

	DepKey             = "dependency-sha"
	ConfigureBinKey    = "configure-bin-sha"
	ConfFile           = "nginx.conf"
	BuildpackYMLSource = "buildpack.yml"
)

Variables

var DefaultConfigTemplate string

var IncludeConfRegexp = regexp.MustCompile(`include\s+(\S*.conf);`)

Functions

func Build

func Build(config Configuration,
	dependencyService DependencyService,
	configGenerator ConfigGenerator,
	calculator Calculator,
	sbomGenerator SBOMGenerator,
	logger scribe.Emitter,
	clock chronos.Clock,
) packit.BuildFunc

func Detect

func Detect(config Configuration, versionParser VersionParser) packit.DetectFunc

Types

type BindingsResolver

type BindingsResolver interface {
	ResolveOne(typ, provider, platformDir string) (servicebindings.Binding, error)
}

type BuildPlanMetadata

type BuildPlanMetadata struct {
	Version       string `toml:"version,omitempty"`
	VersionSource string `toml:"version-source,omitempty"`
	Launch        bool   `toml:"launch"`
}

type Calculator

type Calculator interface {
	Sum(paths ...string) (string, error)
}

type ConfigGenerator

type ConfigGenerator interface {
	Generate(config Configuration) error
}

type Configuration

type Configuration struct {
	NGINXConfLocation        string `env:"BP_NGINX_CONF_LOCATION"`
	NGINXVersion             string `env:"BP_NGINX_VERSION"`
	LiveReloadEnabled        bool   `env:"BP_LIVE_RELOAD_ENABLED"`
	WebServer                string `env:"BP_WEB_SERVER"`
	WebServerForceHTTPS      bool   `env:"BP_WEB_SERVER_FORCE_HTTPS"`
	WebServerEnablePushState bool   `env:"BP_WEB_SERVER_ENABLE_PUSH_STATE"`
	WebServerRoot            string `env:"BP_WEB_SERVER_ROOT"`
	WebServerLocationPath    string `env:"BP_WEB_SERVER_LOCATION_PATH"`
	NGINXStubStatusPort      string `env:"BP_NGINX_STUB_STATUS_PORT"`

	BasicAuthFile string
}

func LoadConfiguration

func LoadConfiguration(environ []string, bindingsResolver BindingsResolver, platformPath string) (Configuration, error)

type DefaultConfigGenerator

type DefaultConfigGenerator struct {
	// contains filtered or unexported fields
}

func NewDefaultConfigGenerator

func NewDefaultConfigGenerator(logs scribe.Emitter) DefaultConfigGenerator

func (DefaultConfigGenerator) Generate

func (g DefaultConfigGenerator) Generate(config Configuration) error

type DependencyService

type DependencyService interface {
	Resolve(path, name, version, stack string) (postal.Dependency, error)
	Deliver(dependency postal.Dependency, cnbPath, layerPath, platformPath string) error
	GenerateBillOfMaterials(dependencies ...postal.Dependency) []packit.BOMEntry
}

type Parser

type Parser struct{}

func NewParser

func NewParser() Parser

func (Parser) ParseYml

func (p Parser) ParseYml(workingDir string) (string, bool, error)

func (Parser) ResolveVersion

func (p Parser) ResolveVersion(cnbPath, version string) (string, error)

type SBOMGenerator

type SBOMGenerator interface {
	GenerateFromDependency(dependency postal.Dependency, dir string) (sbom.SBOM, error)
}

type VersionParser

type VersionParser interface {
	ResolveVersion(cnbPath, version string) (resultVersion string, err error)
	ParseYml(workDir string) (ymlVersion string, exists bool, err error)
}