Skip to main content
Get Prvue 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 Prvue

Clone the repository and install dependencies:

​
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:
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:
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:
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:
This shows:
  • Infrastructure status
  • Orchestrator health
  • Active preview deployments

​
Updating the orchestrator

If you change orchestrator code in the prvue repo (e.g. after pulling changes or editing the TypeScript), run:
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:
  2. Check Docker containers:
  3. Check nginx configuration:
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:
This will:
  1. Cleanup all preview deployments
  2. Delete GitHub webhooks
  3. Destroy the Digital Ocean droplet
This is irreversible!