# Environment Management Guide

This guide covers the comprehensive environment management system in the Flux Gate, including creating, configuring, and managing deployment environments.

## 🎯 Overview

Environments represent different deployment targets where your features can be deployed (e.g., development, staging, production). The environment management system provides controlled feature rollout across different infrastructure environments.

## 🔐 Access Requirements

To manage environments, you need:

- **Admin Role**: Full environment management capabilities
- **Admin Flag**: `is_admin: true` in JWT token

⚠️ **Note**: Environment management is typically restricted to administrators as it affects deployment infrastructure.

## 🌍 Environment Concept

### What are Environments?

Environments are logical deployment targets that represent:

- **Development**: Local or shared development environment
- **Staging**: Pre-production testing environment  
- **Production**: Live production environment
- **Testing**: Dedicated testing environment
- **Demo**: Customer demonstration environment

### Environment Properties

Each environment has:

| Property | Description |
|----------|-------------|
| **Name** | Environment identifier (e.g., "Production", "Staging") |
| **Active** | Whether the environment is currently available |
| **Configuration** | Environment-specific settings |

## 📋 Environment Management Interface

### Accessing Environment Management

1. **Navigation**: Go to Environments page
2. **Environment Table**: View all configured environments
3. **Actions**: Create, edit, and manage environments

### Environment Table

The environments table displays:

| Column | Description |
|--------|-------------|
| **Name** | Environment name/identifier |
| **Active** | Status indicator (active/inactive) |
| **Actions** | Edit and delete options |

## ➕ Creating New Environments

### Environment Creation Process

1. **Navigate**: Go to Environments page
2. **Create Button**: Click "Create New Environment"
3. **Modal Form**: Fill out environment creation form

### Environment Creation Form

| Field | Required | Description |
|-------|----------|-------------|
| **Name** | ✅ | Unique environment identifier |
| **Active** | ❌ | Environment availability status (default: active) |

#### Example Environments

```
Name: Development
Active: Yes
```

```
Name: Staging  
Active: Yes
```

```
Name: Production
Active: Yes
```

```
Name: Demo
Active: No (temporarily disabled)
```

### Creation Steps

1. **Environment Name**: Enter descriptive name
2. **Active Status**: Set availability
3. **Create**: Submit the form
4. **Verification**: Confirm environment appears in list

## ✏️ Editing Environments

### Edit Environment Details

1. **Environment Table**: Find environment to edit
2. **Edit Action**: Click "Edit" button
3. **Edit Modal**: Modify environment properties
4. **Save Changes**: Update environment configuration

### Editable Properties

- **Name**: Update environment identifier
- **Active Status**: Enable/disable environment

### Environment Status Management

#### Active Environments
- Available for feature deployment
- Visible in deployment pipelines
- Can be selected for new features

#### Inactive Environments  
- Temporarily disabled
- Not available for new deployments
- Existing deployments remain intact

## 🏗️ Environment Architecture

### Typical Environment Setup

```
Development Environment
├── Local Development
├── Feature Branches
└── Integration Testing

Staging Environment
├── Pre-production Testing
├── User Acceptance Testing
└── Performance Testing

Production Environment
├── Live Production
├── Customer Facing
└── High Availability
```

### Environment Progression

Features typically progress through environments:

```
Development → Staging → Production
     ↓           ↓          ↓
   Testing    UAT/QA    Live Users
```

## 🔧 Environment Integration

### Feature Deployment Pipeline

Environments integrate with the feature deployment system:

1. **Feature Creation**: Select target environments
2. **Pipeline Configuration**: Define environment progression
3. **Stage Mapping**: Map pipeline stages to environments
4. **Deployment Flow**: Control feature rollout per environment

### Environment-Specific Configuration

Each environment can have:

- **Different Feature States**: Features can be enabled in dev but disabled in prod
- **Context Variations**: Environment-specific context values
- **Rollout Percentages**: Different rollout percentages per environment
- **Pipeline Stages**: Environment-specific pipeline configurations

## 🎯 Environment-Based Feature Control

### Environment Scoping

Features can be configured differently per environment:

| Feature | Development | Staging | Production |
|---------|-------------|---------|------------|
| **New UI** | 100% enabled | 50% rollout | 10% rollout |
| **Beta API** | Enabled | Enabled | Disabled |
| **Debug Mode** | Enabled | Enabled | Disabled |

### Environment Isolation

Environments provide isolation for:

- **Feature Testing**: Safe testing without affecting production
- **Configuration Management**: Environment-specific settings
- **Risk Management**: Controlled rollout across environments
- **Rollback Safety**: Environment-specific rollback capabilities

## 🔄 Environment Lifecycle

### Environment States

Environments can transition between states:

```
Planning → Creation → Active → Maintenance → Retirement
    ↓         ↓        ↓          ↓           ↓
  Design   Deploy   Running   Updates    Cleanup
```

