Environment Setup

Overview

The Ecomdrop IA Connector uses environment variables to configure database connections, Shopify API credentials, and optional theme deployment settings. This guide provides detailed information about all available environment variables.

Never commit your .env file to version control. It contains sensitive credentials that should remain private.

Environment File

Creating the .env File

Create a .env file in the root directory of the project:

touch .env

Environment File Template

Here’s a complete template with all available configuration options:

# ============================================
# 🗄️ DATABASE CONFIGURATION
# ============================================
DATABASE_URL="mysql://username:password@host:port/database"

# ============================================
# 🔐 SHOPIFY API CREDENTIALS
# ============================================
SHOPIFY_API_KEY=your_api_key_here
SHOPIFY_API_SECRET=your_api_secret_here
SHOPIFY_APP_URL=https://your-app-url.com

# ============================================
# 🌐 APPLICATION CONFIGURATION
# ============================================
NODE_ENV=development
PORT=3000

# ============================================
# 🎨 THEME 2.5 CONFIGURATION (Optional)
# ============================================
THEME_2_5_GIT_REPO=Mercaline2024/Thema-ecomdro2.5
THEME_2_5_GIT_BRANCH=main
THEME_2_5_GIT_PROVIDER=github
THEME_2_5_GIT_TOKEN=your_github_token

# ============================================
# 🏪 CUSTOM DOMAIN (Optional)
# ============================================
SHOP_CUSTOM_DOMAIN=

Configuration Variables

Database Configuration

DATABASE_URL

string

required

MySQL connection string for the application database.Format:

mysql://username:password@host:port/database

Example Values:

DATABASE_URL="mysql://shopify_user:secure_password@localhost:3306/shopify_app"

The database must be MySQL 8.0 with UTF-8MB4 character set support.

Shopify API Configuration

SHOPIFY_API_KEY

string

required

Your Shopify app’s API key (also called Client ID).Where to find:

Go to Shopify Partners Dashboard
Select your app
Navigate to App setup > Client credentials
Copy the Client ID

Example:

SHOPIFY_API_KEY=f6edf6b48987a8adc8008aa6bb32b723

SHOPIFY_API_SECRET

string

required

Your Shopify app’s API secret (also called Client secret).Where to find:

Same location as API key
Copy the Client secret

Keep this secret secure. Never share it publicly or commit it to version control.

Example:

SHOPIFY_API_SECRET=shpss_1234567890abcdef1234567890abcdef

SHOPIFY_APP_URL

string

required

The public URL where your app is accessible.Development: Automatically set by Shopify CLI (tunnel URL)

SHOPIFY_APP_URL=https://amazing-cat-123.ngrok.io

Production: Your actual domain

SHOPIFY_APP_URL=https://connector.ecomdrop.io

This URL must match the App URL configured in your Shopify Partners Dashboard.

Application Configuration

NODE_ENV

string

default:"development"

The Node.js environment mode.Accepted values:

development - Development mode with hot reload and verbose logging
production - Production mode with optimizations and minimal logging
test - Test mode for running automated tests

Example:

# Development
NODE_ENV=development

# Production
NODE_ENV=production

PORT

number

default:"3000"

The port number the application server will listen on.Example:

PORT=3000

Change this if port 3000 is already in use on your system.

Theme Configuration (Optional)

These variables configure automatic Shopify theme installation from Git repositories.

THEME_2_5_GIT_REPO

string

The Git repository containing your Shopify theme.Format: username/repository or organization/repositoryExample:

THEME_2_5_GIT_REPO=Mercaline2024/Thema-ecomdro2.5

THEME_2_5_GIT_BRANCH

string

default:"main"

The Git branch to use for theme deployment.Example:

THEME_2_5_GIT_BRANCH=main

THEME_2_5_GIT_PROVIDER

string

The Git hosting provider.Accepted values:

github - GitHub
gitlab - GitLab
bitbucket - Bitbucket

Example:

THEME_2_5_GIT_PROVIDER=github

THEME_2_5_GIT_TOKEN

string

Personal access token for private Git repositories.When needed: Only required if your theme repository is privateGitHub Token Creation:

