Skip to content

Post_Installation_Management

Jump to bottom
Rafal Lagowski edited this page Sep 14, 2025 · 1 revision

🔧 Post-Installation Configuration Management

Complete guide for managing and updating your ClaudeAutoPM configuration after installation.

📋 Overview

ClaudeAutoPM provides comprehensive tools for managing your project configuration at any point after installation. You can add, modify, or remove configurations without reinstalling the framework.

🎯 Quick Reference

Task Command Description
Update .env autopm setup-env Reconfigure API keys and tokens
Manage MCP servers autopm mcp <command> Enable/disable MCP servers
Toggle features autopm config Switch Docker/K8s features
Update framework autopm update Update to latest version
Merge configs autopm merge AI-assisted config merging

📦 Environment Configuration (.env)

Updating API Keys and Tokens

# Reconfigure .env interactively
autopm setup-env

# For specific project
autopm setup-env ~/my-project

Features:

  • ✅ Interactive configuration wizard
  • ✅ Automatic backup of existing .env
  • ✅ Validation of token formats
  • ✅ Default values for quick setup
  • ✅ Clear error messages for invalid inputs

Manual .env Editing

Location: .claude/.env

# Example: Adding OpenAI API key manually
echo "OPENAI_API_KEY=sk-xxxxxxxxxxxxx" >> .claude/.env

# Example: Updating GitHub token
sed -i 's/GITHUB_TOKEN=.*/GITHUB_TOKEN=ghp_newtoken/' .claude/.env

Environment Variables Reference

# Core Services
CONTEXT7_API_KEY=         # Context7 documentation server
GITHUB_TOKEN=             # GitHub integration
PLAYWRIGHT_BROWSER=       # Browser for testing (chromium/firefox/webkit)
PLAYWRIGHT_HEADLESS=      # Run headless (true/false)

# Optional: Cloud Providers
AWS_ACCESS_KEY_ID=        # AWS credentials
AWS_SECRET_ACCESS_KEY=
AZURE_SUBSCRIPTION_ID=    # Azure credentials
AZURE_CLIENT_ID=
GCP_PROJECT_ID=          # Google Cloud credentials

# Optional: AI Providers
OPENAI_API_KEY=          # OpenAI API
GEMINI_API_KEY=          # Google Gemini API

# Optional: Enterprise
AZURE_DEVOPS_PAT=        # Azure DevOps token
AZURE_DEVOPS_ORG=        # Organization name

📡 MCP Server Management

Available Commands

autopm mcp <command> [options]
Command Description Example
list Show all available MCP servers autopm mcp list
enable <name> Enable a server in project autopm mcp enable context7-docs
disable <name> Disable a server autopm mcp disable github-mcp
add Add new server interactively autopm mcp add
remove <name> Remove server definition autopm mcp remove custom-server
sync Generate mcp-servers.json autopm mcp sync
validate Validate all definitions autopm mcp validate
info <name> Show server details autopm mcp info playwright-mcp

Example: Adding GitHub MCP After Installation

# 1. Enable GitHub MCP server
autopm mcp enable github-mcp

# 2. Add GitHub token if not already configured
autopm setup-env
# Enter GitHub token when prompted

# 3. Sync configuration
autopm mcp sync

# 4. Verify
autopm mcp list

Available MCP Servers

Server Description Required Token
context7-docs Documentation context CONTEXT7_API_KEY
context7-codebase Codebase analysis CONTEXT7_API_KEY
github-mcp GitHub operations GITHUB_TOKEN
playwright-mcp Browser automation None
filesystem-mcp File operations None
sqlite-mcp SQLite database None

Manual MCP Configuration

Location: .claude/mcp-servers.json

{
  "mcpServers": {
    "context7-docs": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "env": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
      }
    }
  }
}

⚙️ Feature Configuration

Toggle Docker/Kubernetes Features

# Interactive configuration menu
autopm config

Menu Options:

  1. Toggle Docker-first development
  2. Toggle Kubernetes testing
  3. Toggle GitHub Actions K8s
  4. Load configuration template
  5. Regenerate CLAUDE.md

Configuration Templates

Template Docker Kubernetes Use Case
minimal ❌ ❌ Simple projects, learning
docker-only ✅ ❌ Team consistency
full-devops ✅ ✅ Production deployments

Manual Configuration

Location: .claude/config.json

{
  "features": {
    "docker_first_development": true,
    "kubernetes_devops_testing": false,
    "github_actions_k8s": false,
    "enforce_docker_tests": true
  }
}

Switching Between Configurations

# Option 1: Interactive
autopm config
# Select "Load configuration template"
# Choose: minimal, docker-only, or full-devops

# Option 2: Manual
cp .claude/config-templates/docker-only.json .claude/config.json

# Regenerate CLAUDE.md after changes
.claude/scripts/config/toggle-features.sh

🔄 Framework Updates

Updating ClaudeAutoPM

# Update to latest version
autopm update

# Update specific project
autopm update ~/my-project

Features:

  • ✅ Preserves your configuration
  • ✅ Creates automatic backup
  • ✅ Merges new features
  • ✅ Updates documentation

