6. Managing Environments, Secrets, and Configuration

Introduction: Beyond Basic Deployment

Welcome back, intrepid Void Cloud explorer! In our previous chapters, you’ve learned the fundamentals of setting up your Void Cloud account, initializing projects, and deploying your first applications. That’s a huge step! You can now get your code running live for the world to see.

But what happens when your application needs to connect to a database? Or an external API? What if you have different API keys for your development version versus your live production version? Hardcoding these values directly into your code is a big no-no for security, flexibility, and maintainability. This is where the crucial concepts of environments, secrets, and configuration come into play.

In this chapter, we’re going to dive deep into how Void Cloud empowers you to manage these critical aspects of your applications. You’ll learn how to set up distinct environments for development, staging, and production, securely store sensitive information like API keys, and manage application-specific settings, all while keeping your codebase clean and secure. By the end of this chapter, you’ll be able to build and deploy applications on Void Cloud that are not only functional but also robust, secure, and ready for real-world scenarios.

The Why and How: Environments, Configuration, and Secrets

Before we touch any code or CLI commands, let’s understand why these concepts are so vital for modern application development.

The Need for Different Environments

Imagine you’re building a restaurant. You wouldn’t test out a brand new, experimental recipe on a paying customer, right? You’d try it in a test kitchen first, perhaps with a small group of trusted tasters, before rolling it out to the main dining room.

Software development is exactly the same. We need different “places” for our application to run:

• Development (Dev) Environment: This is your local machine. It’s where you write code, experiment, and debug features. You might use a local database or mock APIs.
• Staging Environment: This is a near-production replica. Here, you test new features with a small group of internal users or QA testers. It connects to test databases and external services, but nothing “live.” This is your “trusted tasters” kitchen.
• Production (Prod) Environment: This is the live application that your actual users interact with. It connects to real databases, payment gateways, and external APIs. This is your “main dining room.”

Why separate them?

• Safety: Prevent accidental data corruption or service outages on your live application.
• Testing: Test new features thoroughly in an environment that mimics production before releasing.
• Isolation: Changes in one environment don’t affect others.
• Cost Optimization: Staging environments might use smaller, cheaper resources.

Void Cloud makes managing these separate environments a breeze, allowing you to deploy the same codebase with different settings.

Configuration vs. Secrets: What’s the Difference?

This is a fundamental distinction that often trips up beginners.

• Configuration: These are settings that your application needs to run, but are generally not sensitive. They might change between environments, but if someone saw them, it wouldn’t compromise your security.

  • Examples: APP_NAME, LOG_LEVEL (debug, info, error), API_BASE_URL (for a public API), PORT.
  • How Void Cloud handles them: Typically as environment variables associated with a specific deployment or project, or via your void.yaml project file.

• Secrets: These are highly sensitive pieces of information that, if exposed, could lead to security breaches, unauthorized access, or financial loss. They must be protected.

  • Examples: Database passwords, API keys for payment processors, encryption keys, private SSH keys.
  • How Void Cloud handles them: Through a dedicated, encrypted secrets store. They are injected into your application’s runtime as environment variables but are never stored in plain text in your repository or build logs.

Think of it like this: Your restaurant’s menu (APP_NAME, LOG_LEVEL) is configuration – not sensitive. The key to the safe where you keep your daily earnings (DATABASE_PASSWORD, STRIPE_API_KEY) is a secret – extremely sensitive!

Void Cloud’s Approach to Management

Void Cloud provides a robust system for managing both configuration and secrets, primarily through:

1. Project Configuration (void.yaml): A file in your project’s root directory that defines build commands, output directories, and other static project-level settings.
2. Environment Variables: Key-value pairs that your application can access at runtime. Void Cloud allows you to define these per project or per environment.
3. Secrets Management System: A secure, encrypted vault where you store sensitive environment variables, linked to specific projects and environments.

Let’s visualize how these pieces fit together:

In this diagram:

• Your codebase, void.yaml, and environment/secrets defined in Void Cloud all feed into the build and runtime environments.
• Crucially, the environment variables and secrets are isolated per environment (Production, Staging, Development), ensuring that your production secrets are never accidentally used in a staging deployment.
• Locally, you’ll use a .env file to mimic Void Cloud’s environment variable injection.

