Environment Variables

This document provides a complete reference for all environment variables used to configure Arrow.

Overview

Arrow uses environment variables for configuration, allowing you to customize behavior without modifying code. Variables are read from .env files in the backend and frontend directories respectively.

Backend Environment Variables

Required Variables

These variables must be configured for Arrow to function:

Variable	Description	Example
`B2_BUCKET`	Primary S3-compatible storage bucket name	`arrow-storage`
`B2_REGION`	Storage bucket region	`us-east-1`
`B2_ENDPOINT`	S3-compatible endpoint URL	`https://s3.us-east-1.backblazeb2.com`
`B2_KEY_ID`	Storage access key ID	`your-key-id`
`B2_APP_KEY`	Storage secret access key	`your-app-key`
`B2_ARROW_MANAGER_BUCKET`	Bucket for Arrow Manager files	`arrow-manager-files`
`B2_ARROW_CONTROL_BUCKET`	Bucket for Arrow Control files	`arrow-control-files`
`B2_PUBLIC_BUCKET`	Bucket for public assets	`arrow-public`
`DASHBOARD_URL`	Full URL of the Arrow dashboard	`https://arrow.yourcompany.com`

EasyPost Integration

Configure these variables for shipment tracking functionality:

Variable	Description	Example
`EASYPOST_PRODUCTION_API_KEY`	EasyPost production API key	`EZAKxxxxxxxx`
`EASYPOST_TEST_API_KEY`	EasyPost test/sandbox API key	`EZTKxxxxxxxx`
`EASYPOST_USE_TEST_FOR_SHIPMENTS`	Use test API for shipments (`true`/`false`)	`false`
`EASYPOST_WEBHOOK_SECRET`	Secret for validating EasyPost webhooks	`whsec_xxxxxxxx`

HelpScout Integration

Configure these variables for support ticket integration:

Variable	Description	Example
`HELPSCOUT_CLIENT_ID`	HelpScout OAuth client ID	`your-client-id`
`HELPSCOUT_CLIENT_SECRET`	HelpScout OAuth client secret	`your-client-secret`
`HELPSCOUT_MAILBOX_ID`	HelpScout mailbox ID for tickets	`12345`

Mapping and Location

Configure these variables for geocoding and mapping features:

Variable	Description	Example
`MAPBOX_ACCESS_TOKEN`	Mapbox API access token	`pk.xxxxxxxx`

Cellular and GPS

Configure these variables for cellular connectivity and GPS tracking:

Variable	Description	Example
`SIMPLEX_API_USERNAME`	Simplex Wireless API username	`your-username`
`SIMPLEX_API_PASSWORD`	Simplex Wireless API password	`your-password`
`BLUES_WEBHOOK_SECRET`	Secret for validating Blues Notecard webhooks	`your-webhook-secret`

Cloudflare Services

Configure these variables for Cloudflare integration:

Variable	Description	Example
`CLOUDFLARE_API_TOKEN`	Cloudflare API token	`your-api-token`
`CLOUDFLARE_ZONE_ID`	Cloudflare zone ID for your domain	`zone-id`
`CLOUDFLARE_TURNSTILE_SECRET_KEY`	Turnstile CAPTCHA secret key	`0x4xxxxxxxx`

Optional Variables

These variables enable additional functionality:

Variable	Description	Example
`BUILD_API_URL`	VM build automation endpoint URL	`https://build.yourcompany.com/api`
`DEVICE_LOOKUP_API_KEY`	API key for device lookup service	`your-api-key`
`GITHUB_PAT`	GitHub personal access token for releases	`ghp_xxxxxxxx`
`TESTING_API_KEY`	API key for testing endpoints	`test-api-key`

Logging Configuration

Configure logging behavior with these variables:

Variable	Description	Default
`LOG_LEVEL`	Minimum log level (`debug`, `info`, `warn`, `error`)	`info`
`LOG_DIR`	Directory for log files	`./logs`
`LOG_FILE`	Log file name	`arrow.log`
`LOG_MAX_SIZE`	Maximum log file size in MB before rotation	`100`
`LOG_MAX_AGE`	Maximum days to retain old log files	`30`
`LOG_MAX_BACKUPS`	Maximum number of old log files to retain	`5`
`LOG_COMPRESS`	Compress rotated log files (`true`/`false`)	`true`
`LOG_CONSOLE`	Also output logs to console (`true`/`false`)	`true`
`LOG_JSON`	Output logs in JSON format (`true`/`false`)	`false`
`LOG_CALLER`	Include caller info in logs (`true`/`false`)	`false`

Licensing Configuration

Configure these variables for license management:

Variable	Description	Example
`LICENSE_PRIVATE_KEY_PATH`	Path to license signing private key	`/etc/arrow/license.key`
`LICENSE_PUBLIC_KEY_PATH`	Path to license verification public key	`/etc/arrow/license.pub`
`LICENSING_API_KEY`	API key for licensing service	`your-api-key`

Security Configuration

Configure these security-related variables:

Variable	Description	Example
`LETSENCRYPT_EMAIL`	Email for Let’s Encrypt certificate notifications	`admin@yourcompany.com`
`TURNSTILE_DEV_BYPASS_TOKEN`	Development bypass token for Turnstile	`dev-bypass-token`
`ENV`	Environment mode (`development` or `production`)	`production`

Frontend Environment Variables

Configure these variables in the frontend .env file:

Variable	Description	Default
`VITE_API_URL`	PocketBase API URL	`http://localhost:8090`
`VITE_VPN_BASE_DOMAIN`	Base domain for Arrow Control DNS-based URLs. Used when VMs have DNS enabled to construct hostname-based URLs for Arrow Control access.	`arrowvpn.io`

Setup Instructions

Backend Setup

Navigate to the backend directory:
Terminal window
```
cd backend
```
Copy the example environment file:
Terminal window
```
cp .env.example .env
```
Edit the .env file with your configuration:
Terminal window
```
nano .env
```
At minimum, configure all required variables listed above.
Restart the backend service after making changes.

Frontend Setup

Navigate to the frontend directory:
Terminal window
```
cd frontend
```
Create a .env file:
Terminal window
```
touch .env
```

Add the frontend environment variables:

VITE_API_URL=http://localhost:8090
VITE_VPN_BASE_DOMAIN=arrowvpn.io

Restart the development server or rebuild for production.

Security Best Practices

Follow these practices to keep your configuration secure:

Never Commit Secrets

Add .env files to your .gitignore:

.env
.env.local
.env.*.local

Use Different Keys Per Environment

Maintain separate credentials for:

Development: Use test/sandbox API keys where available
Staging: Separate credentials from production
Production: Production-only credentials with restricted access

Rotate Credentials Regularly

Change API keys and secrets periodically
Update credentials immediately if compromised
Use secret management tools for production (e.g., HashiCorp Vault, AWS Secrets Manager)

Principle of Least Privilege

Only enable integrations you need
Use API keys with minimal required permissions
Restrict access to production credentials

Validate Before Deployment

Before deploying, verify:

All required variables are set
URLs are correct (no trailing slashes)
API keys are valid and active
Webhook secrets are configured for all enabled webhooks

Troubleshooting

Common Issues

Issue	Solution
”Missing required environment variable”	Ensure all required variables are set in `.env`
API integration not working	Verify API keys are valid and have correct permissions
Webhook failures	Check webhook secret matches the integration’s configuration
File upload failures	Verify S3/B2 credentials and bucket permissions
Authentication errors	Check Zitadel configuration and callback URLs

Verifying Configuration

Test your configuration by checking the backend logs on startup. Arrow will log warnings for missing optional variables and errors for missing required variables.

Next Steps

Installation - Complete installation guide
Architecture - Understand how Arrow uses these configurations
Troubleshooting - Resolve common issues