Demos
A demo is the live, hosted version of a play running on Playbooks infrastructure. It lets users evaluate software in a working state instead of relying on screenshots or the code explorer alone.
How It Works
- When you submit a play, Playbooks will attempt to generate a working configuration.
- As an alternative, you can define your own configuration using
playbooks.json. - The project is then booted inside an isolated sandbox on our infrastructure.
- If the demo deploys successfully, the play can be published and served to visitors.
- If the demo fails, it must be fixed before the play can remain available.
Configuration
Demos are primarily configured during the submission process, where you can manage each part of the setup through the user interface. The following sections outline the primary parts of that configuration.
Strategies
Strategy | Description |
|---|---|
| Basic | Provide the base image, port, and server commands so Playbooks can build the setup. |
| Dockerfile | Supply your own Dockerfile when you want full control over the container. |
| Compose | Use Docker Compose when your demo depends on multiple services working together. |
| Partial | Build from an existing template and define where the runtime code should live. |
Environment Variables
Environment variables are useful when your demo needs secrets or runtime configuration that should not be bundled with the distributed source code. They are injected at runtime and can be managed without changing the underlying repository.
Key | Value |
|---|---|
PORT | •••••••••••••••••••••••••••••••• |
NODE_ENV | •••••••••••••••••••••••••••••••• |
DATABASE_URL | •••••••••••••••••••••••••••••••• |
Private Files
Private files solve a similar problem when your demo depends on runtime-only files such as configuration files, certificates, or package credentials. Like environment variables, they are mounted at runtime and excluded from the code users receive when they download a play.
Path | Value |
|---|---|
/.env | •••••••••••••••••••••••••••••••• |
/.npmrc | •••••••••••••••••••••••••••••••• |
Optimizations
A few small decisions can make a big difference in demo performance and boot speed.
- Use smaller base images when possible so builds and startups stay faster.
- Build for production rather than development so the resulting output is leaner and closer to what users should evaluate.
- Move as much work as possible into the build process instead of doing it at runtime.
- Keep the run command focused on basic serve behavior so cold starts remain as fast as possible.
Debugging
All demos include built-in debugging tools so you can understand how a deployment is behaving after boot. These tools can be viewed at the sandbox level or narrowed to individual services when a demo runs more than one process.
Tool | Purpose |
|---|---|
| Info | View the live Docker configuration for the sandbox and its services. |
| Logging | Inspect real-time output during boot and runtime. |
| Shell | Open a browser-based shell for direct inspection and debugging. |
| Stats | Monitor resource usage and runtime behavior while the demo is live. |
Use these tools to verify startup commands, inspect service behavior, and troubleshoot failed or unstable deployments.
For a broader look at sandbox behavior, compute limits, and runtime infrastructure, see Infrastructure.