Configuration

Learn how to manage ao.config.yml and other configuration settings for your ao-forge projects.

Overview

ao-forge uses configuration files to manage project settings, AO processes, and deployment options.

Configuration Files

ao.config.yml

The main configuration file for your project:

# Project configuration
name: 'my-ao-app'
version: '1.0.0'
description: 'My AO-powered application'

# Framework configuration
framework: 'nextjs'  # or 'nuxtjs'
packageManager: 'pnpm'  # or 'npm', 'yarn'

# AO process configuration
luaFiles: ['counter.lua', 'token.lua']
autoStart: false
processName: 'my-process'

# Development configuration
ports:
  dev: 3000
  ao: 8080

# Build configuration
build:
  output: './dist'
  optimize: true
  sourceMaps: false

# Deployment configuration
deploy:
  platform: 'vercel'
  environment: 'production'

Configuration Management

Using ao-forge config

# Get configuration value
ao-forge config get framework

# Set configuration value
ao-forge config set framework nextjs

# List all configuration
ao-forge config list

# Validate configuration
ao-forge config validate

# Reset to defaults
ao-forge config reset

Configuration Commands

# Get specific value
ao-forge config get ports.dev

# Set specific value
ao-forge config set ports.dev 3001

# Remove configuration
ao-forge config remove deploy.platform

# Show configuration file
ao-forge config show

Framework Configuration

Next.js Configuration

# ao.config.yml
framework: 'nextjs'
nextjs:
  appDir: true
  typescript: true
  tailwind: true
  eslint: true
  prettier: true

Nuxt.js Configuration

# ao.config.yml
framework: 'nuxtjs'
nuxtjs:
  typescript: true
  tailwind: true
  eslint: true
  prettier: true
  modules: ['@nuxtjs/plausible']

AO Process Configuration

Process Settings

# ao.config.yml
processes:
  - name: 'counter'
    file: './ao/counter.lua'
    autoStart: true
    monitoring: true
  - name: 'token'
    file: './ao/token.lua'
    autoStart: false
    monitoring: false

Process Management

# Start specific process
ao-forge process start counter

# Stop specific process
ao-forge process stop counter

# Restart process
ao-forge process restart counter

# List processes
ao-forge process list

# Process status
ao-forge process status counter

Development Configuration

Port Configuration

# ao.config.yml
ports:
  dev: 3000        # Frontend development server
  ao: 8080         # AO process server
  monitoring: 9090 # Process monitoring

Environment Configuration

# ao.config.yml
environments:
  development:
    ports:
      dev: 3000
    debug: true
    hotReload: true
  staging:
    ports:
      dev: 3001
    debug: false
    hotReload: false
  production:
    ports:
      dev: 3000
    debug: false
    hotReload: false

Build Configuration

Build Settings

# ao.config.yml
build:
  output: './dist'
  optimize: true
  sourceMaps: false
  minify: true
  compression: true

Build Optimization

# ao.config.yml
build:
  optimization:
    treeshaking: true
    codesplitting: true
    deadCodeElimination: true
    constantFolding: true

Deployment Configuration

Platform Configuration

# ao.config.yml
deploy:
  platform: 'vercel'
  environment: 'production'
  domain: 'my-app.vercel.app'
  customDomain: 'my-app.com'

Platform-Specific Settings

# ao.config.yml
deploy:
  vercel:
    projectId: 'your-project-id'
    teamId: 'your-team-id'
    environment: 'production'
  netlify:
    siteId: 'your-site-id'
    buildCommand: 'ao-forge build'
    publishDirectory: './dist'
  github:
    repository: 'your-username/your-repo'
    branch: 'gh-pages'
    token: 'your-token'

Environment Variables

Frontend Environment

# .env.local
NEXT_PUBLIC_AO_PROCESS_ID=your-process-id
NEXT_PUBLIC_AO_GATEWAY=https://arweave.net
NEXT_PUBLIC_AO_ENVIRONMENT=production

AO Environment

# .env.ao
AO_WALLET_PATH=./wallet.json
AO_GATEWAY=https://arweave.net
AO_MODULE=your-module-id
AO_ENVIRONMENT=production

Configuration Validation

Validation Rules

# ao.config.yml
validation:
  required:
    - framework
    - packageManager
    - luaFiles
  optional:
    - ports
    - build
    - deploy

Validation Commands

# Validate configuration
ao-forge config validate

# Check for errors
ao-forge config validate --strict

# Fix configuration issues
ao-forge config fix

Configuration Templates

Basic Template

# ao.config.yml
name: 'my-ao-app'
framework: 'nextjs'
packageManager: 'pnpm'
luaFiles: ['counter.lua']
autoStart: false
ports:
  dev: 3000

Advanced Template

# ao.config.yml
name: 'my-ao-app'
version: '1.0.0'
description: 'My AO-powered application'
framework: 'nextjs'
packageManager: 'pnpm'

# AO processes
luaFiles: ['counter.lua', 'token.lua']
autoStart: false
processName: 'my-process'

# Development
ports:
  dev: 3000
  ao: 8080
  monitoring: 9090

# Build
build:
  output: './dist'
  optimize: true
  sourceMaps: false

# Deployment
deploy:
  platform: 'vercel'
  environment: 'production'
  domain: 'my-app.vercel.app'

Best Practices

Configuration Management

  1. Use version control for configuration files
  2. Document configuration options
  3. Validate configuration before deployment
  4. Use environment-specific configurations
  5. Keep secrets in environment variables

Security

  1. Never commit sensitive information
  2. Use environment variables for secrets
  3. Validate inputs in configuration
  4. Use secure defaults for production
  5. Regularly review configuration security

Performance

  1. Optimize build configuration
  2. Use appropriate port settings
  3. Configure monitoring properly
  4. Set up caching where appropriate
  5. Monitor resource usage

Troubleshooting

Common Issues

  1. Configuration not found
    # Check if ao.config.yml exists
ls -la ao.config.yml

# Create default configuration
ao-forge config init
  2. Invalid configuration
    # Validate configuration
ao-forge config validate

# Fix configuration issues
ao-forge config fix
  3. Configuration not applied
    # Reload configuration
ao-forge config reload

# Restart development server
ao-forge dev --restart

Getting Help

# Get help with configuration
ao-forge config --help

# Show configuration schema
ao-forge config schema

# List available options
ao-forge config options
Table of Contents