Skip to main content

​
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 installs all dependencies and configures the server. Subsequent deployments are much faster due to idempotency.
Use --force to rerun steps:
lightfold configure --target myapp --force
Check application logs:
lightfold logs --target myapp --tail
View detailed status:
lightfold status --target myapp
Access server directly:
lightfold ssh --target myapp