Managing Environment Variables

Environment variables let you store configuration values in Serverpod Cloud without hardcoding them in your application code. This guide explains how to create, update, and use environment variables in your Serverpod applications.

warning

Environment variables should not be used to store sensitive information such as API keys, passwords, or access tokens. For sensitive data, use Serverpod's secrets management instead. See the Secrets Management guide for more information.

Creating Environment Variables

1. Use the scloud env create command to add a new environment variable:

   scloud env create --name SERVER_EMAIL --value "support@example.com"

Managing Existing Variables

Listing Variables

To view all environment variables for your project:

scloud env list

This will display a table of your environment variables:

Name         | Value
-------------+--------------------
SERVER_EMAIL | support@example.com

Updating Variables

To change the value of an existing environment variable:

scloud env update --name SERVER_EMAIL --value "noreply@example.com"

Deleting Variables

To remove an environment variable:

scloud env delete --name SERVER_EMAIL

You'll be asked to confirm the deletion:

Are you sure you want to delete the environment variable SERVER_EMAIL? (y/N)

Using Environment Variables in Your Code

Environment variables are accessible in your Serverpod application code through Dart's Platform.environment map:

import 'dart:io';

void main() {
  // Access an environment variable
  final email = Platform.environment['SERVER_EMAIL'];
  
  print('Server email: $email');
}

For more structured access, you might create a configuration class:

class AppConfig {
  final String serverEmail;
  
  AppConfig._({
    required this.serverEmail,
  });
  
  factory AppConfig.fromEnvironment() {
    final email = Platform.environment['SERVER_EMAIL'];
    
    if (email == null) {
      throw Exception('Missing required environment variables');
    }
    
    return AppConfig._(
      serverEmail: email,
    );
  }
}

⚠️ Important Notes

1. Deployment Required: Environment variables are only available after deployment. They won't be accessible during local development unless you set them manually in your development environment.

2. Restart After Changes: After adding or updating environment variables, you need to redeploy your application for the changes to take effect:

   scloud deploy

3. Appropriate Use: Environment variables are best for configuration that varies between environments, such as feature flags, logging levels, or service endpoints.

4. Local Development: For local development, you can:

   • Set environment variables in your terminal before running your app
   • Use a .env file with a package like dotenv (remember to add this file to .gitignore)
   • Create a development-specific configuration

5. Limitations:

   • Environment variable names can only contain lowercase letters a-z, uppercase letters A-Z, digits 0-9 and underscore _ for separation. The name has to start with a letter.
   • Maximum name length is 255.
   • The maximum total size of all environment variables cannot exceed 64kB.

Serverpod Cloud Configuration Management

Serverpod Cloud automatically manages most standard Serverpod configuration settings that would normally be specified in your production.yaml file. These configurations are injected as environment variables into your application's runtime environment.

This means you don't need to manually configure settings like:

• API server configuration:

  • SERVERPOD_API_SERVER_PORT: API server port
  • SERVERPOD_API_SERVER_PUBLIC_HOST: API server host address
  • SERVERPOD_API_SERVER_PUBLIC_SCHEME: Protocol scheme for the API server (https)
  • SERVERPOD_API_SERVER_PUBLIC_PORT: Public port for the API server

• Insights server configuration:

  • SERVERPOD_INSIGHTS_PORT: Insights server port
  • SERVERPOD_INSIGHTS_PUBLIC_HOST: Public host address for the insights server
  • SERVERPOD_INSIGHTS_PUBLIC_SCHEME: Protocol scheme for the insights server (https)
  • SERVERPOD_INSIGHTS_PUBLIC_PORT: Public port for the insights server

• Web server configuration:

  • SERVERPOD_WEB_SERVER_PORT: Web server port
  • SERVERPOD_WEB_SERVER_PUBLIC_HOST: Public host address for the web server
  • SERVERPOD_WEB_SERVER_PUBLIC_SCHEME: Protocol scheme for the web server (https)
  • SERVERPOD_WEB_SERVER_PUBLIC_PORT: Public port for the web server

For a complete list of available configuration options in Serverpod, see the Serverpod Configuration documentation.

💡 Best Practices

• Use environment variables for configuration that varies between environments
• Use descriptive names
• Document required environment variables in your project README
• Add validation to ensure required variables are present
• Don't store sensitive information in environment variables

🧪 Example: Complete Configuration Setup

Here's a more complete example of using environment variables in a Serverpod Cloud application:

// server_config.dart
import 'dart:io';

// Extension to make the config accessible from the session
extension AccessibleConfig on Session {
  ServerConfig get config => ServerConfig.instance;
}

// Configuration class to centralize environment variable access
class ServerConfig {
  final String region;

  ServerConfig._({
    required this.region,
  });

  static void init() {
    _instance = ServerConfig._fromEnvironment();
  }

  static ServerConfig? _instance;
  static ServerConfig get instance {
    return _instance ??= ServerConfig._fromEnvironment();
  }

  factory ServerConfig._fromEnvironment() {
    // Required variables with validation
    final region = Platform.environment['REGION'];

    if (region == null || region.isEmpty) {
      throw Exception('Missing required environment variable: REGION');
    }

    return ServerConfig._(
      region: region,
    );
  }
}

Initialize the configuration when starting Serverpod:

// server.dart
import 'package:serverpod/serverpod.dart';

import 'src/generated/protocol.dart';
import 'src/generated/endpoints.dart';

void run(List<String> args) async {
  final pod = Serverpod(
    args,
    Protocol(),
    Endpoints(),
  );

  ServerConfig.init();

  // other setup code ...

  await pod.start();
}

Inside an endpoint you can access the config through the session object. This allows you to use environment variables throughout your application in a clean, centralized way:

class ExampleEndpoint extends Endpoint {

  Future<String> region(Session session) async {
    final region = session.config.region;

    return region;
  }
}