Configuring environment variables and secrets

Both environment variables and secrets can be used to provide your Celest backend with environment-specific configuration. They allow you to keep configuration values separate from your codebase, improving flexibility when deploying your backend to different environments and isolating sensitive information from your frontend.

Because of this, it's important to keep in mind that environment variables and secrets are not accessible from your frontend code.

Creating environment variables

To declare an environment variable, add a Dart variable in your project.dart file using the env constructor.

import 'package:celest/celest.dart';
 
const project = Project(name: 'my-project');
 
const myEnv = env('MY_ENV');

The name passed to env is the name as it appears in the platform environment. This name will be used to configure your Celest Functions when they're deployed to Celest Cloud or when self hosting in a container.

Celest keeps track of the unique variables throughout your project and ensures that any missing values are provided before you deploy your project. When you run celest start for the first time, it will prompt you for the value of each environment variable. After you provide the values, Celest will securely store them for future use.

Using .env files

You can also use a .env file to store your environment variables. This file should be placed in the root of your project directory in the celest/ folder. When a .env file is present, Celest will start by reading the values from the file and only then prompt you for any missing values.

When the values of these variables changes between environments, you can suffix your .env files with the name of the environment they apply to. For example, Celest currently provides a local and production environment. Given the following .env files:

my-project/
  celest/
    .env.local
    .env.production
    pubspec.yaml

MY_ENV=local-value

MY_ENV=production-value

The value of MY_ENV will be local-value when you run celest start, and production-value you run celest deploy or celest build.

Using environment variables with Celest Functions

To get the value of an environment variable in a Celest Function, you can use the generated celest global. Just like in your Flutter app, Celest will generated some helper methods to access important parts of your project.

In this case, we can use celest.variables.myEnv to access the value of the MY_ENV environment variable.

// Import the generated `celest` global
import 'package:celest_backend/src/generated/cloud.celest.dart';
 
@cloud
Future<String> sayHello(String name) async {
  print('My environment variable is ${celest.variables.myEnv}');
  return 'Hello, $name!';
}

When the sayHello function runs, it will automatically have access to the environment variable. Its value is stored securely and is never hard-coded in your codebase or in the deployed Celest Function.

Creating secrets

Secrets are created and managed exactly like environment variables. The only difference is that secrets are encrypted by Celest and are not displayed in the console when you run celest start. Otherwise, how you use them in your code is the same as environment variables.

To create a secret, use the secret constructor instead of env.

import 'package:celest/celest.dart';
 
const project = Project(name: 'my-project');
 
const myEnv = env('MY_ENV');
const mySecret = secret('MY_SECRET');

Then, you can use the celest.secrets helper in your functions in the same way as environment variables.

// Import the generated `celest` global
import 'package:celest_backend/src/generated/cloud.celest.dart';
 
@cloud
Future<String> sayHello(String name) async {
  print('My environment variable is ${celest.variables.myEnv}');
  print('My secret is ${celest.secrets.mySecret}');
  return 'Hello, $name!';
}

Next steps

You have now learned about the flows available for updating, retreiving, and deleting environment variables in your Celest project. You can follow additional guides to learn more about testing your functions, and installing 3rd party Dart packages.