Go to GitHub Settings > Developer settings > Personal access tokens
Generate new token (classic)
Select scope: repo (Full control of private repositories)
Copy the token

Example:

THEME_2_5_GIT_TOKEN=ghp_1234567890abcdefghijklmnopqrstuvwxyz

This token grants access to your repositories. Keep it secure.

Custom Domain (Optional)

SHOP_CUSTOM_DOMAIN

string

Custom domain for Shopify store, if different from the .myshopify.com domain.Example:

SHOP_CUSTOM_DOMAIN=shop.example.com

Most apps don’t need this. Only use if your store uses a custom primary domain.

Environment-Specific Configurations

Development Environment

For local development:

.env.development

# Database - Local MySQL
DATABASE_URL="mysql://shopify_user:password@localhost:3306/shopify_app"

# Shopify - Development app credentials
SHOPIFY_API_KEY=dev_api_key
SHOPIFY_API_SECRET=dev_api_secret
SHOPIFY_APP_URL=https://tunnel-url.ngrok.io

# Application
NODE_ENV=development
PORT=3000

# Theme - Optional for testing
THEME_2_5_GIT_REPO=
THEME_2_5_GIT_BRANCH=develop
THEME_2_5_GIT_PROVIDER=github
THEME_2_5_GIT_TOKEN=

Use a separate development database to avoid affecting production data.

Production Environment

For production deployment:

.env.production

# Database - Production MySQL (Digital Ocean, PlanetScale, etc.)
DATABASE_URL="mysql://prod_user:secure_password@prod-db.example.com:3306/shopify_app?ssl-mode=REQUIRED"

# Shopify - Production app credentials
SHOPIFY_API_KEY=prod_api_key
SHOPIFY_API_SECRET=prod_api_secret
SHOPIFY_APP_URL=https://connector.ecomdrop.io

# Application
NODE_ENV=production
PORT=3000

# Theme - Production theme repository
THEME_2_5_GIT_REPO=Mercaline2024/Thema-ecomdro2.5
THEME_2_5_GIT_BRANCH=main
THEME_2_5_GIT_PROVIDER=github
THEME_2_5_GIT_TOKEN=ghp_production_token

Always use strong passwords and enable SSL for production database connections.

Docker Environment

For Docker deployment, environment variables are configured in docker-compose.yml:

docker-compose.yml

services:
  shopify_app:
    environment:
      DATABASE_URL: mysql://shopify_user:${MYSQL_PASSWORD}@mysql:3306/shopify_app
      SHOPIFY_API_KEY: ${SHOPIFY_API_KEY}
      SHOPIFY_API_SECRET: ${SHOPIFY_API_SECRET}
      SHOPIFY_APP_URL: https://connector.ecomdrop.io
      NODE_ENV: production
      PORT: 3000
      THEME_2_5_GIT_REPO: ${THEME_2_5_GIT_REPO}
      THEME_2_5_GIT_BRANCH: ${THEME_2_5_GIT_BRANCH}
      THEME_2_5_GIT_PROVIDER: ${THEME_2_5_GIT_PROVIDER}
      THEME_2_5_GIT_TOKEN: ${THEME_2_5_GIT_TOKEN}

Validating Configuration

Check Environment Variables

Verify your environment variables are loaded correctly:

# Print all environment variables (development only!)
node -e "console.log(process.env)"

# Check specific variable
node -e "console.log(process.env.DATABASE_URL)"

Never print environment variables in production logs as they contain sensitive credentials.

Test Database Connection

Test your database connection:

# Using Prisma
npx prisma db pull

# Should output: "Introspected X tables"

Validate Shopify Credentials

Start the dev server to validate Shopify credentials:

npm run dev

# Shopify CLI will validate your API credentials
# and warn you if something is misconfigured

Security Best Practices

Never Commit .env Files

Add .env to your .gitignore:

.gitignore

# Environment variables
.env
.env.local
.env.*.local

Use Strong Passwords

Generate strong passwords for database users:

# Generate a random password (macOS/Linux)
openssl rand -base64 32

Rotate Credentials Regularly

