How Drupal Decoupled Uses Tugboat for Instant Demo Environments

When we launched Drupal Decoupled, we faced a particular challenge: how do you demonstrate the power of a decoupled architecture without forcing people through the complexity of setting it up themselves?

The answer came from an unexpected source: Tugboat, a platform primarily designed for testing environments. 

By repurposing their preview capabilities, we created a one-click demo experience that removes every barrier between curiosity and hands-on experience with modern Drupal development.

Here’s how it works.

Why We Chose Tugboat

Tugboat's strength lies in its ability to create isolated, complete environments rapidly. 

Their platform offers several capabilities that make it perfect for our Drupal Decoupled preview needs:

• Pre-built Snapshots: Tugboat creates base images of complete environments: Drupal with database, web server, and all dependencies already configured. This means users don't start from scratch, but from a fully operational foundation.
• Rapid Deployment: Where traditional setups take minutes or hours, Tugboat spins up isolated instances in seconds. This speed comes from their sophisticated container orchestration that handles complex multi-service stacks automatically.
• API-driven Control: Since we needed programmatic control from our documentation site, Tugboat's API integration allowed us to trigger environment creation directly from our interface.

The connection between testing and demo environments isn't obvious until you examine what both require: isolated instances, quick setup, and disposable environments that clean themselves up.

Tugboat's preview capabilities, originally designed for developers to test pull requests in complete environments, translate directly to demo functionality. 

Both use cases need the same fundamental architecture: spin up a complete stack, use it temporarily, then tear it down.

This realization let us leverage a mature, battle-tested platform instead of building demo infrastructure from scratch.

Technical Implementation

Base Preview Architecture

Our Tugboat implementation runs four coordinated services that mirror a real-world Drupal Decoupled setup:

• Drupal Service: A pre-configured backend with GraphQL Compose enabled, sample content loaded, and all necessary modules installed. It's a fully configured headless CMS ready for API consumption.
• Frontend Service: Next.js and React Router starters configured to connect to the Drupal backend. These aren't static demos but fully functional frontend applications that fetch real data through GraphQL.
• Storybook Service: A complete component library showcasing the design system components used in the frontend implementations.
• Storage Service: The coordination layer that makes everything work together, more on this critical piece below.

The Coordination Challenge

Here's where things get interesting from a technical perspective. 

In a decoupled architecture, the frontend needs to know where the backend lives before it can build. But Tugboat services start independently, and there's no shared file system between containers.

• The Problem: Our frontend service needs the Drupal backend's public URL before it can complete its build process.
• Our Solution: We implemented an intermediate storage service that acts as a communication layer between all services.

How the Magic Works

The coordination happens through a carefully orchestrated sequence:

1. Drupal service starts and completes its installation process with sample content and configuration.
2. Drupal writes its public URL to the shared storage service.
3. Frontend service waits for URL availability in the storage layer.
4. Frontend retrieves the URL and builds against the live Drupal instance.
5. All services become accessible with working connections between them.

This approach ensures that by the time users access the demo, everything is connected and functional: no broken links, no configuration issues, etc.

User Experience: What Users Get in Drupal Decoupled 

In short, when someone clicks 'Try Drupal Decoupled' on our site, they gain immediate access to a complete, working stack: a Drupal backend, a connected frontend, and a component library, all configured with a lifespan of 15-20 minutes.

This approach eliminates every traditional barrier to trying Drupal Decoupled:

• No Local Setup Required: No need to install Docker, configure databases, or manage dependencies.
• No Configuration Headaches: Everything works out of the box, exactly as intended.
• Immediate Access to Complete Stack: Users see the full picture, backend, frontend, and design system working together.

The demo provides the same experience as a local development setup, but without any of the friction that typically stops people from trying new technologies.

Challenges and Solutions

The biggest challenge for this implementation was service coordination:

• Service Coordination: Solved with our storage intermediary that manages URL sharing.
• URL Discovery: Dynamic URL sharing between containers through the storage service ensures the frontend always connects to the correct backend.
• Build Dependencies: Proper sequencing of service startup prevents race conditions and ensures reliable builds.

This solution works because it leverages existing strengths rather than fighting platform limitations, mainly through three main actions:

• Leverages Tugboat's Container Expertise: We don't reinvent container orchestration: we build on top of proven infrastructure.
• Reuses our Proven Configurations: The same Docker configurations we use for client projects power these demos.
• Provides Identical Experience: What users experience in the demo matches what they'd get in local development.

The Power of Repurposing Tools to Innovate

Tugboat wasn't designed for demos, but its architecture fits our needs perfectly. 

This highlights an important principle in technical problem-solving: sometimes the best solution comes from looking at existing tools through a different lens.

Preview environments and demo environments share core requirements: they just serve different audiences. 

By recognizing this overlap, we turned a testing platform into a powerful adoption tool.

Impact on Drupal Decoupled Adoption

This implementation removes the biggest barrier to evaluating headless Drupal: the setup complexity. Instead of reading about decoupled architecture, users can immediately experience it working.

The demo provides hands-on experience with real implementation patterns: GraphQL queries, component composition, and API-driven content management. This practical exposure does more to communicate Drupal's modern capabilities than any amount of documentation.

Want to learn more about the complex installation process of this kind of setups? Learn more in our article on Drupal Decoupled install made easy here.

Leveraging Tugboat Capabilities for Drupal Decoupled

Complex multi-service architectures need coordination mechanisms, especially in containerized environments. 

Our storage intermediary pattern solves a common problem: how do independent services discover and connect to each other dynamically?

This pattern isn't specific to Tugboat or even to demos. Any situation where you need services to coordinate without shared file systems can benefit from a similar approach.

Container orchestration platforms can serve multiple use cases beyond their original design. The key is recognizing when your requirements align with existing platform capabilities, even if the use case seems different on the surface.

Pre-built environments dramatically reduce setup friction for development, testing, and deployment. When you eliminate the gap between "I want to try this" and "I'm actually using this," the adoption perspective changes dramatically.

At Octahedroid, we'll continue evolving this approach as we add new frontend frameworks and extend Drupal Decoupled's capabilities.

The foundation we've built with Tugboat proves that sometimes the best innovation comes from using existing tools in new ways.

If you want to learn more about why we made this project, read our article on Drupal Decoupled here.

And try Drupal Decoupled yourself here and experience firsthand how modern Drupal development works when the friction disappears.