Creating and Testing NGINX Templates

RunCloud allows you to create custom NGINX templates from scratch. Since NGINX is highly sensitive to syntax errors, a single typo could potentially bring down your web server. RunCloud includes a built-in testing environment that lets you safely validate your custom configurations in a live Web Application context without modifying the live server.

Here is how to create a new template, add configuration files to it, and test it safely.

1. Creating a New Template

To build your own NGINX configuration standard, you will start by creating a blank template in your workspace.

Step 1: In the RunCloud dashboard, navigate to Settings in the left-hand menu and select NGINX Templates.

Step 2: Ensure you are in the My Templates tab.

Step 3: Click the blue Create New Template button on the right side of the screen.

Step 4: Provide the basic details for your new template:

• Template Name: Give your template a clear, descriptive name (e.g., “Security Headers Template” or “Custom API Routing”).
• Description: Add a brief description of what this template does so you or your team members understand its purpose later.

Do not click “Create Template” just yet, as you’ll need to add your configuration files first.

2. Adding Configuration Files

A single NGINX Template can contain multiple configuration files (e.g., one for main configurations, one for security rules, etc.).

Step 1: Under the Configuration Files section, click Add New File.

Step 2: A file configuration modal will appear. Fill in the following fields:

• Config Type: Select the appropriate NGINX context for this file from the dropdown (e.g., location.http, location. main, location.root, etc.). This tells RunCloud where to inject your custom rules inside the server’s main NGINX configuration block.
• Filename: Enter a recognizable name for this file (e.g., test, security-headers, custom-cache).
• Content: Paste your NGINX configuration rules into the text editor.

Step 3: Click Done to save the file to your draft template.

Step 4: Click the blue Create Template button at the bottom of the page. You will be redirected to your new Template’s dashboard.

3. Testing Templates

Before assigning a new template to a production web application, you must ensure the NGINX syntax is fully valid. RunCloud’s Test Template feature simulates applying the configuration to a real Web Application’s environment variables (such as paths and app names) without modifying the live server.

Step 1: From your Template’s dashboard, click the … (three dots) menu in the top-right corner.

Step 2: Select Test Template from the dropdown menu.

Step 3: A “Test Template Configuration” modal will appear. The modal will remind you that testing requires an active Web App context to resolve variables properly, but the live application will not be modified.

Step 4: Select one of your existing Web Applications from the dropdown menu to act as the test subject.

Step 5: Click Run Test. RunCloud will evaluate the NGINX configuration against the selected application.

Understanding the Results:

• If the test fails: RunCloud will block the configuration and display an NGINX Configuration Test Failed error box. This box contains NGINX error output (e.g., nginx: [emerg] unknown directive…). A template cannot be successfully installed in a web app if it contains syntax errors.
• If the test passes: You will receive a success confirmation, meaning your NGINX syntax is valid, and your template is now safe to deploy to your active Web Applications.