Configuration

Configure Lightfold deployments and targets

Configuration Files

Lightfold uses three configuration files:

Main Config (~/.lightfold/config.json)

Target-based configuration storing deployment settings.

{
  "targets": {
    "myapp-prod": {
      "project_path": "/path/to/project",
      "framework": "Next.js",
      "provider": "digitalocean",
      "builder": "nixpacks",
      "provider_config": {
        "digitalocean": {
          "ip": "192.168.1.100",
          "username": "deploy",
          "ssh_key": "~/.lightfold/keys/lightfold_ed25519",
          "region": "nyc1",
          "size": "s-1vcpu-1gb",
          "provisioned": true,
          "droplet_id": "123456789"
        }
      },
      "domain_config": {
        "domain": "example.com",
        "ssl_enabled": true,
        "ssl_manager": "certbot",
        "proxy_type": "nginx"
      },
      "deploy": {
        "env_vars": {
          "NODE_ENV": "production",
          "DATABASE_URL": "postgres://..."
        },
        "build_command": "",
        "run_command": "",
        "skip_build": false
      }
    }
  }
}

API Tokens (~/.lightfold/tokens.json)

Secure API token storage (0600 permissions).

{
  "digitalocean": "dop_v1_...",
  "vultr": "...",
  "hetzner": "..."
}

Manage tokens:

# Set token
lightfold config set-token digitalocean

# Get token
lightfold config get-token digitalocean

# List all targets
lightfold config list

State Files (~/.lightfold/state/<target>.json)

Per-target deployment state tracking.

{
  "created": true,
  "configured": true,
  "last_commit": "abc123...",
  "last_deploy": "2025-10-03T10:30:00Z",
  "last_release": "20251003103000",
  "provisioned_id": "123456789",
  "builder": "nixpacks"
}

Target Configuration

Creating Targets

Targets are created automatically during first deployment:

lightfold deploy --target myapp

Or create explicitly:

lightfold create --target myapp --provider digitalocean

Target Naming

Use descriptive target names for different environments:

• myapp-prod - Production
• myapp-staging - Staging
• myapp-dev - Development

Multiple Targets

Deploy the same project to multiple environments:

# Production
lightfold deploy --target myapp-prod

# Staging
lightfold deploy --target myapp-staging

Each target has independent configuration and state.

Provider Configuration

DigitalOcean

{
  "provider": "digitalocean",
  "provider_config": {
    "digitalocean": {
      "ip": "192.168.1.100",
      "username": "deploy",
      "ssh_key": "~/.lightfold/keys/lightfold_ed25519",
      "region": "nyc1",
      "size": "s-1vcpu-1gb",
      "provisioned": true,
      "droplet_id": "123456789"
    }
  }
}

Vultr

{
  "provider": "vultr",
  "provider_config": {
    "vultr": {
      "ip": "192.168.1.100",
      "username": "deploy",
      "ssh_key": "~/.lightfold/keys/lightfold_ed25519",
      "region": "ewr",
      "plan": "vc2-1c-1gb",
      "provisioned": true,
      "server_id": "abc-123"
    }
  }
}

Hetzner Cloud

{
  "provider": "hetzner",
  "provider_config": {
    "hetzner": {
      "ip": "192.168.1.100",
      "username": "deploy",
      "ssh_key": "~/.lightfold/keys/lightfold_ed25519",
      "location": "nbg1",
      "server_type": "cx11",
      "provisioned": true,
      "server_id": "123456"
    }
  }
}

BYOS (Bring Your Own Server)

{
  "provider": "byos",
  "provider_config": {
    "byos": {
      "ip": "1.2.3.4",
      "username": "deploy",
      "ssh_key": "~/.ssh/id_rsa",
      "provisioned": false
    }
  }
}

Domain Configuration

Add Domain

lightfold domain add --domain example.com --target myapp

Configuration:

{
  "domain_config": {
    "domain": "example.com",
    "ssl_enabled": true,
    "ssl_manager": "certbot",
    "proxy_type": "nginx"
  }
}

Remove Domain

lightfold domain remove --target myapp

Reverts to IP-based access.

Deployment Configuration

Environment Variables

Set environment variables in config:

{
  "deploy": {
    "env_vars": {
      "NODE_ENV": "production",
      "DATABASE_URL": "postgres://user:pass@host:5432/db",
      "API_KEY": "secret"
    }
  }
}

Or use .env file in project root:

NODE_ENV=production
DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=secret

Note: .env file is automatically loaded during deployment.

Custom Build Commands

Override auto-detected build commands:

{
  "deploy": {
    "build_command": "npm run custom-build",
    "run_command": "npm run start:prod"
  }
}

Skip Build

Skip build step (for pre-built apps):

{
  "deploy": {
    "skip_build": true
  }
}

Custom Health Checks

Define custom health check endpoint:

{
  "deploy": {
    "health_check": {
      "path": "/api/health",
      "expect": 200,
      "timeout_seconds": 30
    }
  }
}

Builder Configuration

Force Builder

Specify builder in config:

{
  "builder": "nixpacks"
}

Or use flag:

lightfold deploy --builder nixpacks

Available builders:

• native - Traditional build with nginx
• nixpacks - Railway’s Nixpacks (auto-detected)
• dockerfile - Use existing Dockerfile (coming soon)

Builder Priority

Auto-selection order:

1. Flag (--builder)
2. Config ("builder": "nixpacks")
3. Auto-detect (Dockerfile → nixpacks → native)

SSH Configuration

SSH Keys

Auto-generated for provisioned servers:

~/.lightfold/keys/lightfold_ed25519

Or specify custom key:

{
  "provider_config": {
    "digitalocean": {
      "ssh_key": "~/.ssh/my_custom_key"
    }
  }
}

SSH Username

Default username: deploy

Override in config:

{
  "provider_config": {
    "digitalocean": {
      "username": "ubuntu"
    }
  }
}

Config Commands

List Targets

lightfold config list

Set Token

lightfold config set-token digitalocean

Get Token

lightfold config get-token digitalocean

View Status

lightfold status --target myapp

Sync Config

Recover from bad state:

lightfold sync --target myapp

Best Practices

Use descriptive target names

Name targets by environment: myapp-prod, myapp-staging, myapp-dev

Keep secrets in .env files

Never commit .env files to git. Use .gitignore.

Use different servers per environment

Don’t mix production and development on same server.

Backup your config

Config is stored in ~/.lightfold/. Back it up regularly.

Use sync to recover

If state gets corrupted, run lightfold sync to recover.

Config File Locations

File	Path	Purpose
Main Config	~/.lightfold/config.json	Target configuration
API Tokens	~/.lightfold/tokens.json	Provider API tokens
State Files	~/.lightfold/state/<target>.json	Per-target state
SSH Keys	~/.lightfold/keys/	Generated SSH keys

Manual Editing

You can manually edit config files, but use caution:

# Edit config
nano ~/.lightfold/config.json

# Validate by running status
lightfold status --target myapp

Tip: Use lightfold sync after manual edits to ensure consistency.