> ## Documentation Index
> Fetch the complete documentation index at: https://lightfold.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure Lightfold deployments and targets

## Configuration Files

Lightfold uses three configuration files:

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

Target-based configuration storing deployment settings.

```json theme={null}
{
  "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).

```json theme={null}
{
  "digitalocean": "dop_v1_...",
  "vultr": "...",
  "hetzner": "..."
}
```

**Manage tokens:**

```bash theme={null}
# 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.

```json theme={null}
{
  "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:

```bash theme={null}
lightfold deploy --target myapp
```

Or create explicitly:

```bash theme={null}
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:

```bash theme={null}
# Production
lightfold deploy --target myapp-prod

# Staging
lightfold deploy --target myapp-staging
```

Each target has independent configuration and state.

## Provider Configuration

### DigitalOcean

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

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

## Domain Configuration

### Add Domain

```bash theme={null}
lightfold domain add --domain example.com --target myapp
```

**Configuration:**

```json theme={null}
{
  "domain_config": {
    "domain": "example.com",
    "ssl_enabled": true,
    "ssl_manager": "certbot",
    "proxy_type": "nginx"
  }
}
```

### Remove Domain

```bash theme={null}
lightfold domain remove --target myapp
```

Reverts to IP-based access.

## Deployment Configuration

### Environment Variables

Set environment variables in config:

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

Or use `.env` file in project root:

```bash theme={null}
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:

```json theme={null}
{
  "deploy": {
    "build_command": "npm run custom-build",
    "run_command": "npm run start:prod"
  }
}
```

### Skip Build

Skip build step (for pre-built apps):

```json theme={null}
{
  "deploy": {
    "skip_build": true
  }
}
```

### Custom Health Checks

Define custom health check endpoint:

```json theme={null}
{
  "deploy": {
    "health_check": {
      "path": "/api/health",
      "expect": 200,
      "timeout_seconds": 30
    }
  }
}
```

## Builder Configuration

### Force Builder

Specify builder in config:

```json theme={null}
{
  "builder": "nixpacks"
}
```

Or use flag:

```bash theme={null}
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:

```bash theme={null}
~/.lightfold/keys/lightfold_ed25519
```

Or specify custom key:

```json theme={null}
{
  "provider_config": {
    "digitalocean": {
      "ssh_key": "~/.ssh/my_custom_key"
    }
  }
}
```

### SSH Username

Default username: `deploy`

Override in config:

```json theme={null}
{
  "provider_config": {
    "digitalocean": {
      "username": "ubuntu"
    }
  }
}
```

## Config Commands

### List Targets

```bash theme={null}
lightfold config list
```

### Set Token

```bash theme={null}
lightfold config set-token digitalocean
```

### Get Token

```bash theme={null}
lightfold config get-token digitalocean
```

### View Status

```bash theme={null}
lightfold status --target myapp
```

### Sync Config

Recover from bad state:

```bash theme={null}
lightfold sync --target myapp
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive target names" icon="tag">
    Name targets by environment: `myapp-prod`, `myapp-staging`, `myapp-dev`
  </Accordion>

  <Accordion title="Keep secrets in .env files" icon="key">
    Never commit `.env` files to git. Use `.gitignore`.
  </Accordion>

  <Accordion title="Use different servers per environment" icon="server">
    Don't mix production and development on same server.
  </Accordion>

  <Accordion title="Backup your config" icon="floppy-disk">
    Config is stored in `~/.lightfold/`. Back it up regularly.
  </Accordion>

  <Accordion title="Use sync to recover" icon="rotate">
    If state gets corrupted, run `lightfold sync` to recover.
  </Accordion>
</AccordionGroup>

## 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:

```bash theme={null}
# Edit config
nano ~/.lightfold/config.json

# Validate by running status
lightfold status --target myapp
```

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