Step-by-Step Implementation: Managing Your App’s Settings

Let’s get practical! We’ll use a simple Node.js application to demonstrate these concepts. If you don’t have a Void Cloud project ready, quickly set one up as we did in Chapter 3.

1. Preparing Our Sample Application

First, let’s create a very basic Node.js Express app that reads environment variables.

1. Create a new directory for your project:

   mkdir void-config-app
   cd void-config-app
   

2. Initialize a Node.js project:

   npm init -y
   

3. Install Express:

   npm install express dotenv
   

   We’re installing dotenv to help manage environment variables locally, mirroring how Void Cloud will inject them in the cloud.

4. Create an index.js file: This file will contain our simple Express server.

   // void-config-app/index.js
   require('dotenv').config(); // Loads environment variables from .env file
   
   const express = require('express');
   const app = express();
   const port = process.env.PORT || 3000; // Default to 3000 if PORT isn't set
   
   app.get('/', (req, res) => {
       const appName = process.env.APP_NAME || 'Void App';
       const message = process.env.WELCOME_MESSAGE || 'Hello from Void Cloud!';
       const apiKey = process.env.MY_API_KEY ? `(API Key present: YES)` : `(API Key present: NO)`;
       const environment = process.env.VOID_ENVIRONMENT || 'local'; // Void Cloud sets VOID_ENVIRONMENT
   
       res.send(`
           <h1>${message}</h1>
           <p>This is the <strong>${appName}</strong> running in the <strong>${environment}</strong> environment.</p>
           <p>${apiKey}</p>
           <p>Listening on port: ${port}</p>
       `);
   });
   
   app.listen(port, () => {
       console.log(`Server listening on port ${port}`);
       console.log(`APP_NAME: ${process.env.APP_NAME}`);
       console.log(`WELCOME_MESSAGE: ${process.env.WELCOME_MESSAGE}`);
       console.log(`MY_API_KEY: ${process.env.MY_API_KEY ? '****** (hidden)' : 'Not set'}`);
       console.log(`VOID_ENVIRONMENT: ${process.env.VOID_ENVIRONMENT}`);
   });
   

   • require('dotenv').config();: This line, placed at the very top, ensures that any variables defined in a .env file (which we’ll create next) are loaded into process.env when you run the app locally. Void Cloud handles this automatically for deployed apps.
   • process.env.VARIABLE_NAME: This is how Node.js applications access environment variables. We’re setting default values (|| 'Void App') in case the variable isn’t defined.
   • VOID_ENVIRONMENT: This is a special environment variable that Void Cloud automatically injects into your deployments, telling your application which environment it’s running in (e.g., production, staging, development).

5. Add a start script to package.json: Open your package.json and add this line under "scripts":

   // void-config-app/package.json
   {
     "name": "void-config-app",
     "version": "1.0.0",
     "description": "",
     "main": "index.js",
     "scripts": {
       "start": "node index.js", // Add this line
       "test": "echo \"Error: no test specified\" && exit 1"
     },
     "keywords": [],
     "author": "",
     "license": "ISC",
     "dependencies": {
       "dotenv": "^16.4.5",
       "express": "^4.19.2"
     }
   }
   

   • Note on dotenv version: As of early 2026, dotenv v16.4.5 is a stable release.

2. Local Environment Variables (.env file)

For local development, we use a .env file. This file is typically not committed to version control (.gitignore it!).

1. Create a .env file in the root of your void-config-app directory:

   # void-config-app/.env
   APP_NAME=Local Dev App
   WELCOME_MESSAGE=Welcome to your local development server!
   MY_API_KEY=dev_local_secret_123
   PORT=4000
   

2. Run your application locally:

   npm start
   

   You should see output indicating the server is listening on port 4000 and the variables are loaded. Open your browser to http://localhost:4000.

   Notice how MY_API_KEY is printed as ****** (hidden) in the console output from index.js, but locally you can still see its value in the .env file. This is for demonstration; in a real app, you’d never log a secret. The browser output also reflects the variables.

3. Initializing Void Cloud Project & void.yaml

Now, let’s prepare this project for Void Cloud.

