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

```bash
# 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

```bash
# .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

```bash
# .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

```bash
# .env.staging
APP_NAME=MedsApp-Staging

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

### Production Environment

```bash
# .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

```bash
# 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`)

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