### Environment Maintenance

Regular maintenance tasks:

1. **Status Monitoring**: Monitor environment health
2. **Configuration Updates**: Update environment settings
3. **Access Reviews**: Review environment access permissions
4. **Cleanup**: Remove unused or deprecated environments

## 📊 Environment Monitoring

### Environment Analytics

Track environment usage:

- **Feature Deployments**: Number of features per environment
- **Deployment Frequency**: How often deployments occur
- **Success Rates**: Deployment success/failure rates
- **Resource Usage**: Environment resource consumption

### Environment Health

Monitor environment status:

- **Availability**: Environment uptime and availability
- **Performance**: Response times and performance metrics
- **Error Rates**: Environment-specific error tracking
- **Capacity**: Resource utilization and capacity planning

## 🚨 Environment Best Practices

### Naming Conventions

Use consistent environment naming:

```
# Standard environments
development
staging  
production

# Extended environments
dev
test
uat
prod

# Project-specific environments
project-alpha-dev
project-alpha-staging
project-alpha-prod
```

### Environment Configuration

Configure environments appropriately:

1. **Development**:
   - High feature toggle availability
   - Verbose logging enabled
   - Lower security restrictions

2. **Staging**:
   - Production-like configuration
   - Full feature testing
   - Performance monitoring

3. **Production**:
   - Strict security controls
   - Conservative feature rollout
   - Comprehensive monitoring

### Environment Security

Implement security best practices:

- **Access Control**: Restrict environment access by role
- **Configuration Management**: Secure environment-specific configs
- **Audit Logging**: Track environment changes
- **Compliance**: Meet regulatory requirements per environment

## 🔧 Environment Administration

### Environment Cleanup

Regular cleanup activities:

1. **Remove Unused Environments**: Clean up test/temporary environments
2. **Update Environment Status**: Maintain accurate active/inactive status
3. **Documentation**: Keep environment documentation current
4. **Access Audits**: Review and update environment access

### Environment Scaling

As your system grows:

1. **Regional Environments**: Add geo-specific environments
2. **Customer Environments**: Dedicated customer environments
3. **Testing Environments**: Specialized testing environments
4. **Integration Environments**: Third-party integration environments

## 🚫 Environment Deletion

### Deletion Considerations

Before deleting an environment:

⚠️ **Warning**: Environment deletion may impact active features and deployments.

1. **Check Active Features**: Verify no features are actively using the environment
2. **Backup Configuration**: Save environment configuration if needed
3. **Team Notification**: Notify teams of environment removal
4. **Migration Plan**: Plan migration of features to other environments

### Deletion Process

Currently, environment deletion is handled through:

1. **Database Operations**: Direct database environment removal
2. **Feature Updates**: Update features using the deleted environment
3. **Pipeline Updates**: Update pipelines referencing the environment

## 🚨 Troubleshooting

### Common Issues

**Cannot Create Environment**
```
Error: Environment name already exists
```
*Solution*: Choose a unique environment name.

**Cannot Edit Environment**
```
Access Denied: Admin privileges required
```
*Solution*: Ensure you have Admin role or admin flag.

**Environment Not Showing in Pipelines**
```
Environment not available for selection
```
*Solution*: Check that environment is marked as "Active".

### Environment Access Issues

If environments don't appear in feature creation:

1. **Check Status**: Verify environment is active
2. **Refresh Data**: Try refreshing the page
3. **Team Assignment**: Verify team has access to environment
4. **Role Verification**: Confirm user has appropriate roles

## 💡 Tips and Recommendations

### Environment Strategy

1. **Start Simple**: Begin with basic dev/staging/prod setup
2. **Expand Gradually**: Add environments as needs grow
3. **Consistent Naming**: Use consistent naming conventions
4. **Documentation**: Document environment purposes and configurations

### Integration Planning

1. **CI/CD Alignment**: Align environments with CI/CD pipeline
2. **Infrastructure Matching**: Match logical environments to infrastructure
3. **Security Boundaries**: Align environments with security zones
4. **Monitoring Integration**: Integrate with monitoring and alerting systems

### Environment Evolution

1. **Review Regularly**: Periodically review environment needs
2. **Retire Unused**: Remove environments no longer needed
3. **Optimize Resources**: Optimize environment resource usage
4. **Update Documentation**: Keep environment documentation current

## 🔗 Related Documentation

- [Pipeline Management](Pipeline-Management.md) - Creating deployment pipelines
- [Feature Toggle Management](Feature-Toggle-Management.md) - Managing features across environments
- [Context Management](Context-Management.md) - Environment-specific contexts
- [Deployment Guide](Deployment-Guide.md) - Infrastructure deployment

---

*Need help? Check the [Troubleshooting](Troubleshooting.md) guide or create an issue in the project repository.*