🚀 Quickstart

Welcome to Ploy—a self-hostable serverless deployment platform that lets you deploy web applications with automatic builds, GitHub integration, and continuous deployment.

TL;DR — Connect your GitHub repository, push your code, and Ploy handles the rest.

0 · Quick Install (Self-Hosted)

Get Ploy running on your server in minutes with our automated install script:

# Simple mode (unified container - good for testing/development)
curl -fsSL https://raw.githubusercontent.com/polarlightsllc/ploy/main/scripts/install.sh | sudo bash -s -- simple

# Production mode (split containers - recommended for production)
curl -fsSL https://raw.githubusercontent.com/polarlightsllc/ploy/main/scripts/install.sh | sudo bash -s -- prod

What the install script does:

1. Detects your Linux distribution (Ubuntu, Debian, Fedora, CentOS, RHEL, Arch, openSUSE)
2. Installs Docker and Docker Compose if not already installed
3. Downloads the appropriate docker-compose configuration
4. Creates a sample .env file for configuration
5. Starts all Ploy services

Installation modes:

• simple: All services run in a single unified container. Best for testing, development, or small deployments.
• prod: Each service runs in its own container. Better resource isolation and recommended for production use.

After installation:

1. Edit /opt/ploy/.env with your configuration (especially GitHub OAuth credentials)
2. Restart services: cd /opt/ploy && docker compose up -d
3. Access the dashboard at http://your-server-ip:3002

For more details, see the Self-Hosting Guide.

1 · Sign in with GitHub

1. Visit the Ploy dashboard at meetploy.com (or your self-hosted instance)
2. Click Sign in with GitHub
3. Authorize Ploy to access your repositories

2 · Create an organization and project

1. After signing in, create a new organization (or use an existing one)
2. Navigate to Projects and click New Project
3. Give your project a name (e.g., "my-app")

3 · Connect a GitHub repository

1. Click Connect Repository in your project
2. Install the Ploy GitHub App if prompted
3. Select the repository you want to deploy
4. Choose the branch to deploy (default: main)

4 · Configure build settings

Ploy automatically detects most frameworks, but you can customize:

Framework Detection

Ploy automatically detects and configures:

• Next.js - Static and server-side rendering
• React - Static site generation with Vite or Create React App
• Vue - Static sites with Vite
• Nuxt - Static and server-side rendering
• Svelte/SvelteKit - Static and server-side rendering
• Astro - Static site generation
• Angular - Static site generation
• Static HTML - Plain HTML, CSS, and JavaScript

Using ploy.yaml (Recommended)

The recommended way to configure your project is by adding a ploy.yaml file to the root of your repository:

# ploy.yaml
kind: static
build: npm run build
out: dist

Basic configuration options:

• kind: Project type (static or nextjs)
• build: Build command (e.g., npm run build)
• out: Output directory for built files (e.g., dist, build, .next)

For advanced configuration options including monorepo and base path support, see the Configuration guide.

Dashboard Configuration

If needed, you can also override settings in the Ploy dashboard:

# Build Command (optional - auto-detected)
npm run build

# Output Directory (optional - auto-detected)
dist

# Install Command (optional)
npm install

Environment Variables

Add environment variables for your build:

1. Go to Project Settings → Environment Variables
2. Add key-value pairs:
   • API_URL=https://api.example.com
   • NEXT_PUBLIC_API_KEY=your-key-here

5 · Deploy

Once your repository is connected:

1. Automatic Deployment: Push to your configured branch
2. Manual Deployment: Click Deploy in the dashboard
3. Monitor Progress: Watch real-time build logs

# Push to trigger deployment
git add .
git commit -m "Initial deployment"
git push origin main

Deployment Process

Ploy will:

1. Clone your repository
2. Install dependencies
3. Run the build command
4. Upload static assets
5. Generate a unique deployment URL

6 · Access your deployment

After a successful deployment:

1. View your app: Click the deployment URL (e.g., https://my-app-abc123.ploy.app)
2. Share with team: Each deployment gets a unique URL
3. Branch deployments: Every branch gets its own URL for testing

Example deployment URLs:

Production (main):    https://my-app.ploy.app
Branch (feature):     https://my-app-feature-xyz.ploy.app
PR Preview:           https://my-app-pr-123.ploy.app

7 · Advanced features

Custom Domains

Connect your own domain:

1. Go to Project Settings → Domains
2. Add your domain (e.g., example.com)
3. Configure DNS records as shown
4. Wait for SSL certificate provisioning

Preview Deployments

Every push to any branch creates a preview deployment:

• Test features before merging to production
• Share previews with team members or clients
• Automatic cleanup when branches are deleted

Build Logs

Access detailed build logs:

1. Click on any deployment
2. View Build Logs tab
3. Debug failed deployments with full output

Rollback

Quickly revert to a previous deployment:

1. Go to Deployments history
2. Click on a previous successful deployment
3. Click Promote to Production

8 · Example Projects

Next.js App

# Create a new Next.js app
npx create-next-app@latest my-nextjs-app
cd my-nextjs-app

# Initialize git and push to GitHub
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/my-nextjs-app.git
git push -u origin main

Then connect the repository in Ploy - it will auto-detect Next.js and deploy!

Vite + React App

# Create a new Vite app
npm create vite@latest my-react-app -- --template react
cd my-react-app

# Initialize git and push to GitHub
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/my-react-app.git
git push -u origin main

Connect in Ploy and deploy automatically!

Static HTML Site

# Create a simple HTML site
mkdir my-static-site
cd my-static-site
echo '<!DOCTYPE html><html><body><h1>Hello Ploy!</h1></body></html>' > index.html

# Initialize git and push to GitHub
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/my-static-site.git
git push -u origin main

Connect in Ploy and deploy!

9 · FAQ

10 · Next steps

• Read the Self-Hosting Guide to deploy Ploy on your infrastructure
• Check out our GitHub repository for source code
• Join our community for help and feature requests

Happy deploying! ✨