Build & Release Scripts

Build and release scripts allow you to customize what happens during your deployment process. Build scripts run during the deployment phase to prepare your application, while release scripts run after deployment to perform post-deployment tasks. Both are optional, but can be extremely useful for production applications.

Build Scripts

Build scripts run during the deployment process and are used to install dependencies, compile assets, and prepare your application for production. This is where you’ll run commands or build your static site.

When to Use Build Scripts

Build scripts are essential for:

• Installing dependencies - Running npm install, or composer install
• Compiling assets - Building frontend assets with tools like Vite, Webpack, or esbuild
• Static site generation - Running static site generators like Hugo, Jekyll, or Gatsby
• Transpiling code - Compiling TypeScript, Sass, or other preprocessors
• Optimizing production builds - Minifying assets or creating production bundles

Setting Up Your Build Script

1. Create a build script file in your repository. We recommend .webslice/build.sh for consistency, but you can place it anywhere in your repository.
2. Make the script executable by running chmod +x .webslice/build.sh before committing it.
3. Configure the script path in your website settings via the Webslice Console under Settings » Build & Deploy.

Available Tools

The build environment includes common tools like node, npm, composer, and git. If you need a specific version or additional tools, you can install them within your build script, or get in touch if you feel we are missing something.

Example Build Scripts

PHP/Laravel Application

#!/bin/bash
set -e

# Install Composer dependencies (production only)
composer install --no-dev --optimize-autoloader

# Install Node dependencies and build assets
npm ci
npm run build

# Cache Laravel configuration/routes/templates
php artisan config:cache
php artisan route:cache
php artisan view:cache

Static Site (Hugo)

#!/bin/bash
set -e

# Install specific Hugo version if needed
# wget https://github.com/gohugoio/hugo/releases/download/v0.120.0/hugo_extended_0.120.0_Linux-64bit.tar.gz
# tar -xzf hugo_extended_0.120.0_Linux-64bit.tar.gz

# Build the static site
hugo --minify --environment production

Script Execution

Always include #!/bin/bash at the top of your script and set -e to ensure the script fails fast if any command errors. This prevents partial deployments with failed builds.

Release Scripts

Release scripts run after your deployment is live and serving traffic. They’re designed for tasks that should happen post-deployment, such as cache warming, database migrations, or notifying external services.

Database Access

Your database is fully accessible during the release script with the same credentials and configuration as your live application. This makes it the perfect place for database migrations.

When to Use Release Scripts

Release scripts are useful for:

• Database migrations - Running schema updates or data migrations safely
• Cache warming - Pre-populating caches to improve performance
• External notifications - Notifying monitoring services about the deployment
• Post-deployment cleanup - Removing temporary files or clearing old caches

Setting Up Your Release Script

1. Create a release script file in your repository. We recommend .webslice/release.sh for consistency
2. Make the script executable with chmod +x .webslice/release.sh before committing it
3. Configure the script path in your website settings via the Webslice Console under Settings » Build & Deploy

Example Release Scripts

Laravel Migrations

#!/bin/bash
set -e

# Run database migrations
php artisan migrate --force

# Clear old caches
php artisan cache:clear

# Warm up the application cache
php artisan cache:warm

Cache Warming

#!/bin/bash
set -e

# Warm critical pages
curl -s https://yoursite.com/ > /dev/null
curl -s https://yoursite.com/about > /dev/null
curl -s https://yoursite.com/products > /dev/null

echo "Cache warming completed"

Webslice Environment Flag

We automatically set the WEBSLICE environment variable to 1 during both build and release scripts. You can use this to conditionally run code specifically for Webslice deployments.

#!/bin/bash
if [ "$WEBSLICE" = "1" ]; then
    echo "Running on Webslice platform"
    # Run Webslice-specific commands
fi

All environment variables you’ve configured in your website settings are also available during both build and release scripts, allowing you to use API keys, configuration values, and other secrets securely.

Viewing Logs

You can view the output from your build and release scripts at any time through the Webslice Console. Navigate to your website and look under the Activity section for:

• Website Deployment - Shows logs from your build script execution
• Website Release Phase - Shows logs from your release script execution

These logs are invaluable for debugging failed deployments, verifying that your scripts ran correctly, or troubleshooting performance issues. Each deployment maintains its own logs, so you can review historical deployments as well.

Debugging Tips

Add set -x to your scripts to enable verbose output showing each command as it executes. This can be helpful when debugging complex build processes. Remove it once everything is working to keep logs clean.

Best Practices

• Keep scripts idempotent: Scripts should be safe to run multiple times without causing issues
• Use version pinning: Lock dependency versions in package-lock.json, composer.lock to ensure consistent builds
• Fail fast: Use set -e to stop immediately on errors rather than continuing with a bad build
• Log important steps: Use echo statements to log progress, making it easier to debug issues from logs
• Test locally: Run your build and release scripts locally before deploying to catch issues early
• Keep them focused: Build scripts should build, release scripts should release. Don’t mix concerns