Skip to main content
Get preview-deployer up and running in minutes.

​
Prerequisites

Before you begin, ensure you have:
  1. Digital Ocean Account: Sign up at digitalocean.com
  2. GitHub Account: With access to repositories you want to enable
  3. Node.js: Version 20 or higher (download)
  4. pnpm: Package manager (install)
  5. Terraform: Version 1.5 or higher (install)
  6. Ansible: Version 2.14 or higher (install)
  7. SSH Key: For accessing the Digital Ocean droplet

​
Step 1: Install preview-deployer

Clone the repository and install dependencies: 
git clone https://github.com/danLeBrown/preview-deployer.git
cd preview-deployer
pnpm install
pnpm build

​
Step 2: Get Required Tokens

​
Digital Ocean API Token

  1. Go to Digital Ocean API Tokens
  2. Click “Generate New Token”
  3. Give it a name (e.g., “preview-deployer”)
  4. Select “Write” scope
  5. Copy the token (you won’t see it again!)

​
GitHub Personal Access Token

  1. Go to GitHub Settings > Developer settings > Personal access tokens
  2. Click “Generate new token (classic)”
  3. Give it a name (e.g., “preview-deployer”)
  4. Select scopes:
    • repo (Full control of private repositories)
    • admin:repo_hook (Full control of repository hooks)
  5. Generate and copy the token

​
Step 3: Initialize Configuration

Run the init command: 
pnpm --filter cli run build
preview init
You’ll be prompted for:
  • Digital Ocean API token
  • Digital Ocean region (default: nyc3)
  • Droplet size (default: s-2vcpu-4gb)
  • GitHub personal access token
  • GitHub repositories (comma-separated, format: owner/repo)
  • Cleanup TTL in days (default: 7)
  • Max concurrent previews (default: 10)
Configuration is saved to ~/.preview-deployer/config.yml. Sensitive values are stored in your OS keychain.

​
Step 4: Prepare Your Repository

Add a preview-config.yml file to your repository root: 
framework: nestjs # or go, laravel, rust, python
database: postgres
health_check_path: /health
app_port: 3000
app_port_env: PORT
app_entrypoint: dist/main.js  # NestJS example; value is framework-dependent
See Configuration Reference for all options. The app_entrypoint value depends on your framework (e.g. Go: server, Python: app.main:app). Ensure your application has a health check endpoint at the specified path.

​
Step 5: Set Up Infrastructure

Run the setup command: 
preview setup
This will:
  1. Provision a Digital Ocean droplet
  2. Configure the server with Docker, nginx, and the orchestrator
  3. Create GitHub webhooks for your repositories
You’ll be prompted for:
  • SSH public key (for droplet access)
  • Confirmation to create infrastructure
The setup process takes about 5–10 minutes.

​
Step 6: Test It Out

  1. Create a new branch in your repository
  2. Make some changes
  3. Open a pull request
  4. Wait 2–3 minutes for the preview to deploy
  5. Check the PR comments for the preview URL
The preview URL will be in the format: http://YOUR_SERVER_IP/{projectSlug}/pr-{PR_NUMBER}/ (e.g. http://YOUR_SERVER_IP/myorg-myapp/pr-12/).

​
Step 7: Verify Deployment

Check the status: 
preview status
This shows:
  • Infrastructure status
  • Orchestrator health
  • Active preview deployments

​
Updating the orchestrator

If you change orchestrator code in the preview-deployer repo (e.g. after pulling changes or editing the TypeScript), run: 
preview sync
This builds the orchestrator locally, rsyncs it to the server, and restarts the orchestrator service. Use it after initial setup whenever you want to deploy orchestrator changes without re-running preview setup.

​
Troubleshooting

If something goes wrong:
  1. Check the orchestrator logs: 
    ssh root@YOUR_SERVER_IP
journalctl -u preview-deployer-orchestrator -f
  2. Check Docker containers: 
    ssh root@YOUR_SERVER_IP
docker ps -a
docker logs {projectSlug}-pr-123-app  # Replace with your project slug and PR number
  3. Check nginx configuration: 
    ssh root@YOUR_SERVER_IP
nginx -t
cat /etc/nginx/preview-configs/{projectSlug}-pr-123.conf
See Troubleshooting Guide for more help.

​
Next Steps

​
Cost Estimation

Default setup costs approximately:
  • Digital Ocean droplet (s-2vcpu-4gb): ~$24/month
  • Reserved IP: Free
  • Firewall: Free
  • Monitoring: Free
Total: ~$24/month You can reduce costs by:
  • Using a smaller droplet (s-1vcpu-2gb: ~$12/month)
  • Using a cheaper region
  • Disabling backups

​
Cleanup

To destroy all infrastructure: 
preview destroy
This will:
  1. Cleanup all preview deployments
  2. Delete GitHub webhooks
  3. Destroy the Digital Ocean droplet
This is irreversible!