rxminder/docs/setup/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 with Makefile
DOCKER_IMAGE="myregistry.com/myapp:v1.0" make docker-build

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

Environment Files

# .env
APP_NAME=MyCustomApp
DOCKER_IMAGE=myregistry.com/mycustomapp:dev

# .env.production
APP_NAME=ProductionApp
DOCKER_IMAGE=myregistry.com/productionapp:latest

# .env.staging
APP_NAME=StagingApp
DOCKER_IMAGE=myregistry.com/stagingapp:staging

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

1. App name not displaying: Check config/unified.config.ts for correct APP_NAME value
2. Docker build fails: Check that environment variables are properly set

Testing

# Test configuration
bun run config

# Test build
bun run build

# Check configuration values
bun run config:env

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