marketing/DOCKER_ENV.md

Docker Environment Variables Guide

This guide explains how to use environment variables with Docker builds for your Vue.js application.

Problem

The original Dockerfile didn't handle environment variables from .env files because:

1. Vite requires environment variables to be available at build time
2. Docker builds don't automatically read .env files
3. Environment variables need to be passed as build arguments

Solution

The updated Dockerfile now accepts build-time environment variables using ARG and ENV instructions.

How to Use

1. Create a .env file

Create a .env file in your project root with your environment variables:

# .env
VITE_API_BASE_URL=https://api.yourdomain.com
VITE_API_TIMEOUT=10000
VITE_APP_TITLE=My App
VITE_APP_VERSION=1.0.0
VITE_AUTH_TOKEN_KEY=auth_token
VITE_REFRESH_TOKEN_KEY=refresh_token
VITE_ENABLE_ANALYTICS=true
VITE_ENABLE_DEBUG=false
VITE_GOOGLE_ANALYTICS_ID=GA-XXXXXXXXX
VITE_SENTRY_DSN=https://your-sentry-dsn

2. Build with Environment Variables

Option A: Using docker build with --build-arg

docker build \
  --build-arg VITE_API_BASE_URL=https://api.yourdomain.com \
  --build-arg VITE_APP_TITLE="My App" \
  --build-arg VITE_ENABLE_DEBUG=false \
  -t sakai-vue .

Option B: Using docker-compose with env_file

Create a docker-compose.yml:

version: '3.8'
services:
    sakai-vue:
        build:
            context: .
            dockerfile: Dockerfile
            args:
                VITE_API_BASE_URL: ${VITE_API_BASE_URL}
                VITE_APP_TITLE: ${VITE_APP_TITLE}
                VITE_ENABLE_DEBUG: ${VITE_ENABLE_DEBUG}
        ports:
            - '80:80'

Then run:

docker-compose up --build

Option C: Using a script to read .env file

Create a build.sh script:

#!/bin/bash
# build.sh

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
fi

# Build Docker image with environment variables
docker build \
  --build-arg VITE_API_BASE_URL="$VITE_API_BASE_URL" \
  --build-arg VITE_API_TIMEOUT="$VITE_API_TIMEOUT" \
  --build-arg VITE_APP_TITLE="$VITE_APP_TITLE" \
  --build-arg VITE_APP_VERSION="$VITE_APP_VERSION" \
  --build-arg VITE_AUTH_TOKEN_KEY="$VITE_AUTH_TOKEN_KEY" \
  --build-arg VITE_REFRESH_TOKEN_KEY="$VITE_REFRESH_TOKEN_KEY" \
  --build-arg VITE_ENABLE_ANALYTICS="$VITE_ENABLE_ANALYTICS" \
  --build-arg VITE_ENABLE_DEBUG="$VITE_ENABLE_DEBUG" \
  --build-arg VITE_GOOGLE_ANALYTICS_ID="$VITE_GOOGLE_ANALYTICS_ID" \
  --build-arg VITE_SENTRY_DSN="$VITE_SENTRY_DSN" \
  -t sakai-vue .

Make it executable and run:

chmod +x build.sh
./build.sh

Available Environment Variables

The following environment variables are supported in the Dockerfile:

• VITE_API_BASE_URL - Base URL for your API
• VITE_API_TIMEOUT - API request timeout in milliseconds
• VITE_APP_TITLE - Application title
• VITE_APP_VERSION - Application version
• VITE_AUTH_TOKEN_KEY - Key for storing auth token
• VITE_REFRESH_TOKEN_KEY - Key for storing refresh token
• VITE_ENABLE_ANALYTICS - Enable/disable analytics
• VITE_ENABLE_DEBUG - Enable/disable debug mode
• VITE_GOOGLE_ANALYTICS_ID - Google Analytics tracking ID
• VITE_SENTRY_DSN - Sentry DSN for error tracking

Security Notes

1. Never commit .env files - They're already in .gitignore
2. Use .dockerignore - Prevents .env files from being copied to the build context
3. Use build secrets for sensitive data in production:

   docker build --secret id=env,src=.env -t sakai-vue .
   

Troubleshooting

Environment variables not working?

1. Make sure your .env file exists and has the correct variable names
2. Verify the variables are prefixed with VITE_
3. Check that you're passing them as build arguments
4. Ensure the variables are available at build time (not runtime)

Build fails?

1. Check that all required environment variables are provided
2. Verify the variable names match exactly (case-sensitive)
3. Make sure there are no syntax errors in your .env file

Development vs Production

• Development: Use .env.local or .env.development
• Production: Use .env.production or pass variables directly via build args
• Testing: Use .env.test

The Dockerfile will work with any of these approaches as long as the variables are passed as build arguments.