Handling Configuration Conflicts

# If conflicts arise during update
autopm merge

This launches AI-assisted merge helper that:

  1. Analyzes both configurations
  2. Identifies conflicts
  3. Suggests optimal merge
  4. Preserves customizations

📝 Manual File Editing

Key Configuration Files

File Purpose When to Edit
.claude/.env API keys and tokens Adding new services
.claude/config.json Feature toggles Changing workflow
.claude/mcp-servers.json MCP server config Custom MCP servers
.claude/ACTIVE_STRATEGY.md Execution strategy Performance tuning
.claude/base.md Project context Project-specific rules

Editing Strategy Configuration

Location: .claude/strategies/ACTIVE_STRATEGY.md

Available strategies:

  • sequential.md - One agent at a time (safest)
  • adaptive.md - Smart parallelization (default)
  • hybrid.md - Maximum parallelization (fastest)
# Switch strategy
cd .claude/strategies
ln -sf hybrid.md ACTIVE_STRATEGY.md

🎯 Common Scenarios

Scenario 1: Adding OpenAI Integration

# Method 1: Interactive
autopm setup-env
# Answer 'y' when asked about AI providers
# Enter OpenAI API key

# Method 2: Manual
echo "OPENAI_API_KEY=sk-xxxxx" >> .claude/.env

Scenario 2: Enabling Docker Development

# Interactive toggle
autopm config
# Select option 1: Toggle Docker-first development
# Select option 8: Regenerate CLAUDE.md

Scenario 3: Adding Azure DevOps

# Step 1: Add credentials
autopm setup-env
# Configure Azure DevOps when prompted

# Step 2: Update CI/CD
autopm config
# Configure for Azure DevOps workflows

Scenario 4: Switching from Minimal to Docker

# Load Docker-only template
autopm config
# Select: Load configuration template
# Choose: docker-only
# Regenerate CLAUDE.md

🛠️ Troubleshooting

Token Validation Issues

Problem: Token rejected during setup

❌ Token too short! Your token has 15 characters.
   Required: Minimum 20 characters

Solution: Ensure you're copying the entire token, check for:

  • Missing characters at beginning/end
  • Extra spaces or line breaks
  • Wrong token type (e.g., using OAuth token instead of PAT)

MCP Server Not Working

Problem: MCP server fails to start

Checklist:

  1. Verify token in .env: grep CONTEXT7 .claude/.env
  2. Check server is enabled: autopm mcp list
  3. Validate configuration: autopm mcp validate
  4. Sync configuration: autopm mcp sync
  5. Check logs: ~/.claude/logs/mcp-*.log

Configuration Not Taking Effect

Problem: Changes to config.json not reflected

Solution:

# Regenerate CLAUDE.md after config changes
.claude/scripts/config/toggle-features.sh

# Restart Claude Code for changes to take effect

🔐 Security Best Practices

Token Management

  1. Never commit .env files

    # Verify .env is in .gitignore
grep "\.env" .gitignore

  2. Use environment-specific files

    .claude/.env.development
.claude/.env.production

  3. Rotate tokens regularly

    # Update tokens quarterly
autopm setup-env

  4. Use secrets management in production

    • AWS Secrets Manager
    • Azure Key Vault
    • HashiCorp Vault

File Permissions

# Secure .env file (owner read/write only)
chmod 600 .claude/.env

# Verify permissions
ls -la .claude/.env
# Should show: -rw-------

📚 Advanced Configuration

Custom MCP Servers

Create custom server definition:

# Create server definition
cat > .claude/mcp/custom-api.md << 'EOF'
---
name: custom-api
description: Custom API integration
enabled: false
---

## Configuration
```json
{
  "command": "node",
  "args": ["custom-mcp-server.js"],
  "env": {
    "API_KEY": "${CUSTOM_API_KEY}"
  }
}

EOF

Enable and sync

autopm mcp enable custom-api autopm mcp sync


### Environment-Specific Configurations

```bash
# Development config
cp .claude/config.json .claude/config.dev.json

# Production config
cp .claude/config-templates/full-devops.json .claude/config.prod.json

# Switch based on environment
export CLAUDE_ENV=production
cp .claude/config.${CLAUDE_ENV}.json .claude/config.json

Automation Scripts

Create update script:

#!/bin/bash
# update-config.sh

# Update framework
autopm update

# Reconfigure environment
autopm setup-env

# Sync MCP servers
autopm mcp sync

# Validate everything
autopm mcp validate

echo "✅ Configuration updated successfully"

🔗 Related Documentation

💡 Tips and Best Practices

  1. Always backup before major changes

    cp -r .claude .claude.backup.$(date +%Y%m%d)

  2. Test configuration changes in development first

  3. Use version control for config files

    git add .claude/config.json .claude/ACTIVE_STRATEGY.md
git commit -m "chore: Update project configuration"

  4. Document custom configurations

    echo "# Custom Config Notes" >> .claude/CONFIG_NOTES.md

  5. Keep tokens in password manager

    • Never store in plain text files
    • Use password manager for backup
    • Enable 2FA where possible

📞 Getting Help

Clone this wiki locally