Deployments

Deployments are at the heart of Parslinks. This guide covers everything you need to know about deploying, managing, and monitoring your applications.

What is a Deployment?

A deployment is the process of building your application and making it available on the internet. Each deployment:

• Builds your code: Installs dependencies and runs build commands
• Creates a snapshot: Immutable version of your application
• Gets a unique URL: Access this specific version
• Can be promoted: Make it the production deployment
• Includes logs: Complete build and runtime logs

Deployment Types

Production Deployments

Production deployments are your live, customer-facing versions:

• Triggered by: Pushing to production branch (usually main)
• URL: Your primary domain (e.g., yourapp.com)
• Automatic: Deploys automatically when enabled
• Promoted: Or manually promoted from preview deployments

Preview Deployments

Preview deployments let you test changes before production:

• Triggered by: Pull requests or non-production branches
• URL: Unique preview URL (e.g., project-git-feature.parslinks.app)
• Temporary: Can be deleted after testing
• Shareable: Share with team for review

Manual Deployments

Trigger deployments manually:

• From Dashboard: Click "Deploy" button
• From CLI: Use Parslinks CLI
• From API: Trigger via API call
• Redeploy: Deploy existing commit again

Creating a Deployment

Method 1: Git Push (Automatic)

With Git integration enabled:

# Make changes to your code
git add .
git commit -m "Add new feature"
git push origin main

# Deployment automatically triggers!

Method 2: Dashboard Deploy

1. Navigate to your project
2. Click Deploy button
3. Select branch/commit (optional)
4. Click Deploy Now
5. Monitor build progress

Method 3: CLI Deploy

# Install Parslinks CLI
npm install -g parslinks-cli

# Login
parslinks login

# Deploy current directory
parslinks deploy

# Deploy specific directory
parslinks deploy --cwd ./my-app

# Deploy to specific project
parslinks deploy --project my-project

Method 4: API Deploy

curl -X POST https://api.parslinks.com/v1/deployments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_123",
    "branch": "main"
  }'

Deployment Configuration

Build Settings

Configure how your project builds:

# Framework Detection
Framework: Next.js (auto-detected)

# Build Configuration
Build Command: npm run build
Output Directory: .next
Install Command: npm install

Advanced Build Settings

# Node.js Version
Node Version: 18.x

# Package Manager
Package Manager: npm # or yarn, pnpm, bun

# Root Directory (for monorepos)
Root Directory: apps/web

# Environment Variables
Environment: Production

# Build Cache
Enable Build Cache: Yes

Framework Presets

Parslinks automatically detects and configures common frameworks:

Deployment Process

Build Phases

Every deployment goes through these phases:

1. Queued (⏳)

Deployment queued and waiting for build slot

2. Initializing (🔄)

Setting up build environment
Installing system dependencies

3. Cloning Repository (📦)

Cloning repository from Git
Checking out specific commit/branch

4. Installing Dependencies (📚)

Running: npm install
Installing node_modules

5. Building (🔨)

Running: npm run build
Compiling application

6. Deploying (🚀)

Uploading build artifacts
Configuring routing

7. Ready (✅)

Deployment successful!
URL: https://your-app.parslinks.app

Monitoring Build Progress

Watch your deployment in real-time:

1. Click on the deployment in your project
2. View live build logs
3. See current phase and progress
4. Check for errors or warnings

Build Logs

Build logs show everything that happens during deployment:

[13:45:23] Starting build...
[13:45:24] Cloning repository
[13:45:25] Installing dependencies
[13:45:26] npm install
[13:45:45] Running build
[13:45:46] npm run build
[13:46:12] Build successful
[13:46:13] Deploying to CDN
[13:46:15] Deployment complete!

Deployment URLs

Production URL

Your primary production URL:

https://yourproject.parslinks.app

Or with custom domain:

https://yourapp.com

Preview URLs

Preview deployments get unique URLs:

# Pull request preview
https://project-git-pr-123.parslinks.app

# Branch preview
https://project-git-feature-auth.parslinks.app

# Specific deployment
https://project-deployment-abc123.parslinks.app

Deployment Permalinks

Each deployment gets a permanent URL:

https://project-v1-abc123.parslinks.app

This URL never changes and always shows this specific deployment.

Managing Deployments

Promoting a Deployment

Make a preview deployment your production deployment:

1. Go to Deployments tab
2. Find the deployment you want to promote
3. Click ⋮ → Promote to Production
4. Confirm promotion
5. This deployment becomes live

Rolling Back

Revert to a previous deployment:

1. Go to Deployments tab
2. Find the previous working deployment
3. Click ⋮ → Promote to Production
4. Your site instantly reverts

Canceling a Deployment

Stop a build in progress:

1. Go to active deployment
2. Click Cancel Build
3. Build stops immediately
4. Deployment marked as cancelled

Redeploying

Deploy the same commit again:

1. Find the deployment
2. Click ⋮ → Redeploy
3. New deployment starts with same configuration

Use cases:

