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:

lightfold deploy

What happens:

1. Framework Detection

   Analyzes project structure to identify framework and package manager.

   Supports 15+ frameworks including Next.js, Django, Rails, Laravel, and more.

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

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

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

Manual Steps

You can run each step independently for granular control:

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

{
  "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:

lightfold deploy --builder nixpacks

Blue/Green Deployment

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

1. Create new release

   Creates timestamped directory: /srv/<app>/releases/20251003103000/

2. Build application

   Uploads code, installs dependencies, runs build commands.

3. Health check

   Starts new release and runs health checks.

4. Swap symlink

   Atomically updates /srv/<app>/current symlink to new release.

5. Cleanup

   Keeps last 5 releases, removes older ones.

On failure: Automatically rolls back to previous release.

Rollback

Instant rollback to previous release:

lightfold rollback --target myapp

Swaps symlink back to previous release directory.

Custom Domains & SSL

Add custom domain with automatic Let’s Encrypt SSL:

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:

lightfold domain remove --target myapp

State Recovery

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

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:

{
  "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:

# 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

First deployment is slow

First deployment installs all dependencies and configures the server. Subsequent deployments are much faster due to idempotency.

Force reconfiguration

Use --force to rerun steps:

lightfold configure --target myapp --force

View deployment logs

Check application logs:

lightfold logs --target myapp --tail

Check server status

View detailed status:

lightfold status --target myapp

SSH into server

Access server directly:

lightfold ssh --target myapp