Deploy

Access Key

To find your account API Access Key, please visit either:

• The new Dashboard > Profile picture > Edit account details > API Key
• The old Panel > Account > API

All account API Access Keys are in uuid format, such as c24347cf-1bc0-4900-8d60-86b1c7701f53.

Please use your account API Access Key, not the Password or ReadOnlyPassword of your storage zone.

Please read the authentication guide to learn more about Access Key types.

Basic Auth Credential

Password-protect your website with basic auth by setting credentials.

Basic auth credentials are defined in the username:password format.

You may specify more than one credential for basic auth to support multiple user logins; however, bunny.net may limit the total number of credentials.

Be aware that not all programs support Unicode characters. ASCII is a safe choice.

Basic Auth Passwordless Stage

Remove password protection from specific deployment stages. By default, all stages are password protected.

Having a passwordless stage enables you to have a public version of your website for users, while having other private stages for developers to edit and test your website.

Common choices include main, production, prod, etc., whichever you picked as your --main-stage.

You may specify more than one passwordless stage.

To learn more about stages, check the --stage option.

Basic Auth Pattern

Sometimes, you may want just a portion of your website to be private.

For example, you may only want to password protect some urls, such as:

• /preview/launch-announcement
• /prerelease/*
• /newsletter/christmas-sale
• /subscribers/*

You may specify more than one pattern for basic auth password protection; however, bunny.net may limit the total number of patterns.

Build Before Deploy

Ensure your project always builds with the latest version of your code before deployment.

If true, Bunny Launcher will always run your build commands before deploying your website.

If false, you are responsible for building your project beforehand.

You can specify your build commands with the --build-command option.

You can think of these options as the equivalent of a pre- hook command from npm added for your convenience.

Build Command

The command(s) you use to build your website.

This option is meant to be used in conjunction with the --build-before-deploy option.

You can specify multiple build commands.

All commands will be run before publishing if the --build-before-deploy option is true.

You can think of these options as the equivalent of a pre- hook command from npm added for your convenience.

Build Framework

The framework you use to build your website. To see if your framework is supported, read the framework guides.

Please be sure to read your framework guide, since some frameworks require additional configuration.

This option, which is automatically detected and configured by default, will set default options for your deployment depending on your framework:

• --build-command
• --build-framework
• --build-out-dir
• --build-out-dir
• --not-found-spa

You can override the default options or use the Static HTML framework with your own options instead.

Build Out Dir

The folder your would like deployed.

Usually, this folder is named dist. However, your framework may choose a different folder or you may select your own folder.

The default value depends on your framework.

Build Package Manager

If you are using Node.js, your preferred package manager. Otherwise, please leave this option undefined.

This option is automatically inferred from your project in this order of precedence:

1. Your packageManager field from your package.json
2. Your engines field from your package.json, if it specifies an npm version.
3. Your lockfile in your current working directory

It is recommended to install bunny-launcher in your devDependencies to lock the version of bunny-launcher for consistency.

Country Allowed

Specify the countries allowed to visit your website. By default, all countries are allowed.

All country codes are based on the ISO 3166-1 alpha-2 standard. For example:

• US United States of America
• UK United Kingdom

If your company only does business within the United States, you may decide to block all other countries from accessing your website by only specifying US.

If you specify this option, you cannot also specify the --country-blocked option at the same time.

Country Blocked

Specify the countries blocked from visiting your website. By default, no countries are blocked.

All country codes are based on the ISO 3166-1 alpha-2 standard. For example:

• RU Russian Federation
• CN China

If you would like to block countries that the United States has sanctioned, you can do that too:

• CU Cuba
• IR Iran
• KP North Korea
• SY Syria

If you specify this option, you cannot also specify the --country-allowed option at the same time.

Custom Header

Specify custom headers to add to your responses.

This option is great for adding security headers or setting cross origin isolation to enable features like SharedArrayBuffer.

All headers should be specified in json:

{"X-Powered-By": "bunny-launcher"}

You can specify custom headers as either a single object with a single flag or multiple objects with multiple flags. However, setting this option in the config is easiest.

Domain Alias

Specify other domains or subdomains that should be redirected to the domain or subdomain you specified for the --domain-name option.

The most common example is redirecting www.example.com to example.com, or vice versa.

With the explosion in TLDs, you may prefer to redirect other domains too. For example, redirecting bunny.com to bunny.net.

You can specify more than one domain alias; however, bunny.net may limit the total number of aliases.

Your options depend on your record type. To learn more about DNS Record types and their limitations, please read the --domain-type option documentation first.

When using the --stage option, you may include a {stage} variable in the domain alias.

For example, www.{stage}.example.com will be deployed as www.dev.example.com when the current stage is dev. Otherwise, when the --stage option is the same as the --main-stage option, the domain alias will be www.example.com.

Domain Name

Specify your website domain or subdomain. (e.g. example.com or www.example.com).

Your options depend on your record type. To learn more about DNS Record types and their limitations, please read the --domain-type option documentation first.

When using the --stage option, you may include a {stage} variable in the domain name.

For example, {stage}.example.com will be deployed as dev.example.com when the current stage is dev. Otherwise, when the --stage option is the same as the --main-stage option, the domain name will be example.com.

If you do not have a domain name, you can set the --domain-type option to cname and use any subdomain from *.b-cdn.net. However, we strongly recommend purchasing a domain name.

Domain Registrar

The domain registrar where you purchased your domain.

We provide guides for many domain registrars. Please find your specific registrar guide to link your domain to your new website.

To find the correct guide, you will also need to know your --domain-type option.

Domain Type

Bunny Launcher supports three domain types, each with their own benefits and drawbacks.

We provide guides for many domain registrars. Please find your specific registrar guide to link your domain to your new website, depending on your domain type.

This option applies to both the domain name and domain aliases options.

cname

The cname DNS Record type is the easiest and most common type to use.

The benefits of the cname DNS Record include:

• Supports subdomains (e.g. www.example.com, not example.com)
• Easiest DNS Record type to create
• Compatible with all domain registrars
• No nameserver migration needed

The drawbacks of the cname DNS Record include:

• Does not support root domains (e.g. example.com)
• The cname DNS Record must be created manually

nameserver

The nameserver type involves migrating your domain name servers to bunny.net, which provides a bulk import feature.

The benefits of the nameserver type include:

• Automatically create all DNS Records (e.g. the domain name and domain aliases) for websites deployed with Bunny Launcher
• Supports both root domains and subdomains (e.g. www.example.com and example.com)
• The performance of bunny.net is often faster than your domain registrar and other nameservers

The drawbacks of the nameserver type include:

• Migrating all DNS records to bunny.net nameservers is required beforehand
• After the free tier, bunny.net charges for DNS queries
• Rarely, some domain registrars (e.g. Cloudflare) do not allow you to change nameservers.

aname

The aname record, also known as cname flattening, is mainly included for Cloudflare compatibility.

The benefits of the aname type include:

• Supports root domains (e.g. example.com, not www.example.com)

The drawbacks of the aname type include:

• Does not support subdomains (e.g. www.example.com)
• Performance penalties if your nameservers do not support Anycast DNS (supported by both bunny.net and Cloudflare)
• The aname DNS Record must be created manually

Edge Rule

Edge rules are an advanced feature of Pull Zones. This flag is for advanced users.

The Bunny Launcher uses edge rules behind the scenes to implement many of its options.

Edge rules mirror the json format used in the bunny.net api.

The main exception is that the Guid property cannot be specified, since bunny.net automatically generates it.

To compare edge rules in the config file to edge rules in the pull zone, Bunny Launcher uses the description property. Each edge rule description within a pull zone must be unique, but multiple pull zones may have the same edge rule description.

Any edge rule that is manually created outside of the config will be deleted when the website is deployed again. Please keep the edge rules in your config.

The easiest way to create a new edge rule is:

1. Create a demo edge rule in the bunny.net dashboard
2. Test the demo rule to ensure it behaves as expected
3. Use the Get Pull Zone API Docs or the Bunny CLI to print the pull zone with its edge rules.
4. Copy your demo edge rule to your config
5. Delete the edge rule Guid property in your config
6. Save your config file
7. Deploy your website again with the new edge rule

Image Optimizer

Enable the Bunny Optimizer to automatically resize and reformat images on your website.

To learn more about the Bunny Optimizer and its image processing options, please read the docs.

Perfect for improving performance with frameworks (e.g. Next.js) that do not support image optimization.

To load images from Bunny Optimizer, try Unpic components, which support several frameworks.

By default, the Bunny Optimizer is not enabled.

Interactive

Deploy your website in a single command:

npx --yes bunny-launcher@latest --interactive

This flag enables the interactive guide, which will describe options, ask questions to fill in your config, and subsequently deploy your website.

There are several options that are not included in the interactive guide.

If you would like to interactively fill in your config, but not deploy your website, use:

npx --yes create-bunny-launcher@latest --interactive

If you would like to validate your config, use:

npx --yes create-bunny-launcher@latest

IP Blocked

The IP addresses that will be blocked from visiting your website.

Specify the flag multiple times to block multiple IP addresses.

However, bunny.net may limit the total number of blocked IP addresses.

Logging Storage Zone

The storage zone name or id that you would like to set as the Permanent Log Storage.

The Logging IP Anonymization is automatically disabled.

Before enabling Permanent Log Storage, you must sign the DPA agreement (GDPR).

Before signing the agreement, please fill out your personal information:

• The new Dashboard > Profile picture > GDPR > Account > Personal details
• The old Panel > Account > Update account details

To sign the agreement, please go to:

• The new Dashboard > Profile picture > GDPR > Data Processing (GDPR)
• The old Panel > Account > Data Processing (GDPR)

Main Stage

Websites are often deployed in several environments.

However, only one stage is the main stage. It goes by many names (e.g. main, production, prod, etc.).

To make automated deployment from git-based CI/CD pipelines easier, the default main stage is called main. You may change it to whichever name you prefer.

To learn more about stages, check these options:

• --stage
• --domain-name
• --domain-alias

Not Found Path

Define a custom 404 Not Found page when your users visit a URL that does not exist.

If the --not-found-spa option is false, the default value in order of precedence is:

1. 404.html
2. 404/index.html
3. bunnycdn_errors/404.html
4. 200.html

If the --not-found-spa option is true, the default value in order of precedence is:

1. index.html
2. 200.html

You can specify your own file path, but we recommend sticking with the conventions.

Not Found Spa

Configure the server to host a Single Page Application (SPA).

The server will:

• Rewrite the 404 Not Found status code to 200 OK
• Always return the file defined by --not-found-path

The default value depends on your framework.

Optimize

Tune your bunny.net config to prioritize either performance or cost. Pick the one that best suits your needs.

Many Storage Zone and CDN type and region settings cannot be changed after creation. If you would like to change the optimize option later, you must remove your website and deploy it again.

Performance

Bunny.net ranked the #1 fastest global CDN in 2023, and prioritizing performance gives you that lightning speed.

Changed settings include:

• Edge Tier SSD storage zone
• Replicated storage zones across all available regions
• Bunny CDN Standard Network with 114+ PoPs worldwide

Cost

For high traffic or bandwidth heavy websites, prioritizing cost gives you speed at an affordable price.

Changed settings include:

• Single Standard Tier HDD storage zone in Frankfurt, Germany
• Replicated storage zones are disabled
• Bunny CDN Volume Network with 10 PoPs worldwide

Profile

Your profile is any easy-to-remember name that you gave to reference your API Access Key. By saving an API Access Key under a profile, you can use that profile to easily select, change, and remove your API Access Key.

If you only have one profile, that one profile is your default profile and will be automatically selected for all of your commands. When possible, commands will automatically select profiles based on the storage zones, pull zones, dns zones, and linked hostnames in an account.

If you have multiple profiles and a profile cannot be inferred, then specifying the profile will tell the command which profile it should use. A specified profile name will override all inference, unless the environment variable BUNNY_ACCESS_KEY or the command line flag --access-key is provided.

Redirect

Sometimes, webpages are renamed, re-organized, or changed. Broken URLs need to be redirected to avoid SEO penalties.

To set redirects, define them in json:

{
  "/about-us": "/about",
  "/contact-us": "/contact"
}

Unfortunately, due to limits in bunny.net edge rules, it is not possible to redirect globs or variables. Only redirect one webpage to another webpage.

However, bunny.net may limit the total number of redirects.

Referrer Allowed

Blocking requests that do not come from your domain prevents other websites from hotlinking your resources, which would have cost you bandwidth and money.

When a user visits your webpages, their web browser may send an (intentionally misspelled) referer header on each request. This header often contains the URL or origin of the webpage they are visiting.

The referer header is sent in many, but not all, cases. For those cases where it is not sent (e.g. typing the URL directly, removed for privacy reasons, etc.), the --referrer-block-none-referrer determines whether the request without the referer header is blocked or not.

By default, your --domain-name is automatically allow listed, except when you specify your own values or use the --referrer-blocked option.

If you specify this option, you cannot also specify the --referrer-blocked option at the same time.

Referrer Blocked

You may decide to only block requests from websites that are using your resources and costing you significant bandwidth and money from hotlinking, rather than all websites.

When a user visits your webpages, their web browser may send an (intentionally misspelled) referer header on each request. This header often contains the URL or origin of the webpage they are visiting.

The referer header is sent in many, but not all, cases. For those cases where it is not sent (e.g. typing the URL directly, removed for privacy reasons, etc.), the --referrer-block-none-referrer determines whether the request without the referer header is blocked or not.

If you specify this option, you cannot also specify the --referrer-allowed option at the same time.

Referrer Block None Referrer

The referer header is sent in many, but not all, cases. For those cases where it is not sent (e.g. typing the URL directly, removed for privacy reasons, etc.), this option determines whether the request without the referer header is blocked or not.

Assuming you are hosting your website with Bunny Launcher, this option should always be false. If you are only hosting assets (e.g. images), then you may consider setting this option to true. Even then, you may unwittingly block users from accessing your resources if you are using them in other contexts, like emails.

Instead, using the --referrer-allowed option is recommended to prevent other websites from hotlinking your resources, which would have cost you bandwidth and money.

Schema

The schema option defines the location for the config’s json schema, which provides autocomplete when creating and editing your config.

Recommended values include:

• ./node-modules/bunny-launcher/schema.json
• https://cdn.jsdelivr.net/npm/bunny-launcher@0.0.0/schema.json
• https://unpkg.com/bunny-launcher@0.0.0/schema.json

When possible, pin the version instead of using the latest version. The config format and schema may change between versions. If you must use the latest version, use:

• https://bunny-launcher.com/static/json-schema/bunny-launcher/schema.json
• https://cdn.jsdelivr.net/npm/bunny-launcher/schema.json
• https://unpkg.com/bunny-launcher/schema.json

The default value depends on your framework.

Shared Credentials File

All profiles are saved by default in ~/.bunny/credentials.

The shared credentials file follows the TOML v1.0.0 format specification.

Each profile consists of a:

• profile
• accessKey
• email
• id
• name (optional)

[personal]
accessKey = "c24347cf-1bc0-4900-8d60-86b1c7701f53"
email = "johndoe@example.com"
id = "31141ed7-9a4c-48b3-9910-676f9c999d70"

[business]
accessKey = "85e2e568-dc73-47c2-8530-ce8f8f42fe6c"
email = "johndoe@company.com"
id = "5552c462-bde1-4a41-88ed-d8c1bc1c51bc"
name = "John Doe"

Stage

Websites are often deployed in several environments.

You may have a public production stage for users visiting your website, a private staging stage for previewing changes before they are deployed to production, and many development stages for your developers.

How many stages you have and how you decide to name them is up to you.

The most important stage is the --main-stage, which goes by many names (e.g. main, production, prod, etc.).

This option and the --main-stage option affect both the --domain-name and the --domain-alias options.

We recommend specifying your stage. When the stage option is not specified, the default stage is selected in this order of precedence:

1. If you define a .bunny/stage file with the stage name inside, that will be your default stage. You can add the stage file to your .gitignore file.
2. If the CI environment variable is truthy, the default stage is the same as the --main-stage option.
3. If the CI environment variable is falsy, the default stage is the same as the current username. If the username cannot be found, you must set the stage yourself.

Version

The version of the bunny-launcher package that the config was created or first deployed with.

By tracking the package version in the config, it is possible to automatically migrate old config schemas to the latest config schema.

This option can only be specified in the config file. It cannot be passed as a command line flag or environment variable.

Write Config

Automatically write the resolved config after deployment.

In cases where there are readonly file systems or other errors, this option will fail gracefully without throwing an error.

This option is true by default, and it is recommended to leave the option enabled.