Shipyard

intermediate

Ephemeral environment platform for pull request previews.

Overview

Shipyard is a modern ephemeral environment platform designed to automatically create temporary preview environments for every pull request in your development workflow. Originally built to solve the challenge of reviewing changes in context, Shipyard integrates with GitHub and GitLab to spin up isolated environments that mirror your production setup, making code review more thorough and collaboration more effective. The platform automatically provisions Docker containers based on your application configuration, creates unique URLs for each environment, and manages the complete lifecycle from creation to cleanup. This Docker stack deploys Shipyard as a self-hosted service that monitors your repositories for pull request events and dynamically creates preview environments using Docker containers. By mounting the Docker socket, Shipyard gains the ability to orchestrate containers on the host system, while GitHub token integration enables automatic PR status updates and comment posting with preview URLs. The setup creates a powerful CI/CD enhancement that bridges the gap between code changes and visual validation. Development teams working with web applications, API services, and full-stack projects will find this configuration particularly valuable for improving code review processes and reducing deployment surprises. Startups and growing engineering teams can eliminate the friction of manual environment setup, while larger organizations can standardize their preview workflow across multiple repositories and maintain better quality control before production deployments.

Key Features

Automatic pull request environment provisioning with unique subdomain URLs
GitHub and GitLab webhook integration for real-time PR event processing
Docker socket mounting for direct container orchestration on host system
Configurable environment templates via .shipyard/docker-compose.yml in repositories
Auto-cleanup of environments when pull requests are merged or closed
Team sharing capabilities with persistent environment URLs during PR lifecycle
PR comment automation with direct links to preview environments
Multi-repository support with centralized environment management dashboard

Common Use Cases

1Frontend teams needing visual confirmation of UI changes before merging PRs
2Full-stack development workflows requiring database and API testing in isolated environments
3Client agencies showcasing work-in-progress features to stakeholders during development
4QA teams performing comprehensive testing without interfering with main staging environments
5Remote development teams collaborating on features with shared preview links
6Microservices architecture validation with interconnected service previews
7Documentation sites and static generators requiring content preview before publication

Prerequisites

GitHub or GitLab personal access token with repository and webhook permissions
Docker host with at least 2GB RAM and 10GB disk space for environment provisioning
Network access to GitHub/GitLab APIs and webhook delivery endpoints
Port 8080 available for Shipyard dashboard and API access
Understanding of Docker Compose syntax for repository environment configuration
Domain or subdomain configuration if using custom URLs for preview environments

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  shipyard: 
3    image: shipyard/shipyard:latest
4    container_name: shipyard
5    restart: unless-stopped
6    ports: 
7      - "8080:8080"
8    environment: 
9      GITHUB_TOKEN: ${GITHUB_TOKEN}
10      DOCKER_HOST: unix:///var/run/docker.sock
11    volumes: 
12      - /var/run/docker.sock:/var/run/docker.sock
13      - shipyard_data:/data
14
15volumes: 
16  shipyard_data:

.env Template

.env

1GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Usage Notes

1Docs: https://shipyard.build/docs/
2Create ephemeral preview environments for each pull request
3Configure via .shipyard/docker-compose.yml in repo
4GitHub/GitLab integration for automatic PR comments with preview URLs
5Auto-cleanup when PR is merged or closed
6Share environments with team for review and testing

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  shipyard:
5    image: shipyard/shipyard:latest
6    container_name: shipyard
7    restart: unless-stopped
8    ports:
9      - "8080:8080"
10    environment:
11      GITHUB_TOKEN: ${GITHUB_TOKEN}
12      DOCKER_HOST: unix:///var/run/docker.sock
13    volumes:
14      - /var/run/docker.sock:/var/run/docker.sock
15      - shipyard_data:/data
16
17volumes:
18  shipyard_data:
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23GITHUB_TOKEN=ghp_xxxxxxxxxxxx
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/shipyard/run | bash

Troubleshooting

Permission denied accessing Docker socket: Ensure the container user has access to /var/run/docker.sock or add user to docker group
GitHub webhook delivery failures: Verify GITHUB_TOKEN has admin:repo_hook permissions and repository webhook settings
Environments not cleaning up after PR merge: Check GitHub token permissions for repository events and webhook configuration
Port conflicts during environment creation: Configure port ranges in Shipyard settings or modify .shipyard/docker-compose.yml templates
Out of disk space errors: Implement Docker image cleanup policies and monitor shipyard_data volume usage
Preview URLs not accessible: Verify firewall rules allow inbound connections on dynamically allocated ports

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

shipyard

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download