Project-Level Environment Configuration with .servbay.config

Overview

ServBay is a powerful local web development tool that allows developers to set up isolated environments for different projects. The key to this capability is the ability to create a file named .servbay.config in the root directory of each project.

Using a .servbay.config file, you can easily specify the desired versions of PHP, Node.js, Python, Go, Java, and other languages for a particular project. Additionally, you can configure Node.js package managers (such as NPM and Yarn), set registry URLs, cache directories, and more. This granular project-level control significantly boosts development efficiency and convenience, ensuring that each project runs in its required environment and eliminating version conflicts.

How the .servbay.config File Works

When ServBay starts or reloads a website, it checks if a .servbay.config file exists in the website's root directory. If present, ServBay reads the configuration from this file and applies it to the running environment for that specific site. Project-level configuration entries in this file will override the corresponding global settings set in ServBay. If the .servbay.config file does not exist, or if an item is not set in the file, ServBay falls back to the global defaults.

This mechanism makes switching between projects seamless, as each project carries its own environment configuration.

How to Create and Configure .servbay.config

Creating and editing a .servbay.config file is very straightforward.

File Location

Create a file named .servbay.config in your project’s root directory. The project root is usually located under ServBay’s website storage path, such as /Applications/ServBay/www/YourProjectName/.

Configuration Syntax

The .servbay.config file uses a simple KEY=VALUE format, with one configuration item per line. You can use # to add comments for better readability.

Example Configuration Options

Below is an example of a .servbay.config file showing how to configure various environment versions and package manager settings:

# Example .servbay.config file

# Specify the PHP runtime version. Make sure this version is installed in ServBay.
PHP_VERSION=8.5

# Specify the Node.js runtime version. Ensure this version is installed in ServBay.
NODE_VERSION=20

# Configure Yarn's registry URL to speed up dependency downloads.
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/

# Configure NPM's registry URL for faster dependency download.
NPM_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/

# Specify the local cache directory for NPM. Note: This path is relative to the ServBay installation directory.
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

# Specify Yarn's local cache directory. Note: This path is relative to the ServBay installation directory.
YARN_CONFIG_CACHE=/Applications/ServBay/tmp/yarn/cache

# Specify Ruby runtime version. Ensure this version is installed in ServBay.
RUBY_VERSION=2.7

# Specify the Java (OpenJDK) runtime version. Ensure this version is installed in ServBay.
JAVA_VERSION=21

# Specify Python runtime version. Ensure this version is installed in ServBay.
PYTHON_VERSION=3.11

# Specify .NET runtime version. Ensure this version is installed in ServBay.
DOTNET_VERSION=5.0

# Specify Go runtime version. Ensure this version is installed in ServBay.
GO_VERSION=1.12

# Configure Go module proxy server to accelerate module downloads.
GOPROXY=https://goproxy.cn,direct

Note: The version numbers in this sample (PHP_VERSION=8.5, NODE_VERSION=20, etc.) are for demonstration purposes only. In practice, you should fill in the appropriate values according to your project needs and the versions installed/supported by ServBay. If a specified version is not installed, ServBay may use a default version or display an error.

Supported Configuration Items

Based on the example above, the .servbay.config file mainly supports the following types of configuration:

1. Environment Version Specification:

   • PHP_VERSION: Specify PHP version.
   • NODE_VERSION: Specify Node.js version.
   • RUBY_VERSION: Specify Ruby version.
   • JAVA_VERSION: Specify Java (OpenJDK) version.
   • PYTHON_VERSION: Specify Python version.
   • DOTNET_VERSION: Specify .NET version.
   • GO_VERSION: Specify Go version.
   • (Refer to the ServBay documentation or app interface to check the full list of supported environment types and corresponding variable names.)

2. Package Manager Configuration (Node.js):

   • YARN_CONFIG_REGISTRY: Yarn registry URL.
   • NPM_CONFIG_REGISTRY: NPM registry URL.
   • NPM_CONFIG_CACHE: NPM local cache directory path.
   • YARN_CONFIG_CACHE: Yarn local cache directory path.

3. Go Module Proxy Configuration:

   • GOPROXY: Go module proxy server address.

These settings allow you to establish an independent environment for each project, preventing interference between different projects.

Applying and Verifying Configuration

After configuring the .servbay.config file, make sure ServBay has loaded your project (i.e., your project is visible in the "Websites" list within the ServBay application). ServBay will read the configuration when the website is loaded or reloaded.

To verify that your configuration is effective, you can:

1. Check the ServBay App Interface: ServBay may display the currently applied environment versions for your project in the site details or related view.

2. Validate from the Command Line: Open ServBay’s Terminal feature and ensure your working directory is set to the project root. Then, run the relevant version check commands, such as:

   • Check PHP version: php -v
   • Check Node.js version: node -v
   • Check Yarn version: yarn -v
   • Check NPM version: npm -v
   • Check Python version: python -V or python3 -V
   • Check Go version: go version
   • Check Java version: java -version
   • Check .NET version: dotnet --version
   • Check Ruby version: ruby -v Verify that the output matches the versions specified in your .servbay.config file.

3. Validate via Web Page (PHP-specific): Create a simple PHP file like info.php in your project root with the following content: <?php phpinfo(); ?>. Visit this file in your browser (for example, http://your-project.servbay.demo/info.php) and check the reported PHP version in the output to confirm it matches the version you set.

The image below may illustrate how ServBay reflects effective project-level configuration in its app interface:

(Please check the actual output in the ServBay app for the specific effect of your configuration.)

Important Notes

• The filename must be exactly .servbay.config without any typos.
• The file must be placed in your project’s root directory.
• The versions specified in the file must be installed and supported by ServBay.
• Each configuration entry should be on a separate line in the format KEY=VALUE.
• Any syntax errors may cause the entire file to be ignored or some settings to be invalid.
• The settings in .servbay.config override ServBay’s global configuration and are only effective for the current project.

Frequently Asked Questions (FAQ)

Q: What if there is no .servbay.config file in my project root?

A: If the file is absent, ServBay will use your global environment settings configured via the app to run your project.

Q: What if I specify a version in .servbay.config that isn’t installed in ServBay?

A: ServBay will prompt an error; the exact behavior depends on the version and configuration of ServBay. To ensure your specified version is used, always install the required environment version in the ServBay app first.

Q: Do I need to restart ServBay after changing the .servbay.config file?

A: Usually, after modifying .servbay.config, you just need to reload or stop and restart the affected website in the ServBay app; you do not need to quit and restart the whole application.

Q: Will the settings in .servbay.config affect my other projects?

A: No. The .servbay.config file applies project-level configurations and only affects the ServBay site directory it resides in.

Summary

The .servbay.config file gives developers powerful project-level environment management in ServBay. Whether you’re maintaining legacy projects requiring older runtime versions or developing new projects with the latest technology stacks, you can rapidly switch and isolate environments simply by editing this file. This greatly enhances the flexibility and efficiency of your local development workflow. Make the most of this feature to streamline your development process.