Parameter Store Setup Guide

A parameter store provides a centralized way to manage configuration values for your applications running on Eyevinn Open Source Cloud. This guide shows you how to set up a parameter store using the App Config Service backed by Valkey.

What is a Parameter Store?

A parameter store is a key-value storage system for managing application configuration. It consists of two components:

  1. Valkey - A Redis-compatible in-memory data store that holds the configuration values
  2. App Config Service - A web UI and REST API for managing the configuration

Why Use a Parameter Store?

  • Centralized Configuration - Store all your application settings in one place
  • Easy Updates - Change configuration values without redeploying your application
  • Environment Variables - Automatically inject configuration as environment variables into Web Runner and WASM Runner instances
  • Feature Flags - Toggle features on/off dynamically
  • Secrets Management - Store API keys and sensitive configuration (combined with OSC Service Secrets for sensitive values)

Naming Rules

Parameter store names must be alphanumeric only (letters and digits, no underscores, hyphens, or other special characters):

  • ✅ Valid: myconfig, myStore123, configprod
  • ❌ Invalid: my_config, my-config, my.config

The same name is used for both the Valkey instance and the App Config Service instance.

The fastest way to set up a parameter store is using the OSC MCP tools with an AI agent.

Prerequisites

  • An OSC account
  • Claude Desktop, Claude Code, VS Code, or Cursor with MCP configured (see setup guide)

Setup Command

Simply ask your AI agent:

"Set up a parameter store for me"

Or be more specific:

"Create a parameter store called myconfig"

The AI agent will use the setup-parameter-store MCP tool which:

  1. Creates a Valkey instance for data storage
  2. Retrieves the Valkey connection details
  3. Creates an App Config Service instance
  4. Configures the App Config Service to use the Valkey instance
  5. Verifies the setup is working

The entire process takes about 30 seconds.

Manual Setup via Web Console

If you prefer to set up manually:

Step 1: Create a Valkey Instance

  1. Navigate to the Valkey service
  2. Click Create valkey
  3. Enter a name (e.g., configstore)
  4. Click Create
  5. Wait for the instance to be ready

Step 2: Get Connection Details

  1. Go to your active services dashboard
  2. Click on your Valkey instance
  3. Note the External IP and External Port
  4. Construct the Redis URL: redis://<external-ip>:<external-port>

Step 3: Create App Config Service

  1. Navigate to the App Config Service
  2. Click Create app-config-svc
  3. Enter a name (e.g., myconfig)
  4. In RedisUrl, enter the URL from Step 2
  5. Click Create

Step 4: Verify Setup

  1. Click on your App Config Service instance
  2. Click Open to access the web UI
  3. Try adding a test configuration key/value pair

Manual Setup via CLI

# Create Valkey instance
npx @osaas/cli create valkey-io-valkey configstore

# Get the Valkey instance details
npx @osaas/cli describe valkey-io-valkey configstore

# Extract IP and port from the output, then create App Config Service
npx @osaas/cli create eyevinn-app-config-svc myconfig \
  -o RedisUrl="redis://123.45.67.89:12345"

Replace 123.45.67.89:12345 with the actual external IP and port from the Valkey instance.

Using Your Parameter Store

Managing Configuration via Web UI

  1. Open your App Config Service instance from the dashboard
  2. Click Open to access the web UI
  3. Add key-value pairs:
  4. Key: DATABASE_URL
  5. Value: postgresql://user:pass@host:5432/db
  6. Values are immediately available via the API

Using with Web Runner

When creating a Web Runner instance, specify your parameter store in the ConfigService field:

npx @osaas/cli create eyevinn-web-runner myapp \
  -o SourceUrl="https://github.com/yourusername/yourapp" \
  -o ConfigService="myconfig"

All configuration values will be loaded as environment variables when your app starts.

Using with WASM Runner

Similarly for WASM Runner:

npx @osaas/cli create eyevinn-wasm-runner mywasm \
  -o WasmUrl="https://example.com/app.wasm" \
  -o ConfigService="myconfig"

Accessing via API

Get a value

curl https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config/DATABASE_URL

Response:

{
  "key": "DATABASE_URL",
  "value": "postgresql://user:pass@host:5432/db"
}

Set a value

