Using Custom Templates in Bunnyshell
Marketplace templates are a great starting point, but most teams eventually need templates tailored to their own applications and infrastructure patterns. Custom templates let you encode your specific stack, conventions, and defaults into a reusable blueprint that anyone on your team can deploy. Watch the video above for a hands-on walkthrough of creating and publishing a custom template.
Template YAML Structure
Every Bunnyshell template is built on a YAML configuration file that defines the components, their relationships, and how they should be built and deployed. Understanding this structure is essential for creating effective custom templates.
At the top level, the template YAML includes metadata — a name, description, and version. Below that, the components section lists each service in your environment. A component entry specifies the source (a Git repository with a Dockerfile, or a pre-built Docker image), build configuration, exposed ports, environment variables, resource requests and limits, and dependencies on other components.
Here is what makes a template different from a regular environment configuration: parameters. A template wraps the environment YAML with a parameter definition layer. Parameters are placeholders for values that should be configurable at deployment time. For example, instead of hardcoding a Git repository URL, you define a parameter called repository_url with a default value and a description. When someone creates an environment from your template, they see this parameter in the UI and can override it.
The parameter definition includes the variable name, a human-readable label, a description, a default value, and optionally a validation rule (like a regex pattern or a list of allowed values). Well-defined parameters make templates self-documenting — users can understand what each value controls without reading the raw YAML.
Parameterizing Templates with Variables
The art of template design is choosing what to parameterize and what to keep fixed. Parameterize too little, and the template is rigid — users must fork and edit it for every variation. Parameterize too much, and the template becomes confusing — users face a wall of configuration options that they do not understand.
A good rule of thumb: parameterize what changes between deployments, hardcode what represents your architecture. Git repository URLs, branch names, database passwords, API keys, and feature flags are good candidates for parameters. Service topology, networking configuration, health check paths, and base image choices are better left as fixed values in the template, because they represent decisions your team has already made.
Bunnyshell supports variable interpolation throughout the template YAML. Parameters defined at the template level can be referenced anywhere in the configuration using the {{ "{{variable_name}}" }} syntax. This means a single parameter can control multiple configuration values — for example, a project_name parameter might be used in service names, DNS labels, and log prefixes simultaneously.
Publishing and Sharing Templates
Once your template is ready, you can publish it within your Bunnyshell organization. Published templates appear in the template selection screen when any team member creates a new environment. You can organize templates with descriptions, tags, and categories to help users find the right starting point.
Publishing a template does not mean it is frozen. You can update a published template at any time, and Bunnyshell tracks the version history. Existing environments are not affected by template updates — they continue running with the configuration they were created from. Users creating new environments will automatically get the latest version.
For teams with multiple projects that share a similar architecture, organization-level templates are a powerful standardization tool. The platform team maintains a library of approved templates, and product teams create environments from them. This ensures consistency in base images, security configurations, observability setup, and resource allocation across the entire organization.
Best practices for maintaining templates include keeping them in version control alongside your application code, testing template changes by creating an environment before publishing, documenting parameters clearly so users know what each one controls, and reviewing templates periodically to update base images and dependencies. Treat templates as a product — they are the interface between your platform and your developers.
Ship faster starting today.
14-day full-feature trial. No credit card required. Pay-as-you-go from $0.007/min per environment.
Frequently Asked Questions
How do I create a custom template in Bunnyshell?
Start by defining your environment configuration in a bunnyshell.yaml file that lists all components, their sources, build instructions, and environment variables. Then, in the Bunnyshell dashboard, navigate to Templates and create a new template from your YAML. You can add parameters to make values configurable, write a description, and publish the template for your team.
What should I parameterize in a Bunnyshell template?
Parameterize values that change between deployments — Git repository URLs, branch names, database credentials, API keys, resource limits, and feature flags. Keep infrastructure decisions like service topology and networking as fixed values in the template, since those represent your architecture standards.
Can I share templates across multiple Bunnyshell projects?
Yes. Templates can be published at the organization level, making them available to all projects and teams within your organization. This is ideal for platform teams that want to provide standardized environment configurations while letting individual teams customize deployment-specific parameters.