• Environment variables changed
• Build failed due to temporary issue
• Want to apply new build settings

Deleting Deployments

Remove old preview deployments:

1. Go to Deployments tab
2. Find the deployment
3. Click ⋮ → Delete
4. Confirm deletion

Note: Production deployment cannot be deleted.

Deployment Environments

Environment Variables by Deployment

Different environments can have different variables:

Production Environment:
  DATABASE_URL=postgresql://prod-db
  API_URL=https://api.production.com

Preview Environment:
  DATABASE_URL=postgresql://staging-db
  API_URL=https://api.staging.com

Development Environment:
  DATABASE_URL=postgresql://localhost
  API_URL=http://localhost:8000

Branch-Specific Configurations

Configure different settings per branch:

# main branch (production)
Build Command: npm run build
Environment: Production

# staging branch
Build Command: npm run build:staging
Environment: Staging

# feature branches (previews)
Build Command: npm run build:preview
Environment: Preview

Deployment Hooks

Git Hooks

Trigger deployments on Git events:

• Push to Branch: Auto-deploy on push
• Pull Request: Create preview deployment
• Tag Created: Deploy tagged releases
• Pull Request Merged: Deploy to production

Webhook Notifications

Get notified about deployment events:

{
  "event": "deployment.created",
  "deployment": {
    "id": "dep_123",
    "status": "building",
    "url": "https://app.parslinks.app",
    "commit": "abc123"
  }
}

Configure webhooks to:

• Slack
• Discord
• Custom endpoints
• CI/CD tools

Deploy Hooks

Run scripts at different stages:

{
  "hooks": {
    "beforeBuild": "npm run prebuild",
    "afterBuild": "npm run postbuild",
    "beforeDeploy": "npm run predeploy",
    "afterDeploy": "npm run postdeploy"
  }
}

Deployment Settings

Auto Deploy

Enable automatic deployments:

1. Go to Project Settings → Git
2. Enable Auto Deploy
3. Select production branch
4. Deployments trigger on every push

Preview Deployments

Configure preview deployments:

Enable Preview Deployments: Yes

Preview Branch Pattern: *  # All branches
# Or specific pattern: feature/*

Pull Request Previews: Enabled
Deploy on PR Comment: Enabled

Build Concurrency

Control simultaneous builds:

• Free Plan: 1 concurrent build
• Pro Plan: 3 concurrent builds
• Team Plan: 10 concurrent builds
• Enterprise: Unlimited

If limit reached, builds queue automatically.

Deployment Analytics

Build Metrics

Track deployment performance:

• Build Duration: Average and individual build times
• Success Rate: Percentage of successful deployments
• Failure Reasons: Common build errors
• Queue Time: Time waiting for build slot

Performance Metrics

Monitor deployed applications:

• Response Time: Server response times
• Error Rate: Failed requests
• Traffic: Requests per second
• Uptime: Service availability

Troubleshooting Deployments

Common Build Failures

Dependencies Installation Failed

Error: Cannot find module 'some-package'

Solution:

• Check package.json includes the dependency
• Verify version compatibility
• Clear cache and redeploy

Build Command Failed

Error: Build script failed with exit code 1

Solution:

• Check build logs for specific error
• Verify build command is correct
• Check environment variables are set
• Test build locally first

Out of Memory

Error: JavaScript heap out of memory

Solution:

• Upgrade to plan with more build resources
• Optimize build process
• Use incremental builds
• Reduce bundle size

Wrong Node Version

Error: Unsupported Node.js version

Solution:

• Set correct Node version in project settings
• Use .nvmrc or package.json "engines" field

Debugging Failed Deployments

1. Check Build Logs:

   • Look for error messages
   • Identify failing command
   • Note error line numbers

2. Verify Configuration:

   • Build command correct?
   • Output directory right?
   • Environment variables set?

3. Test Locally:

   # Run same commands locally
   npm install
   npm run build

4. Check Environment:

   • Node version matches?
   • Dependencies compatible?
   • Environment variables available?

Getting Help

If you're stuck:

1. Check Logs: Build logs often show the exact issue
2. Search Documentation: Check troubleshooting guide
3. Contact Support: Share deployment ID and logs
4. Community Forum: Ask the community

Best Practices

1. Use Git Integration

✅ Do: Connect your Git repository

Automatic deployments
Full deployment history
Easy rollbacks

❌ Don't: Manually upload files

No version control
No rollback capability
Manual process

2. Test Before Production

1. Create feature branch
2. Push to create preview deployment
3. Test preview URL
4. Merge to production branch

3. Use Environment Variables

✅ Store secrets in environment variables
❌ Don't commit secrets to Git

4. Monitor Deployments

• Enable deployment notifications
• Check build times regularly
• Review failed deployments
• Monitor production errors

5. Implement CI/CD

# Example GitHub Actions workflow
name: Deploy
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm test
  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: parslinks/deploy-action@v1

Deployment Limits

Limits vary by plan:

Next Steps