rxminder/docs/APP_NAME_CONFIGURATION.md

APP_NAME Configuration Guide

This document explains how the APP_NAME environment variable is used throughout the application to customize branding and naming.

Overview

The APP_NAME environment variable allows you to customize the application name across all components, from the frontend UI to Docker containers and Kubernetes deployments.

Default Values

• Default APP_NAME: RxMinder
• Package name fallback: rxminder (lowercase)
• Docker tag fallback: meds (for backward compatibility)

Usage Examples

Setting APP_NAME

# For deployment
export APP_NAME="MyMedsApp"
make deploy

# For development
export APP_NAME="DevMeds"
bun run dev

# For Docker build
APP_NAME="CustomApp" docker build -t myapp .

Environment Files

# .env
APP_NAME=MyCustomApp

# .env.production
APP_NAME=ProductionApp

# .env.staging
APP_NAME=StagingApp

Where APP_NAME is Used

1. Frontend Application

• HTML Title: <title>$APP_NAME</title>
• UI Header: Button text shows APP_NAME value
• Environment Variable: Available as import.meta.env.VITE_APP_NAME

2. Docker Configuration

• Build Argument: Passed to Dockerfile as --build-arg APP_NAME=...
• Container Names: ${app_name_lower}-validation-test
• Image Tags: ${app_name_lower}-validation:latest
• Docker Compose: Labels include app=${APP_NAME}

3. Kubernetes Deployment

• Resource Names: ${APP_NAME}-frontend, ${APP_NAME}-config
• Labels: app: ${APP_NAME}
• Container Image: ${DOCKER_IMAGE:-registry/user/${APP_NAME}:latest}

4. Package Configuration

• Package Name: "name": "${APP_NAME:-rxminder}"

File Locations

Files That Use APP_NAME

1. Frontend Files:

• index.html.template - Page title
• App.tsx - UI header text
• vite.config.ts - Environment variable mapping

2. Docker Files:

• docker/Dockerfile - Build argument and environment variable
• docker/docker-compose.yaml - Build args and labels

3. Kubernetes Templates:

• k8s/frontend-deployment.yaml.template - Resource names and labels
• k8s/configmap.yaml.template - Resource names and labels
• All other k8s/*.yaml.template files

4. Scripts:

• scripts/deploy.sh - Container and image naming
• scripts/buildx-helper.sh - Container and image naming
• scripts/validate-deployment.sh - Container and image naming
• scripts/process-html.sh - HTML template processing

Build Process

Development Mode

1. bun run predev → Processes index.html.template → index.html
2. bun run dev → Starts development server

Production Build

1. Dockerfile processes index.html.template using envsubst
2. Vite build uses processed index.html
3. Final image contains customized HTML with correct title

Examples by Environment

Development Environment

# .env
APP_NAME=MedsApp-Dev
VITE_APP_NAME=MedsApp-Dev

# Results in:
# - HTML title: "MedsApp-Dev"
# - UI header: "MedsApp-Dev"
# - Docker containers: "medsapp-dev-validation-test"

Staging Environment

# .env.staging
APP_NAME=MedsApp-Staging

# Results in:
# - Kubernetes resources: "MedsApp-Staging-frontend"
# - Docker images: "medsapp-staging-validation:latest"

Production Environment

# .env.production
APP_NAME=MedicationTracker

# Results in:
# - All resources branded as "MedicationTracker"
# - Clean production naming

Case Handling

• Frontend: Uses original case (MyApp)
• Docker: Converts to lowercase (myapp)
• Kubernetes: Uses original case in labels, lowercase in DNS names

Troubleshooting

Common Issues

1. HTML title not updating: Ensure index.html.template exists and process-html.sh runs
2. Docker build fails: Check that APP_NAME doesn't contain invalid characters for Docker tags
3. Kubernetes deployment fails: Verify APP_NAME follows Kubernetes naming conventions

Validation

# Test HTML processing
APP_NAME=TestApp ./scripts/process-html.sh

# Test Docker build
APP_NAME=TestApp make deploy

# Check generated files
grep -r "TestApp" dist/

Best Practices

1. Use consistent naming: Keep APP_NAME consistent across all environments
2. Follow naming conventions: Use alphanumeric characters and hyphens
3. Avoid special characters: Docker and Kubernetes have naming restrictions
4. Document custom names: Include APP_NAME in your deployment documentation

Migration from Hardcoded Values

If you're migrating from hardcoded "meds" or "rxminder" references:

1. Set APP_NAME=meds to maintain backward compatibility
2. Test all deployment scripts with the new variable
3. Gradually update to your preferred application name
4. Update documentation and deployment guides

Environment Variable Precedence

1. Command-line environment variable (APP_NAME=...)
2. .env file in project root
3. Default value (RxMinder)

# Priority order:
APP_NAME=CmdLineApp make deploy-dev    # Highest priority
# vs .env file: APP_NAME=EnvFileApp
# vs default: RxMinder               # Lowest priority