Skip to content

Deployment Guide

This guide is for Enterprise and Partner tier customers

Self-hosted deployment requires an active Enterprise or Partner subscription. Contact your LightPane account manager to receive the deployment package.

Prerequisites

Before starting, ensure you have:

  • [ ] An AWS account dedicated to LightPane (not shared with other workloads)
  • [ ] AWS CLI configured with administrator access to the account
  • [ ] A domain name and Route 53 hosted zone (or equivalent DNS)
  • [ ] The LightPane deployment package (provided by your account manager)

Deployment package contents

lightpane-deploy-v1.x.x/
├── cloudformation/
│   └── lightpane-stack.yaml        # Full infrastructure template
├── lambda/
│   ├── discovery.zip               # Service discovery function
│   ├── key-management.zip          # Key management function
│   └── auth.zip                    # Authentication functions
├── layers/
│   ├── gcp-sdk.zip                 # Google Cloud SDK layer
│   ├── service-definitions.zip     # Service definition files
│   └── dependencies.zip            # Python dependencies
├── scripts/
│   ├── deploy.sh                   # Initial deployment script
│   ├── update.sh                   # Update script for new versions
│   └── create-admin.sh             # Create initial admin user
├── config/
│   └── parameters.example.json     # CloudFormation parameter template
└── README.txt                      # Version-specific instructions

Step 1: Configure parameters

Copy the parameter template and fill in your values:

cp config/parameters.example.json config/parameters.json

{
    "DomainName": "lightpane.acmecorp.com",
    "HostedZoneId": "Z1234567890ABC",
    "Environment": "production",
    "Region": "eu-west-2"
}

Step 2: Deploy the CloudFormation stack

./scripts/deploy.sh --config config/parameters.json

The script:

  1. Uploads Lambda packages and layers to S3
  2. Creates the CloudFormation stack
  3. Waits for stack creation to complete
  4. Outputs the API endpoint URL and CloudFront distribution domain

Deployment takes approximately 15-20 minutes

CloudFront distribution creation is the longest step. The script waits for all resources to reach a stable state before completing.

Step 3: Configure DNS

Point your domain at the CloudFront distribution. The deploy script outputs the distribution domain name:

# Example output from deploy.sh:
# CloudFront Distribution: d1234567890abc.cloudfront.net
# Create a CNAME record: lightpane.acmecorp.com -> d1234567890abc.cloudfront.net

Create the DNS record in your hosted zone or DNS provider.

Step 4: Create the initial admin user

./scripts/create-admin.sh \
  --email admin@acmecorp.com \
  --name "Admin User"

This generates a temporary password and creates the first user account. Change the password on first login.

Step 5: Verify the deployment

# Check the API is responding
curl https://lightpane.acmecorp.com/health

# Log in to the application
# Open https://lightpane.acmecorp.com in a browser

Updating to a new version

When LightPane provides an updated deployment package:

./scripts/update.sh --config config/parameters.json --package lightpane-deploy-v1.x.y/

The update script:

  1. Uploads new Lambda code and layers
  2. Updates the CloudFormation stack (if template changes are needed)
  3. Verifies the deployment health
  4. Rolls back automatically if health checks fail

Test updates in a staging environment first

Deploy the update to a separate staging account before applying to production. The deployment package works identically across accounts.

Linking cloud accounts

After deployment, link your cloud accounts through the LightPane application:

  1. Log in to your self-hosted LightPane instance
  2. Go to Cloud Accounts
  3. Follow the same setup process as the managed service:
    • AWS: deploy the CloudFormation role template
    • GCP: run the Cloud Shell setup script
    • Azure: create the Service Principal

The cross-account roles trust your self-hosted Lambda's execution role, not the LightPane managed account. The setup instructions in your instance are pre-configured with the correct account ID.

Troubleshooting

Symptom Likely cause Resolution
502 Bad Gateway Lambda function error Check CloudWatch Logs for the discovery Lambda
403 Forbidden CORS or WAF blocking Check WAF rules and CloudFront configuration
Discovery returns empty Cross-account role not configured Verify the IAM role trust policy references your Lambda's execution role
GCP discovery fails Missing GCP SDK layer Verify the layer is attached to the discovery Lambda