Skip to content

env-vars.md

Latest commit

 

History

History
182 lines (124 loc) · 6.93 KB

env-vars.md

File metadata and controls

182 lines (124 loc) · 6.93 KB

Environment Variables Setup

This guide provides detailed instructions for setting up your .dev.vars file for local development.

First, copy the sample environment file:

cp .env.sample .dev.vars

Then, edit the .dev.vars file to set the required values as described below.

Variables Summary

Variable Description Example Value
OP_KEY_ID UUID v4 identifier for your Open Payments key. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
OP_PRIVATE_KEY Base64-encoded private key for signing requests. (See conversion script below)
OP_WALLET_ADDRESS The URL of your Open Payments wallet address. https://ilp.interledger-test.dev/my-wallet
AWS_ACCESS_KEY_ID AWS access key for S3. Not used in local dev. ABCDEFGHIJKLMN12OPQR
AWS_SECRET_ACCESS_KEY AWS secret key for S3. Not used in local dev. ab1cD/2e/fGhIJ11kL13mN0pQrS45tu6V7w8X9yZ
AWS_S3_ENDPOINT The endpoint for the S3-compatible storage. http://localhost:8081
UMAMI_HOST URL of your Umami instance. http://localhost:3001
UMAMI_WEBSITE_ID Website ID from the Umami dashboard. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Detailed Configuration

Open Payments Configuration

These variables are required to connect to an Interledger wallet for handling payments. For development, you can use the Interledger Testnet.

OP_KEY_ID

This is the unique identifier for your API key.

  1. Sign up for an Interledger Testnet wallet.
  2. In your wallet dashboard, navigate to the Settings section from the side menu and access developer keys.
  3. Generate a new key pair.
  4. Copy the Key ID (which is in UUID format) and paste it into your .dev.vars file.

OP_PRIVATE_KEY

This is the secret key used to sign payment requests, proving you own the wallet.

  1. When you generate a key pair, your wallet will provide a private key.
  2. Important: This key needs to be converted to a specific format. Use the script below to do this.

Security Note: Never commit this value to version control.

Click to see Private Key Conversion Script

After copying your private key, run this script to convert it to the correct format.
Replace currentKey value string with your copied private key, then use the output as your OP_PRIVATE_KEY value:

// paste your private key from the wallet here
const currentKey = ''

const derBytes = atob(
  currentKey
    .replace('-----BEGIN PRIVATE KEY-----', '')
    .replace('-----END PRIVATE KEY-----', '')
    .replace(/\s/g, ''),
)
const bytes = new Uint8Array(derBytes.length)
for (let i = 0; i < derBytes.length; i++) {
  bytes[i] = derBytes.charCodeAt(i)
}
const privateKey = bytes.slice(-32)
const keyBase64 = btoa(String.fromCharCode(...privateKey))

console.log('Your new OP_PRIVATE_KEY is:')
console.log(keyBase64)

OP_WALLET_ADDRESS

This is the public address of your wallet where you can receive payments.

  1. In your Interledger wallet dashboard, find your payment pointer. It will look something like $ilp.interledger-test.dev/my-wallet.
  2. To get the wallet address, simply replace the $ with https://.

For example, if your payment pointer is $ilp.interledger-test.dev/alice, your OP_WALLET_ADDRESS would be https://ilp.interledger-test.dev/alice.

AWS Configuration

These variables are for connecting to an S3 bucket, which is used to store the configuration for the publisher tools. For local development, a simulated S3 service is used, so you don't need real AWS credentials.

AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY

For local development, these values are ignored by the local S3 simulator. You can leave the default values from .env.sample as they are.

AWS_S3_ENDPOINT

For Development: Use the local S3 simulator, which runs on http://localhost:8081. This should be the default value in your .dev.vars.

AWS_S3_ENDPOINT="http://localhost:8081"

For Production: Use your actual S3 bucket endpoint, this would be the URL of your actual S3 bucket endpoint.

AWS_S3_ENDPOINT="https://your-bucket-name.s3.your-region.amazonaws.com"
How to get real AWS keys (for production use)
  1. Sign in to the AWS Management Console
  2. Navigate to IAM (Identity and Access Management)
  3. In the left sidebar, select "Users"
  4. Click on your user or create a new user with S3 permissions
  5. Go to the "Security credentials" tab
  6. Scroll down to "Access keys" and click "Create access key"
  7. Choose "Application running outside AWS"
  8. Copy the Access key ID Make sure to save both the Access Key ID and Secret Access Key when they are displayed, as AWS will not show the secret key again.

Required Permissions: S3 read/write access
Security Note: Never commit this value to version control

Umami Analytics

Optional. If unset, the analytics script is silently skipped. For local dev, start the Umami instance first:

cd localenv/umami && docker compose up -d

Then log in at http://localhost:3001 (default credentials: admin / umami), go to Settings → Websites → Add website, and copy the Website ID.

UMAMI_HOST="http://localhost:3001"
UMAMI_WEBSITE_ID="<your-website-id>"

Development vs Production

Development Setup

  • Uses local S3 simulation via localenv/s3
  • Uses Interledger testnet for payments
  • Safe for testing and development

Production Setup

  • Requires actual AWS S3 bucket
  • Uses live payment networks
  • Requires proper security measures

Troubleshooting

Common Issues

  • "OP_KEY_ID not found": Ensure your key ID is a valid UUID v4 format
  • "Invalid private key": Verify the private key is properly base64-encoded
  • "AWS access denied": Check that your IAM user has the necessary S3 permissions
  • "Connection refused to localhost:8081": Make sure the local S3 service is running (pnpm -C localenv/s3 dev)

Testing Your Configuration

After setting up your .dev.vars, you can test your configuration by running:

pnpm -r --parallel dev

Open the application on localhost:3000 try to use features or trigger configuration storage

Need Help?