1. Initialize Void Cloud: If you haven’t already, run void init in your project root.

   void init
   

   Follow the prompts. Choose a project name (e.g., void-config-app). This will create a void.yaml file.

2. Review void.yaml: Void Cloud CLI v2.2.0 (as of early 2026) generates a basic void.yaml. For our Node.js app, it might look something like this:

   # void-config-app/void.yaml
   projectId: void-config-app
   name: Void Config App
   build:
     command: npm install
     outputDirectory: . # Our app doesn't have a build step that outputs to a dist folder
   run:
     command: npm start
     runtime: nodejs@20 # Specify Node.js v20, a common LTS as of early 2026
   

   • projectId: Your unique project identifier on Void Cloud.
   • name: A human-readable name for your project.
   • build.command: The command Void Cloud runs to build your application (e.g., npm install, npm run build).
   • build.outputDirectory: Where your built assets are located. For a simple Node.js API, it’s usually the root (.).
   • run.command: The command Void Cloud executes to start your application.
   • run.runtime: Specifies the runtime environment. nodejs@20 is a good choice, as Node.js 20.x is an LTS release as of early 2026.

4. Managing Environment Variables on Void Cloud

Now, let’s add configuration variables that Void Cloud will inject. These are non-sensitive settings.

1. Add a project-level environment variable: This variable will apply to all deployments of this project by default, unless overridden by an environment-specific variable.

   void env add APP_NAME="My Awesome Void App"
   

   You’ll be prompted to confirm.

2. Add an environment-specific variable for staging: We want our staging environment to have a different welcome message.

   void env add WELCOME_MESSAGE="Welcome to the Staging environment!" --environment=staging
   

   Notice the --environment=staging flag. This tells Void Cloud to apply this variable only when deploying to the staging environment.

3. List your environment variables: You can see all configured variables using:

   void env ls
   

   Output might look like:

   Key             Value                          Environment
   APP_NAME        My Awesome Void App            (global)
   WELCOME_MESSAGE Welcome to the Staging environment! staging
   

   • APP_NAME is global.
   • WELCOME_MESSAGE is specific to staging. If we deploy to production, WELCOME_MESSAGE won’t be set unless we define a global or production-specific one.

5. Managing Secrets on Void Cloud

Now for the sensitive stuff: MY_API_KEY. This must be stored as a secret.

1. Add a secret for production:

   void secret add MY_API_KEY="prod_void_secret_xyz_456" --environment=production
   

   • Important: Void Cloud encrypts this value at rest and transit. It is never exposed in plain text via the CLI or dashboard after creation. It’s injected directly into your application’s runtime.

2. Add a secret for staging:

   void secret add MY_API_KEY="stage_void_secret_abc_123" --environment=staging
   

3. List your secrets:

   void secret ls
   

   Output will show the keys and their associated environments, but the values will be masked:

   Key          Environment
   MY_API_KEY   production
   MY_API_KEY   staging
   

   This masking is a core security feature of Void Cloud’s secrets management.

6. Deploying with Environment-Specific Settings

Now we’ll see it all in action.

1. Deploy to production:

   void deploy --environment=production
   

   Void Cloud will build and deploy your application. Once deployed, open the URL.

   • You should see: APP_NAME as “My Awesome Void App”, WELCOME_MESSAGE as “Hello from Void Cloud!” (our default, as no production-specific WELCOME_MESSAGE was set), and MY_API_KEY present.

2. Deploy to staging:

   void deploy --environment=staging
   

   After this deployment, open the new staging URL.

   • You should see: APP_NAME as “My Awesome Void App”, WELCOME_MESSAGE as “Welcome to the Staging environment!”, and MY_API_KEY present.

Notice how the same codebase now behaves differently based on the --environment flag during deployment, thanks to Void Cloud injecting the correct configuration and secrets. The VOID_ENVIRONMENT variable will also correctly reflect production or staging in your app.

A Note on PORT

Our index.js uses process.env.PORT || 3000. Void Cloud typically exposes your application on a standard web port (e.g., 80 or 443) and handles internal routing. If your application must listen on a specific internal port, you would set PORT as an environment variable in Void Cloud. However, for most web applications, simply letting Void Cloud handle the external port and allowing your app to listen on whatever PORT it provides (or a default like 3000) is the best practice. Void Cloud will proxy requests to your app’s internal port.

