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

# Deployment Guide

> Understand how Lightfold deploys your applications

## Deployment Flow

Lightfold uses a composable, idempotent deployment architecture where each step is independent and can be run standalone or orchestrated together.

### Orchestrated Deployment

The `lightfold deploy` command chains all steps automatically:

```bash theme={null}
lightfold deploy
```

**What happens:**

<Steps>
  <Step title="Framework Detection">
    Analyzes project structure to identify framework and package manager.

    Supports 15+ frameworks including Next.js, Django, Rails, Laravel, and more.
  </Step>

  <Step title="Infrastructure Creation">
    Creates server infrastructure if not already created.

    * **Auto-provision mode**: Creates VM on cloud provider (DigitalOcean, Vultr, Hetzner)
    * **BYOS mode**: Validates SSH access to existing server

    Marks target as "created" in local state.
  </Step>

  <Step title="Server Configuration">
    Configures server if not already configured.

    * Installs runtime dependencies
    * Sets up systemd services
    * Configures nginx reverse proxy
    * Creates deployment directory structure

    Writes `/etc/lightfold/configured` marker on server.
  </Step>

  <Step title="Code Deployment">
    Deploys code changes using blue/green deployment.

    * Checks git commit vs. last deployed commit
    * Creates timestamped release: `/srv/<app>/releases/<timestamp>/`
    * Uploads tarball and builds project
    * Swaps symlink `/srv/<app>/current` with health checks
    * Auto-rollback on failure
  </Step>
</Steps>

### Manual Steps

You can run each step independently for granular control:

```bash theme={null}
# Step 1: Create infrastructure
lightfold create --target myapp

# Step 2: Configure server
lightfold configure --target myapp

# Step 3: Deploy code
lightfold push --target myapp
```

## Idempotency

Lightfold is designed to be safe to rerun. Each step checks state before executing.

### State Tracking

**Local State** (`~/.lightfold/state/<target>.json`):

```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"
}
```

**Remote Markers** (on server):

* `/etc/lightfold/created` - Written by create command
* `/etc/lightfold/configured` - Written by configure command

### Smart Skipping

Commands automatically skip completed steps:

* `create` - Skips if already created
* `configure` - Skips if `/etc/lightfold/configured` exists
* `push` - Skips if git commit unchanged
* `deploy` - Skips all completed steps

Use `--force` to override and rerun steps.

## Builder System

Lightfold supports multiple build strategies:

### Native Builder

Traditional approach using framework detection + nginx.

* Uses framework-specific build commands
* Serves static files with nginx
* Runs app with systemd service

### Nixpacks Builder

Railway's Nixpacks for auto-detected builds.

* Auto-detects runtime and dependencies
* Generates optimized Docker container
* No Dockerfile required

### Dockerfile Builder

Uses your existing Dockerfile (coming soon).

### Auto-Selection

Lightfold automatically selects the best builder:

1. If Dockerfile exists → `dockerfile`
2. If Node/Python + nixpacks available → `nixpacks`
3. Otherwise → `native`

Override with `--builder` flag:

```bash theme={null}
lightfold deploy --builder nixpacks
```

## Blue/Green Deployment

Lightfold uses blue/green deployment for zero-downtime releases:

<Steps>
  <Step title="Create new release">
    Creates timestamped directory: `/srv/<app>/releases/20251003103000/`
  </Step>

  <Step title="Build application">
    Uploads code, installs dependencies, runs build commands.
  </Step>

  <Step title="Health check">
    Starts new release and runs health checks.
  </Step>

  <Step title="Swap symlink">
    Atomically updates `/srv/<app>/current` symlink to new release.
  </Step>

  <Step title="Cleanup">
    Keeps last 5 releases, removes older ones.
  </Step>
</Steps>

**On failure:** Automatically rolls back to previous release.

## Rollback

Instant rollback to previous release:

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

Swaps symlink back to previous release directory.

## Custom Domains & SSL

Add custom domain with automatic Let's Encrypt SSL:

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

**What happens:**

1. Prompts for SSL enable (default: yes)
2. Installs certbot if needed
3. Issues Let's Encrypt certificate
4. Configures nginx with domain + HTTPS
5. Sets up auto-renewal
6. Updates target config

Remove domain:

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

## State Recovery

If local state gets corrupted or server IP changes, use sync:

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

**Sync operations:**

* Recovers server IP from provider API
* Verifies SSH connectivity
* Syncs remote markers (`created`, `configured`)
* Updates deployment info (current release, git commit)
* Checks service status

## Environment Variables

Set environment variables in config:

```json theme={null}
{
  "targets": {
    "myapp": {
      "deploy": {
        "env_vars": {
          "NODE_ENV": "production",
          "DATABASE_URL": "postgres://..."
        }
      }
    }
  }
}
```

Or use `.env` file in project root (automatically loaded).

## Multi-Target Deployments

Deploy the same project to multiple environments:

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

# Staging
lightfold deploy --target myapp-staging

# Development
lightfold deploy --target myapp-dev
```

Each target has independent configuration and state.

## Deployment Tips

<AccordionGroup>
  <Accordion title="First deployment is slow">
    First deployment installs all dependencies and configures the server. Subsequent deployments are much faster due to idempotency.
  </Accordion>

  <Accordion title="Force reconfiguration">
    Use `--force` to rerun steps:

    ```bash theme={null}
    lightfold configure --target myapp --force
    ```
  </Accordion>

  <Accordion title="View deployment logs">
    Check application logs:

    ```bash theme={null}
    lightfold logs --target myapp --tail
    ```
  </Accordion>

  <Accordion title="Check server status">
    View detailed status:

    ```bash theme={null}
    lightfold status --target myapp
    ```
  </Accordion>

  <Accordion title="SSH into server">
    Access server directly:

    ```bash theme={null}
    lightfold ssh --target myapp
    ```
  </Accordion>
</AccordionGroup>