curl -X POST https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config \
  -H "Content-Type: application/json" \
  -d '{"key":"API_KEY","value":"sk_live_abc123"}'

List all values

curl https://myconfig.eyevinn-app-config-svc.auto.prod.osaas.io/api/v1/config

Using in Application Code

If your Web Runner application needs to fetch config at runtime:

import { Context } from "@osaas/client-core";
import { getEyevinnAppConfigSvcInstance } from "@osaas/client-services";

async function getConfig(key) {
  const ctx = new Context();
  const configService = await getEyevinnAppConfigSvcInstance(ctx, 'myconfig');

  const response = await fetch(
    new URL(`/api/v1/config/${key}`, configService.url),
    { cache: 'no-store' }
  );

  if (response.ok) {
    const data = await response.json();
    return data.value;
  }
  return undefined;
}

// Usage
const apiKey = await getConfig('API_KEY');

Best Practices

Sensitive Values

For sensitive values like API keys and passwords, combine parameter store with OSC Service Secrets:

  1. Store the sensitive value as a Service Secret
  2. Reference it in your parameter store value using {{secrets.secretname}}
  3. The secret value will be injected when the configuration is loaded

See Working with Secrets for details.

Configuration Naming

Use consistent naming conventions:

  • Environment-specific: PROD_DATABASE_URL, DEV_DATABASE_URL
  • Service-specific: AUTH_SERVICE_URL, PAYMENT_SERVICE_URL
  • Feature flags: FEATURE_NEW_DASHBOARD, ENABLE_BETA_FEATURES

Updating Configuration

  • Configuration changes are immediate - no restart required for Web Runner or WASM Runner
  • If your app caches config values, implement a refresh mechanism
  • Use the web UI for manual updates, use the API for automated deployments

Character Handling in Values

Parameter store values are stored via JSON and preserved faithfully in the parameter store itself. However, when values are injected as environment variables into your application at startup, shell metacharacters can cause problems.

Shell Metacharacter Warning

⚠️ Avoid shell metacharacters in parameter values that will be injected as environment variables. The following characters may be silently corrupted or cause unexpected behaviour at runtime:

! $ # & * ? [ ] ( ) { } | ; < > `

Safe characters for environment variable values: - Alphanumeric characters (a-z, A-Z, 0-9) - Hyphens (-), underscores (_), dots (.), slashes (/), colons (:), at-signs (@) - Most printable characters except the shell metacharacters listed above

Handling Special Characters in Passwords

If your password or secret must contain shell metacharacters (e.g., Mypassword2024!), use base64 encoding:

# Encode the value
echo -n 'Mypassword2024!' | base64
# Output: TXlwYXNzd29yZDIwMjQh

# Store the base64-encoded value in the parameter store

Then decode it in your application code:

// Node.js example
const password = Buffer.from(process.env.MY_PASSWORD, 'base64').toString('utf-8');

This ensures the value is preserved faithfully through the environment variable injection.

Troubleshooting

App Config Service won't start

  • Verify the Valkey instance is running and healthy
  • Check the Redis URL format: redis://<ip>:<port> (no trailing slash)
  • Ensure the external IP and port are correct

Configuration values not loading in Web Runner

  • Verify the ConfigService parameter matches the exact name of your App Config Service instance
  • Check that the App Config Service instance is running
  • Look at the Web Runner logs for connection errors
  • If logs show [CONFIG] ERROR or Authorization: command not found, the config service token may have expired — recreate the app with delete-my-app + create-my-app

Zero environment variables loaded

If logs show [CONFIG] Loaded 0 environment variable(s) or [CONFIG] WARNING: Config service returned no valid environment variables:

  1. Verify the parameter store has values: use list-parameters MCP tool or the App Config web UI
  2. Check if the config service authentication failed (look for error messages in the logs)
  3. If auth failed, rebuild the app (restart-my-app with rebuild=true) to migrate to a long-lived refresh token
  4. Monorepo apps (subPath): If your app uses both subPath and configService, the workspace's start command may bypass the root-level config loading. See Monorepo Apps with subPath and configService for details

Can't access the web UI

  • Ensure the App Config Service instance is in "Running" state
  • Try refreshing the instance URL
  • Check the service status page for any platform issues

Pricing

Both Valkey and App Config Service are billed separately based on runtime. See Pricing for details.