Mini-Challenge: Adding a Development Environment

Let’s put your new knowledge to the test!

Challenge: You want to introduce a development environment on Void Cloud for internal testing that’s distinct from staging and production.

1. Add a WELCOME_MESSAGE environment variable for the development environment. Make it unique, e.g., “Exploring new features in Development!”.
2. Add a MY_API_KEY secret specifically for the development environment. Use a placeholder like “dev_void_secret_alpha_beta”.
3. Deploy your void-config-app to the development environment.
4. Verify that the deployed application at the development URL displays the correct WELCOME_MESSAGE and indicates MY_API_KEY is present.

Hint: Remember the --environment flag for void env add and void secret add, and for void deploy.

What to observe/learn: You should have three distinct deployments (production, staging, development), each showing different messages and confirming the presence of their respective secrets, all from the same codebase. This demonstrates the power of environment-specific configuration and secrets management.

Common Pitfalls & Troubleshooting

Even with powerful tools, sometimes things don’t go as planned. Here are some common issues and how to resolve them:

1. “My environment variable isn’t showing up!”

   • Check void env ls and void secret ls: Did you add it correctly? Is it associated with the right environment (global vs. specific)?
   • Did you redeploy? After adding or updating an environment variable or secret on Void Cloud, you must trigger a new deployment for the changes to take effect in your running application.
   • Typos in code: Double-check process.env.YOUR_VARIABLE_NAME in your application code for exact matches (case-sensitive!).
   • Variable precedence: If you have a global APP_NAME and also an APP_NAME for staging, the staging-specific one will override the global one when deploying to staging. Make sure you understand this hierarchy.

2. “I accidentally put a secret in void env add instead of void secret add.”

   • This is a security risk! Immediately remove the sensitive variable using void env rm <KEY> [--environment=<ENV>].
   • Then, add it correctly using void secret add <KEY>=<VALUE> [--environment=<ENV>].
   • Consider rotating the compromised secret if it was exposed in build logs or publicly.

3. Local .env vs. Void Cloud variables.

   • Remember, your local .env file is only for local development. When deployed to Void Cloud, the .env file is ignored, and Void Cloud injects its own configured variables and secrets.
   • Make sure your local .env is in your .gitignore to prevent accidental commits of sensitive data.

4. Forgetting dotenv.config() locally.

   • If your local app isn’t picking up .env variables, ensure require('dotenv').config(); is at the very top of your main application file (e.g., index.js).

Summary: Your Apps, Configured and Secure

You’ve just leveled up your Void Cloud skills significantly! Understanding and implementing proper environment, configuration, and secrets management is a hallmark of professional application development.

Here are the key takeaways from this chapter:

• Environments (Dev, Staging, Prod) provide crucial isolation for testing, development, and live operations, preventing unintended side effects.
• Configuration refers to non-sensitive application settings that can vary per environment (e.g., APP_NAME).
• Secrets are highly sensitive data that must be securely stored and managed (e.g., MY_API_KEY).
• Void Cloud CLI (void env, void secret) and the Void Cloud Dashboard are your primary tools for managing these values.
• The void.yaml file defines static project-level configuration like build and run commands.
• Always redeploy after making changes to environment variables or secrets on Void Cloud for them to take effect.
• Locally, use a .env file (and dotenv in Node.js) to mimic Void Cloud’s environment injection, and always .gitignore your .env file.

By leveraging Void Cloud’s robust features, you can ensure your applications are flexible, scalable, and most importantly, secure across all stages of their lifecycle.

What’s Next?

With our application now securely configured, we’re ready to explore more advanced topics. In the next chapter, we’ll dive into deployment strategies, continuous integration, and continuous delivery (CI/CD) on Void Cloud, learning how to automate our deployments and streamline our development workflow even further. Get ready to automate!

References

• Void Cloud Official Documentation: Environment Variables
• Void Cloud Official Documentation: Secrets Management
• Void Cloud Official Documentation: void.yaml Configuration
• Node.js Documentation: process.env
• dotenv npm package

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.