Change your database passwords and API tokens periodically:

Database passwords: Every 90 days
API tokens: Every 180 days
After team member departure: Immediately

Use Environment-Specific Credentials

Never use production credentials in development:

Separate database instances
Separate Shopify apps for dev/staging/prod
Different API keys per environment

Restrict Database Access

Configure MySQL user permissions:

-- Grant only necessary permissions
GRANT SELECT, INSERT, UPDATE, DELETE ON shopify_app.* TO 'shopify_user'@'localhost';

-- Don't grant DROP, CREATE, or admin privileges
FLUSH PRIVILEGES;

Troubleshooting

Environment Variables Not Loading

If your .env file isn’t being loaded:

Check file location: Must be in project root directory
Check file name: Must be exactly .env (note the leading dot)
Restart dev server: Changes require server restart

# Verify .env file exists
ls -la | grep .env

# Should output: .env

Invalid DATABASE_URL Format

Common DATABASE_URL mistakes:

# ❌ Wrong - missing protocol
DATABASE_URL="localhost:3306/shopify_app"

# ❌ Wrong - incorrect protocol
DATABASE_URL="postgres://user:pass@localhost:3306/shopify_app"

# ❌ Wrong - unencoded special characters in password
DATABASE_URL="mysql://user:p@ssw0rd@localhost:3306/shopify_app"

# ✅ Correct
DATABASE_URL="mysql://user:p%40ssw0rd@localhost:3306/shopify_app"

Use URL encoding for special characters in passwords: @ becomes %40, # becomes %23, etc.

Shopify App URL Mismatch

If you get “redirect_uri mismatch” errors:

Check Partners Dashboard:
- App URL: https://your-app-url.com
- Allowed redirect URLs: https://your-app-url.com/api/auth

Verify .env matches:

SHOPIFY_APP_URL=https://your-app-url.com

For development: Shopify CLI updates this automatically

Next Steps

After configuring your environment:

Database Setup

Set up MySQL and run Prisma migrations

Quickstart Guide

Complete the quick setup and run your app

Deployment Guide

Deploy to production with Docker and Traefik

Configuration

Configure Ecomdrop and Dropi integrations

Overview

Getting Started

Core Features

Integrations

Configuration

Deployment

Overview

Environment File

Creating the .env File

Environment File Template

Configuration Variables

Database Configuration

Shopify API Configuration

Application Configuration

Theme Configuration (Optional)

Custom Domain (Optional)

Environment-Specific Configurations

Development Environment

Production Environment

Docker Environment

Validating Configuration

Check Environment Variables

Test Database Connection

Validate Shopify Credentials

Security Best Practices

Troubleshooting

Environment Variables Not Loading

Invalid DATABASE_URL Format

Shopify App URL Mismatch

Next Steps

Database Setup

Quickstart Guide

Deployment Guide

Configuration

Overview

Getting Started

Core Features

Integrations

Configuration

Deployment

Documentation Index

​Overview

​Environment File

​Creating the .env File

​Environment File Template

​Configuration Variables

​Database Configuration

​Shopify API Configuration

​Application Configuration

​Theme Configuration (Optional)

​Custom Domain (Optional)

​Environment-Specific Configurations

​Development Environment

​Production Environment

​Docker Environment

​Validating Configuration

​Check Environment Variables

​Test Database Connection

​Validate Shopify Credentials

​Security Best Practices

​Troubleshooting

​Environment Variables Not Loading

​Invalid DATABASE_URL Format

​Shopify App URL Mismatch

​Next Steps

Database Setup

Quickstart Guide

Deployment Guide

Configuration

Overview

Environment File

Creating the .env File

Environment File Template

Configuration Variables

Database Configuration

Shopify API Configuration

Application Configuration

Theme Configuration (Optional)

Custom Domain (Optional)

Environment-Specific Configurations

Development Environment

Production Environment

Docker Environment

Validating Configuration

Check Environment Variables

Test Database Connection

Validate Shopify Credentials

Security Best Practices

Troubleshooting

Environment Variables Not Loading

Invalid DATABASE_URL Format

Shopify App URL Mismatch

Next Steps