Edit

Deploy web static files

  • Article

Note

Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

This article applies to: ❌ Basic/Standard ✔️ Enterprise

This article shows you how to deploy your static files to an Azure Spring Apps Enterprise plan instance using the Tanzu Web Servers buildpack. This approach is useful if you have applications that are purely for holding static files like HTML, CSS, or front-end applications built with the JavaScript framework of your choice. You can directly deploy these applications with an automatically configured web server (HTTPD and NGINX) to serve those assets.

Prerequisites

Deploy your static files

Note

This article focuses on describing deployment configurations and troubleshooting specific to web static file deployment. To understand the general build and deployment scenarios for the Azure Springs Apps Enterprise plan, see the Build service on demand section of Use Tanzu Build Service and How to deploy polyglot apps.

You can deploy static files to Azure Spring Apps using NGINX or HTTPD web servers in the following ways:

  • You can deploy static files directly. Azure Spring Apps automatically configures the specified web server to serve the static files.
  • You can create your front-end application in the JavaScript framework of your choice, and then deploy your dynamic front-end application from source code. Azure Spring Apps builds your app into static content and uses your configured web server to serve the static files.

You can also create a server configuration file to customize the web server.

Deployment examples

The Azure CLI examples in this section show building and deploying static files for two container registry scenarios:

  • Azure Spring Apps managed container registry.
  • User managed container registry.

Build and deploy static files directly

This example deploys static files directly using an autogenerated default server configuration file.

The following command deploys a static file:

az spring app deploy
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --source-path <path-to-source-code> \
    --build-env BP_WEB_SERVER=nginx

For information about using environment variables, see the Configure an autogenerated server configuration file section.

Build and deploy your front-end application as static content

This example deploys a dynamic front-end application from source code.

The following command deploys an application:

az spring app deploy \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --source-path <path-to-source-code> \
    --build-env BP_WEB_SERVER=nginx BP_NODE_RUN_SCRIPTS=build BP_WEB_SERVER_ROOT=build

Build and deploy static files using a customized configuration file

This example deploys static files using a customized server configuration file.

The following command deploys an application:

az spring app deploy \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --source-path <path-to-source-code>

For more information, see the Use a customized server configuration file section of this article.

Sample code

Note

The sample code is maintained by the Paketo open source community.

The Paketo buildpacks samples demonstrate common use cases for several different application types, including the following use cases:

  • Serving static files with a default server configuration file using BP_WEB_SERVER to select either HTTPD or NGINX.
  • Using Node Package Manager to build a React app into static files that a web server can serve. Use the following steps:
    1. Define a script under the scripts property of the package.json file that builds your production-ready static assets. For React, it's build.
    2. Find out where static assets are stored after the build script runs. For React, static assets are stored in ./build by default.
    3. Set BP_NODE_RUN_SCRIPTS to the name of the build script.
    4. Set BP_WEB_SERVER_ROOT to the build output directory.
  • Serving static files with your own server configuration file, using either HTTPD or NGINX.

Configure an autogenerated server configuration file

You can use environment variables to modify the autogenerated server configuration file. The following table shows supported environment variables.

Environment Variable Supported Value Description
BP_WEB_SERVER nginx or httpd Specifies the web server type, either nginx for Nginx or httpd for Apache HTTP server. Required when using the autogenerated server configuration file.
BP_WEB_SERVER_ROOT An absolute file path or a file path relative to /workspace. Sets the root directory for the static files. The default is public.
BP_WEB_SERVER_ENABLE_PUSH_STATE true or false Enables push state routing for your application. Regardless of the route that is requested, index.html is always served. Useful for single-page web applications.
BP_WEB_SERVER_FORCE_HTTPS true or false Enforces HTTPS for server connections by redirecting all requests to use the HTTPS protocol.

The following environment variables aren't supported.

  • BP_LIVE_RELOAD_ENABLED
  • BP_NGINX_VERSION
  • BP_HTTPD_VERSION

Use a customized server configuration file

You can configure web server by using a customized server configuration file. The following table shows the configuration file path:

Web server Default configuration file path How to customize server configuration file path
nginx nginx.conf under the root path of your source code. Use environment variable BP_NGINX_CONF_LOCATION to specify the configuration file name. Place the file under the root path of your source code.
httpd httpd.conf under the root path of your source code. Not supported.

Your configuration file must conform to the restrictions described in the following table.

Configuration Description Nginx Configuration Httpd Configuration
Listening port Web server must listen on port 8080. The service checks the port on TCP for readiness and whether it's live. You must use the templated variable PORT in the configuration file. The appropriate port number is injected when the web server is launched. listen {{PORT}} Listen "${PORT}"
Log path Config log path to the console. access_log /dev/stdout, error_log stderr ErrorLog /proc/self/fd/2
File path with write permission Web server is granted write permission to the /tmp directory. Configuring the full path requires write permission under the /tmp directory. For example: client_body_temp_path /tmp/client_body_temp
Maximum accepted body size of client request Web server is behind the gateway. The maximum accepted body size of the client request is set to 500 m in the gateway and the value for web server must be less than 500 m. client_max_body_size should be less than 500 m. LimitRequestBody should be less than 500 m.

Buildpack bindings

Deploying static files to the Azure Spring Apps Enterprise plan supports the Dynatrace buildpack binding. The htpasswd buildpack binding isn't supported.

For more information, see How to configure APM integration and CA certificates.

Common build and deployment errors

Your deployment of static files to an Azure Spring Apps Enterprise instance may generate the following common build errors:

  • ERROR: No buildpack groups passed detection.
  • ERROR: Please check that you're running against the correct path.
  • ERROR: failed to detect: no buildpacks participating

The root cause of these errors is that the web server type isn't specified. To resolve these errors, set the environment variable BP_WEB_SERVER to nginx or httpd.

The following table describes common deployment errors when you deploy static files to Azure Spring Apps Enterprise.

Error message Root cause Solution
112404: Exit code 0: purposely stopped, please refer to https://aka.ms/exitcode The web server failed to start. Validate your server configuration file to see if there's a configuration error. Then, check whether your configuration file conforms to the restrictions described in the Use a customized server configuration file section.
mkdir() "/var/client_body_temp" failed (13: Permission denied) The web server doesn't have write permission to the specified path. Configure the path under the directory /tmp; for example: /tmp/client_body_temp.

Next steps