All docs on one page

# BETA (now)

{#beta-now}

Welcome to the public BETA of the new fortrabbit platform. Now ready for your real-world applications.

# Our goals of the BETA

{#our-goals-of-the-beta}

• Gather more real-world feedback
• Harden the platform
• Catch some edge cases
• Complete missing features

# Benefits for you

{#benefits-for-you}

• Experience a new features first
• Try new features landing soon
• Attractive pricing
• Expect good stability
• Enjoy the new design
• Enjoy the new docs

# Current limits

{#current-limits}

At the time of this writing the following features are still missing but planned to be added soon:

• Only one data center (EU) is available for now
• No real-time live updates in the dashboard yet
• Metrics are not yet implemented
• Autoscaling is not available yet
• Event log is not ready yet
• Streaming logs implementation will change, see log usage
• Collaboration features are still a bit rough
• Many smaller features are not fully implemented
• No SEPA direct debit payments, only credit card
• Short downtimes may happen from time to time (see below)

# Short hiccups

{#short-hiccups}

We are experimenting with shorter-lived instances to run the web frontends. These can be interrupted at any time by our infrastructure provider with some notification in advance. But, sometimes this notification is still too late to restart all the applications somewhere else without any disruption. We are still in the process of trying to improve this situation and lower the downtimes as much as possible. Please bear with us for now. So for now, small hiccups of a couple of minutes are actually expected.

Feedback on this specifically very welcome. How important is this uptime for you at what level? Maybe acceptable for staging environments and XS projects?

# Do

{#do}

• Deploy production websites
• Find use cases we haven't thought about
• Uncover communication issues
• Create apps and environments
• Help hunting bugs
• Deploy code
• Route domains
• Change settings
• Test performance

# Feedback scope

{#feedback-scope}

• Product and pricing
• Feature scope and market positioning
• UI/UX/DX/design
• Communication
• General ideas
• Be direct and honest please

# Timing

{#timing}

We plan to transition to general availability after a few months of BETA testing. At the time of this writing, something between 3 and 9 months. There are a couple of features that we regard as important for full public release. We also plan to implement some customer feedback during BETA.

During the BETA time period - and beyond - the old platform will continue to run normally. New and old platform will run side by side. There is no rush for existing customers. There will be extensive help and communication for the migration.

# Stability

{#stability}

We promise to do everything we can to keep your apps up and running. We offer a conservative 98% uptime SLA during BETA, aiming for more. Monitoring is in place and we act as quickly as possible when something looks off.

• fortrabbit.betteruptime.com - status monitor including automated tests, covering the Alpha period as well

The platform is still under active development. We usually release once a week. New features are only deployed after automated checks and human testing.

• edge - local development
• staging - test environment
• production - where the BETA runs

During the ALPHA we were able to catch many early issues. For the BETA period now, we want to gain more experience with larger real-world applications and run into all kinds of edge cases to harden the platform further.

# Terms

{#terms}

The legal section has been updated. The new terms are applicable for new and old customers for the new and the old platform. There are only minor adjustments.

# Pricing

{#pricing}

The BETA is paid, but prices may change. We plan to introduce final pricing and billing during the BETA. Feedback on this very much welcome!

# Info for ALPHA testers

{#info-for-alpha-testers}

Thanks again for your feedback during the first phase. Much appreciated. We had to do some data structure changes recently. So at best please:

• Payment methods: Create a new one and attach any apps to the new one.
• fortrabbit GitHub App: Disconnect and re-connect the fortrabbit GitHub App.

# New and old - side by side

{#new-and-old-side-by-side}

fortrabbit currently operates two platforms - the new and the old. They run side-by-side, giving existing customers enough time to migrate their projects.

The old platform remains fully functional and supported. It will be phased out slowly, so there is no rush to leave. We aim to make the migration as seamless as possible, with details and timing to follow.

The new platform is live and open to everyone. Experience a redesigned, yet familiar fortrabbit.

# New customers

{#new-customers}

Start with the new platform.

# Existing customers

{#existing-customers}

You can use both platforms simultaneously. Accounts have not been transferred. Please create a new account on the new platform, ideally using the same email address for future matching. We suggest to already create new apps on the new platform, while continuing to manage existing apps on the old one.

# Timeline

{#timeline}

The exact support duration for the old platform is not yet defined. It will depend on customer feedback and needs.

██████████████████░░░░░  Old platform

                ⇣ ⇣   Migration

 ░░░░░░░░░░░░░░██████████████████████████████████████████████████  New platform

2025     2026     2027     2028     2029     2030
raw

# Milestones

{#milestones}

• 2025 New platform launches in BETA
• 2026 New platform becomes generally available (feature complete)
• 2026 Migration phase old → new
• 2027 Old platform sunset

# Changes

{#changes}

This page compares old and new platform, see new features and deprecations.

# Changes

{#changes-1}

What is new and different to the old platform?

# New core

{#new-core}

It's an entirely new hosting platform. The infra layer is completely new.

# New dashboard

{#new-dashboard}

There is a new self-service dashboard, available under dash.fortrabbit.com.

# One stack

{#one-stack}

The legacy platform features two different stacks: Universal Apps (with persistent storage and direct SSH access) and Professional Apps (with ephemeral storage and horizontal scaling). For the new platform attributes from both previous stacks are combined into one. The new platform is more Uni-App-like with persistent storage and direct SSH/SFTP access.

# Environments

{#environments}

To better support production-staging workflows the app is now a grouping object. Dedicated hosting stacks are mapped with environments. An app is connected to the (external) Git repo, each individually scalable environment represents a branch. At least one environment, usually production, adding and removing environments is optional.

# Git deployment

{#git-deployment}

fortrabbit no longer provides Git repo hosting. Connect your GitHub (other providers like GitLab and CodeBerg are planned) with the fortrabbit GitHub app to enable git push deployment instead. See the GitHub integration.

We believe this is what the majority of new users want. Our self-hosted repo didn't support PR workflows and other advanced features that GitHub and similar platforms offer. The GitHub App integration is smooth and straightforward. We've created a system to detect software, propose a build pipeline, and provide detailed deployment options. GitHub offers generous free plans with private repos. Using a third party Git provider reduces your dependence on us.

We understand that some people may have privacy concerns about GitHub, as it is owned by Microsoft. We are aware it's a big change for existing customers. Feedback on this is welcome.

Mind that using our Git deployment is not a requirement, it's optional. Direct SSH/SFTP access is always possible. This already allows integrations with other Git providers today, see the Git providers integration section.

# Build commands

{#build-commands}

The deployment pipeline is more configurable. Node.js is available during the deployment to create JavaScript bundles. See the new build commands article.

# Collaboration

{#collaboration}

Collaboration workflows have been extended. The concepts are similar, yet more flexible.

With the old platform, it was required to join the Company of the business owner to get access on their Apps. Re-inviting colleagues was not only a repetitive task, but also destroying attribution. With the new platform, the relation between the parties is more transparent.

No more company plans: Collaboration on the legacy platform is a paid feature for larger teams. All collaboration features are now available for free.

People

{#people}

We are doubling down on personal access. Each person involved should their own (free) account. This enables more scenarios and better mapping of real world business relations. See the person object article.

Teams

{#teams}

Instead of a hierarchical structure with the Company as the root element, there are decoupled but related objects now. Use the new team to collaborate with a group of developers. Teams are connected to apps, developers and payment methods. See the team article.

Payment methods

{#payment-methods}

A Billing Contact is now called payment method. Like the old Billing Contact, it holds the billing credentials. Unlike before, it is not part of a Company but instead is managed by clients, individual developers and teams. A payment method pays for the apps, thus people in control of the payment method control the hosting.

# Pricing

{#pricing-1}

Billing concepts mostly stay the same. There still is pro-rated post-paid billing. See price comparison for more details. Note that prices can still change during BETA.

# Components

{#components}

The pricing structure, as with the former Pro Stack, is based on components. This enables you to book only required resources, avoiding over-provisioning. Presets to get started quickly are available.

# Workers and crons

{#workers-and-crons}

Workers & crons jobs are available for all.

# Backups with restore

{#backups-with-restore}

The new backup component offers one click restore of old states.

# New documentation

{#new-documentation}

The website you are currently viewing is part of the new documentation.

# App names and IDs

{#app-names-and-ids}

Previously, the App name served as the unique identifier, test URL, and credential base. This enforced strict naming conventions and prevented renaming. The new platform separates identity from display:

• ID: Immutable unique identifier
  • Used for the test URL {{app-env-id}}.frbit.app
• Name: Display label
  • Can be changed at any time and has no format restrictions

Apps now serve as containers for environments. The app name will represent the

Vanity URLs for custom subdomains are planned, a fortrabbit branded subdomain that works like any other domain. Without having to deal with DNS entries. {{my-name}}.frbit.webhost.

# Deprecations

{#deprecations}

Which features will not be available?

# No PHP 7.4

{#no-php-7-4}

The new platform wil only offer PHP 8 and upwards. Make sure the software you run is compatible.

# SSH keys only

{#ssh-keys-only}

Sorry, username/password is no longer an option to connect via SSH or SFTP. Please use more secure and more convenient SSH key authentication. Issues with username/password authentication have been the source of many support requests.

# No horizontal scaling

{#no-horizontal-scaling}

There is no horizontal scaling any more, but higher vertical scaling to cover similar workloads. To achieve this we went a long mile, but it was an important goal, the two stacks have been a barrier.

# No object storage

{#no-object-storage}

The new platform currently does not have S3 like asset storage. We may add it later. Larger web storage plans are available.

# No memcache

{#no-memcache}

Memcache is not available for the new platform. A different key-value storage is planned.

# No Craft Copy (for now)

{#no-craft-copy-for-now}

Craft Copy is a command line tool to speed up common tasks around Craft CMS deployment on fortrabbit craft copy all/up. It's available as a free plugin for Craft CMS. People enjoy using it. We may not port it to the new platform. Here is why:

• Craft Copy is a compatibility layer, parts are not required any more:
  • delete config files -> replace patterns
  • auto-migrate -> post deploy commands
  • Craft CMS software template
• Other parts, like db/down, might be replaced by general tooling:
  • fortrabbit CLI
  • DDEV fortrabbit recipe
  • Improved documentation on our side
• fortrabbit does not provide a Git repo any more

We aim to be a good Craft CMS hosting provider, as compatible as possible, best without additional plugins required. Maintaining Craft Copy over the years was not always fun, for instance when a minor Craft CMS release introduced changes that required us to rethink critical parts.

We are very open for feedback on all of this.

# Price comparison (old/new)

{#price-comparison-old-new}

The new platform is more affordable than the old platform for most real live use cases. This page helps understanding pricing differences and choosing matching plans.

# Product changes affecting pricing

{#product-changes-affecting-pricing}

The following structural changes in the new platform directly affect pricing:

# Component based pricing model

{#component-based-pricing-model}

The new platform adopts a component-based pricing structure, similar to the former Pro Stack. This allows for individual scaling of resources, enabling you to pay only for what you need.

This allows better matching pricing for:

• Standard CMS systems with a LAMP stack
• Sophisticated web applications with jobs and key-value store
• Static file systems

# No more Company Plans

{#no-more-company-plans}

The old platform had company plans. It was built with good intentions, aiming to offer lower rates for solo developers while charging larger teams more. This model often caused confusion. The new platform removes Company Plans. All collaboration features are now included at no extra cost.

# New backup options

{#new-backup-options}

The backup system has been improved. Key features include one-click restores and ad-hoc backups on click. Retention policies (WIP) are being introduced to optimize storage while ensuring access to both recent and historical backups. While the new backup pricing might appear higher when comparing solely by quantity, the enhanced functionality provides greater value and security.

# Autoscaling (WIP)

{#autoscaling-wip}

The new platform supports autoscaling for MySQL, storage, and traffic, aligning with our "start small, scale later" philosophy. This eliminates the need to over-provision resources or upgrade entire packages when a single resource limit is reached, as was the case with the Uni Stack. Cost caps can still be applied, which is useful for budgeting and client communication.

# New XS options

{#new-xs-options}

The new XS plans options are specifically designed to allow creating small projects. This can be staging environments, weekend hacks, mini client projects. The smallest possible combination starts at €2.50.

# Traffic is a component

{#traffic-is-a-component}

On the old platform, 50 GB of traffic was included. Exceeding this limit incurred a charge of €1 per additional 5 GB. This overage charge was often unexpected. On the new platform, traffic is treated as a distinct component (with tiers) that can be either capped or set to auto-scale.

# New architecture

{#new-architecture}

The new infrastructure layer is even more optimized for speedy PHP web delivery. While we don't have benchmarks to share, we are confident that the new platform allows to do more with less.

# Universal Stack mapping

{#universal-stack-mapping}

The following new platform plan combinations roughly match former Uni App plans:

# Light plan equivalent

{#light-plan-equivalent}

formerly priced at €5.0

# Standard plan equivalent

{#standard-plan-equivalent}

formerly priced at €15.0

# Plus plan equivalent

{#plus-plan-equivalent}

formerly priced at €30.0

# Further details

{#further-details}

• Pricing new platform
• Specs Uni Stack (old platform)
• Specs Pro Stack (old platform)
• https://web.archive.org/web/20250513173439/https://www.fortrabbit.com/pricing

# Migration from old to new platform

{#migration-from-old-to-new-platform}

With the new platform's general availability planned for 2026, we expect feature parity between the old and new systems. Customers are invited to migrate their apps at their convenience, with our full support. We plan to migrate all remaining apps automatically at the end of the transition period.

# Self-service migration

{#self-service-migration}

Early adopters are welcome to migrate their apps to the new platform. Here is a recommended workflow overview using Git deployment:

1. Create a new App on the new platform
2. Install the fortrabbit GitHub App on your GitHub account
3. Create a new repository or map an existing one on GitHub
4. Connect your local codebase to the GitHub repository
5. Push to deploy
6. Sync your database to the new App (if required)
7. Sync your content to the new App (if required)
8. Test functionality
9. Point your domain to the new DNS records

Please contact us at any point during the process. We are happy to provide hands-on assistance. We can also offer a discount during the migration period.

# fortrabbit migration (planned)

{#fortrabbit-migration-planned}

In the future, we will plan to migrate remaining client apps from the old platform to the new one. In most cases, this will not require any action from you, though a maintenance window with some downtime may be necessary. We will inform you well in advance.

# New platform

{#new-platform}

Experience the all new fortrabbit. Now.

# First steps

{#first-steps}

fortrabbit is a platform to deploy and host PHP websites and web applications. The GitHub integration provides deployment directly from the repo. Projects are represented as apps with environments. The collaboration features map real world relations between developers and stakeholders.

# 1. Sign up

{#1-sign-up}

Create a free personal account over at our dashboard.

# 2. Create a free trial app

{#2-create-a-free-trial-app}

During boarding you will be guided to create your first app. Choose the free trial for a quick test drive.

# 3. Explore

{#3-explore}

Explore all the settings in the dashboard. Login by SSH or SFTP. Deploy some code. Browse our docs here. There are extensive guides for:

• Craft CMS
• Laravel
• Kirby CMS
• Statamic
• October CMS
• and even WordPress

Please contact us if you have a question or want to leave feedback.

# 4. Start for real

{#4-start-for-real}

If you like what you see, migrate existing or start new projects here. Invite other developers or your clients to collaborate here.

# Project organization

{#project-organization}

# Intro

{#intro}

The fortrabbit platform has two layers to map web projects:

• App: Git repo, collaboration.
• Environment: Runtime, git branch, code access, components, settings.

# Workflows

{#workflows}

There is a main way to set this up and a couple of other possible workflows that are more or less sub-optimal:

# Projects as apps, environments are stages

{#projects-as-apps-environments-are-stages}

- App: 'My website project'
  - Environment 1: 'Main' - live production
  - Environment 2: 'Dev' - feature development (optional)
raw

Use environments as versions of the website. When using git deployment, branches can be mapped to environments. See the multi staging article. Each app requires at least one environment. One app with one environment is also common.

Rating: ✅ ✅ ✅ ✅

# Projects as folders in an environment

{#projects-as-folders-in-an-environment}

- App: 'My agency'
  - Environment 1: 'Main'
    - Folders: 'website-1', 'website-2' …
raw

Web projects are just folders in a single environment. This might be viable for micro sites, but has some downsides. When routing domains, .htaccess must be used. Resources like the database need to be shared.

Many CMS systems offer multi-site features, which works in a similar way. There are use cases for it, but in general individual installations will work better.

Rating: ❌ ❌ ✅ ✅

# Project parts as environments

{#project-parts-as-environments}

- App: 'website-1'
  - Environment 1: 'frontend'
  - Environment 2: 'backend'
raw

Environments map to parts of a web project. This may work for headless CMS systems, where frontend and backend are separated software.

Rating: ❌ ❌ ✅ ✅

# Projects as environments

{#projects-as-environments}

- App: 'My agency'
  - Environment 1: 'website-1'
  - Environment 2: 'website-2'
  - Environment 3: 'website-3'
raw

Web projects map to environments. This might be viable for tiny micro sites, but is sub-optimal. Resources and settings are shared. Individual web project access in collaboration is not possible.

Rating: ❌ ❌ ❌ ✅

# Projects as apps, stages as folders

{#projects-as-apps-stages-as-folders}

- App: 'website-1'
  - Environment 1: 'Main'
    - Folders: 'prod', 'staging'
raw

In this workflow, environments are ignored, instead stages are mapped as folders in one environment. This may not work as intended.

Rating: ❌ ❌ ❌ ✅

# Free trial details

{#free-trial-details}

Each new app at fortrabbit starts with a free trial that is limited in time. Use cases, options and limits.

# Starting a new trial

{#starting-a-new-trial}

Create a new app in to the dashboard.

# Use cases

{#use-cases}

The flexible free trial allows a variety of use cases and workflows. Fair usage of provided resources is expected.

• Exploring the platform
• Feature development
• Handover work to a client
• Weekend experiments

# Trial time limit

{#trial-time-limit}

There is a 72h time limit for the trial. A countdown timer in the dashboard with the app will show you the time left. We may experiment with different timing options.

# Trial end

{#trial-end}

When setting an app in trial mode you can define what shall happen when the trial period ends:

# Opt-in

{#opt-in}

• no credit card required
• the app will be deleted at the end of the trial time
• upgrade at any time before to keep it

# Opt-out

{#opt-out}

• credit card required (no charges during trial)
• start paying after the trial ends
• cancel at any time before

The free trial is only limited by time. It's possible to book all components in all sizes. For larger plans opt-in is required.

# Get started

{#get-started}

# Account organization

{#account-organization}

Prefer one fortrabbit account per person. Create additional accounts only for strict separation or when using separate GitHub identities.

# Best use one account only

{#best-use-one-account-only}

A fortrabbit account maps to a person in real life. People manage apps, teams, and payment methods.

# How NOT to handle one account

{#how-not-to-handle-one-account}

• No account sharing please - No need to create an account and share credentials with colleagues or clients. Use collaboration features.
• No generic accounts please - Please sign up with firstname.lastname@company.com and not accounts@company.com.

# Why to have multiple fortrabbit accounts

{#why-to-have-multiple-fortrabbit-accounts}

In some scenarios it might be advisable to have multiple accounts at fortrabbit as one individual:

# Strict separation

{#strict-separation}

Collaboration features are designed to be open and transparent. Collaborators can see your other apps, payment methods, and teams on your profile. They can see names and metadata, but cannot access them. Often that is desired; this way you can request access to an app that you need to work on as well.

If you don't want to expose any of your other projects to your co-workers, create a second private account at fortrabbit.

# Multiple GitHub accounts

{#multiple-github-accounts}

At GitHub you can also use one Account to manage personal repos, contribute to other people's repos, and be part of multiple organizations. But when you have multiple accounts at GitHub, maybe one for work and a private one, you may also want to keep that separation with fortrabbit.

# GitHub connection limits

{#github-connection-limits}

• You can't connect the same GitHub account to multiple accounts at fortrabbit
• You can't connect multiple GitHub accounts to one account at fortrabbit

# How NOT to handle multiple accounts

{#how-not-to-handle-multiple-accounts}

• New account for each app - NO! You can have multiple apps
• New account for new trial - NO! Each new app starts as a new trial
• New account for each client - NO! Use client collaboration
• New account for organization - NO! Use developer collaboration

# Components intro

{#components-intro}

Individually scalable hosting resources for each environment.

# Intro

{#intro-1}

With VPS hosting you pay for size of your box. Within that box you can run different services. fortrabbit on the other side has a micro service oriented architecture with services running in isolated containers. This architecture is reflected in the pricing. A component represents a service that can be booked and scaled individually per environment.

PHP, database, but also traffic and storage are components. Most components are available in different sizes, those are called plans and are titled like t-shirt labels: XS, S, M, L …. Different resource attributes are associated with the plans as well.

See the components list for all available components. The pricing page gives you an overview. The pricing intro explains level billing concepts.

# Required and optional components

{#required-and-optional-components}

The components PHP, traffic and storage are required, they can not be deselected. All other components are optional.

# Components during the free trial

{#components-during-the-free-trial}

All components are available with the free trial. They are however limited to the smallest plan.

# Stack detector

{#stack-detector}

Automatic pre-configuration of hosting settings based on project requirements found with a Git repo.

When connecting a Git repo from GitHub while setting up an app for git deployment, the code in the repo will be scanned using the stack detector:

• github.com/fortrabbit/stack-detector - open source

It will discover the used software packages and versions. Matching settings from the software templates will be applied. In addition composer.json and package.json will be parsed to suggest custom build commands:

• npm run build will be set when a package.json is present
• composer install will be set when a composer.json is present

# Software templates

{#software-templates}

We maintain a list of hosting settings for popular software to be pre-configured for smooth setup. When setting up an app with Git deployment the repos will be parsed by the stack detector and the software will be detected automatically. If the software is not detected or setup without Git deployment is preferred, the software can be chosen by the user. Software templates are version aware (although just major versions).

• Book matching components
• Enable PHP extensions
• Apply desired root path — to serve from the right location
• Populate ENV vars — to connect to the database automatically
• Suggest post deploy commands

This is especially handy with modern software that supports ENV var configuration and environment detection — like Laravel or Craft CMS do.

# What it does not do

{#what-it-does-not-do}

The software template will NOT install the selected software on your behalf. Installing software with composer is easy. We expect you to have a local development running before. In many cases developers bring existing projects.

# Limitations

{#limitations}

Aren't there always some? Heads up so it doesn't cost you hours of researching in the wrong direction.

# This is not VPS hosting

{#this-is-not-vps-hosting}

The fortrabbit platform has a service oriented architecture with individually scalable as components. The environment are lightweight containers that are optimized for speedy web delivery of PHP applications. If you are shopping for as much hardware resources as possible for as little money as possible, you might look elsewhere.

# No 1-click installers

{#no-1-click-installers}

When creating an app we ask for the desired software you are about to use. This can be Laravel, Craft CMS, WordPress or alike. That will not install the software. Read more more about the software templates here.

# No root shell

{#no-root-shell}

The SSH environment is "jailed". So you can use it for deployment and for common tasks around development. Therefore, it's NOT possible to install software like: FFmpeg, Node, NPM, Gulp, webpack, ruby, Rails or a mail server. We do this for security and performance and security design reasons.

# Need to call via php interpreter

{#need-to-call-via-php-interpreter}

To launch a PHP script you need to specify the PHP interpreter explicitly: for example, php artisan or php craft.

# No image optimization tools

{#no-image-optimization-tools}

Tools like jpegoptim, optipng, pngquant, SVGO, gifsicle and alike can help to reduce file size of your images. Using such tools are considered a best practice today. Unfortunately they consume a lot of CPU time and memory. fortrabbit apps are build for fast short running light processes, not heavy lifting. Consider using a third party service for this.

# No video compressing

{#no-video-compressing}

ffmpeg and ffprobe alike are also not available to avoid overuse of resources.

# wkhtmltopdf

{#wkhtmltopdf}

wkhtmltopdf is a popular library to convert HTML to PDF. It's NOT installed and you can not install it on your own for the reasons named above. Check out the following alternatives:

• dompdf is a PHP only PDF by CSS renderer
• Use PDF as a service
• Rethink if you really need PDF?
• Consider PDF creation on the client side with JS in the browser, with jsPDF or similar

# Security responsibilities

{#security-responsibilities}

We believe in a clear division of security concerns. We - fortrabbit - take care of the Operating System level and the PHP runtime, you - the developer - are responsible for the software you write and use.

# Service location

{#service-location}

A data center can be chosen for each app individually, but can't be changed later on. The service is available in Euro (€) or US Dollars ($): This can be chosen with each payment method. The fortrabbit headquarters is based in Berlin, time zone is: CET.

# Mailing

{#mailing}

Many applications and websites need to be able to send emails. The classical example is a password reset form for a CMS. Best use a third party service to achieve this. Here are the options:

# Transactional mail provider

{#transactional-mail-provider}

Recommended: to use a "transactional mail service", those are built to ensure email delivery and will notify you when delivery fails — see transactional mail for more details. These providers are easily integrated via an API and there are plugins for CMS and frameworks.

# Direct SMTP

{#direct-smtp}

Caution: It's possible to use a mail script that uses SMTP (Simple Mail Transfer Protocol) via an email provider directly. There are countless possibilities how to use SMTP. Most frameworks and CMS have configuration options build in.

Although this is the standard approach, for example sending mails via Microsoft Exchange or Google for Work, but we can not recommend it any more. More mail providers are closing down this option.

To use this option anyhow, it's required to manually open the SMTP ports (25, 465, 587) with the outgoing firewall rules.

# No sendmail

{#no-sendmail}

Not available: It's not possible to use sendmail — the Mail Transfer Agent — on fortrabbit. The PHP mail() function uses Sendmail by default. Back in the good ol' days, this would simply call the shell command sendmail to send an email directly from your web server to the receiving email server. This is a bad practice nowadays and will rarely work. Most big email providers will simply ignore emails from unknown servers to avoid spam.

# PHP PATH_INFO

{#php-path-info}

Our runtime implements PHP via FastCGI + FPM. To utilize PATH_INFO you need to do a small hack-around in your .htaccess file:

RewriteCond %{REQUEST_URI} \.php/ [NC]
RewriteRule ^(.+)\.php/(.+)$    /$1.php [NC,L,QSA,E=PATH_INFO:/$2]
apache

# Software support levels

{#software-support-levels}

We take pride in our software knowledge. This document outlines our technical competence levels and the support you can expect.

There are no one-click installers at fortrabbit. Our software guides are mostly about deploying and configuring an existing code base to fortrabbit. Our friendly support chat can help you with all general hosting questions as well as wth general PHP questions. Additionally we are good with certain frameworks and CMS. We have categorized our knowledge in levels.

# A grade support

{#a-grade-support}

We have really solid hands-on experience with this. Ask us anything on Craft CMS, Laravel, Symfony

# B grade support

{#b-grade-support}

We know how to install it here but have no hands-on experience here in-house: WordPress, Statamic, Kirby, Grav, October CMS, ExpressionEngine, Yii2, Drupal …

# C grade support

{#c-grade-support}

You can install this software here. Some clients are using it here already. But we can not give you much specific support: Phalcon, CakePHP, Concrete5, Contao, Joomla!, Magento, ModX, MotoCMS, Neos, PhileCMS, Shopware, Silverstripe, Stacey, TYPO3, Zend, CodeIgniter.

# Live code examples

{#live-code-examples}

Literary copy/paste code examples here. Click on deep links to the dashboard directly from the docs here.

# Code example

{#code-example}

- {{app-name}} - name of the currently selected app.
- {{app-env-name}} - name of currently selected environment.
- {{app-env-id}} - ID of the currently selected environment.
raw

• Logged can use the select on the right to change the values
• Unknown users will see the variables in curly braces {{variable}}

# Deep links

{#deep-links}

• Logged in users see a link
• Unknown users see on info to login to see the link

# How to use

{#how-to-use}

See a select on the left side of docs (desktop version). With that select, the most recently used environment is selected. Change the select to a different environment to show different examples.

# How it works

{#how-it-works}

The login state of the dashboard is stored in a functional cookie, along with a list of environments. It will change appropriate code examples on the current page according to the selected environment. Clearing browser cookie will reset the state.

# Concepts

{#concepts}

Nuts and bolts that make up the fortrabbit hosting platform.

# Direct code access

{#direct-code-access}

Access files, logs and runtime data in your environment directly.

# As alternative to Git deployment

{#as-alternative-to-git-deployment}

We usually recommend to use Git deployment. But not every developer is used to Git yet and it has steep learning curve. Also not all software is ready to be used with Git and Composer. Use rsync, to upload your website.

# SSH

{#ssh}

SSH (Secure Shell) is a network protocol to login to remote web servers. SSH is used in the terminal. It's pre-installed with most operating systems. With SSH you login to have an interactive session on the remote server - the environment in our case. SSH is not suited for transferring files from your computer to the server. See the SSH guide for more details.

# SFTP

{#sftp}

SFTP (Secure File Transfer Protocol) is a network protocol to transfer files to and from web servers. It's build on top of SSH. You will usually use it with a graphical interface. See the SFTP guide.

# SSH key authentication

{#ssh-key-authentication}

To access code by either method, SSH keys are required. Upload your public SSH keys to your personal account with the dashboard. Read more about SSH keys here.

Your code access credentials are stored with your personal account on fortrabbit. This way you always have up-to-date code access on each environment you have access on. It also makes managing the team easy — add/remove collaborators and code access is handled "automagically".

# SSH access

{#ssh-access}

# Get ready

{#get-ready}

• You need to have setup SSH keys to authenticate.
• See the direct code access intro for uses cases and limits.

# Accessing SSH

{#accessing-ssh}

Each environment has it's own SSH access. Execute the following in your terminal to login:

## Connect to your environment via SSH
{#connect-to-your-environment-via-ssh}
$ ssh {{app-env-id}}@ssh.{{region}}.frbit.app
shell

If the login went well, you will see a small welcome message:

–––––––––––––––––––––––  ∙ƒ  –––––––––––––––––––––––
raw

# Executing PHP scripts

{#executing-php-scripts}

If you want to execute PHP scripts, including artisan and it's like, make sure to specify the PHP interpreter explicitly:

## will work
{#will-work}
$ php artisan some:command
$ php some-script.php

## will _not_ work:
{#will-not-work}
$ ./artisan some:command
$ ./some-script.php
shell

# Using Composer

{#using-composer}

Using Git deployment will trigger Composer automatically. Therefore, it should not be necessary to run Composer from the environment. If you still need to run Composer manually on the App, you can. Please think twice before using composer update, because that will bring your local code out of sync which is likely to cause issues. Use composer install instead. Again, running Composer directly on the App is probably not what you want to do.

# Limitations

{#limitations-1}

• This is not a root shell, so you can't install or remove software packages
• Mind that you are using the same runtime as your web application: resource intensive operations will drain memory and CPU from the web execution
• Worker and cron jobs are managed via the dashboard, not the shell

# SFTP access

{#sftp-access}

# Use cases

{#use-cases-1}

SFTP is commonly used by novice developers to upload code. It's not a good practice but get's the job done. We recommend to deploy code via Git or sync using rsync. Sometimes it's a helpful companion tool to look up something quickly.

• Browse files: Check what's actually on the server.
• See logs: Analyze access or error logs.
• Upload assets: If you have large binary files not suitable for Git (though Object Storage is usually better).
• Troubleshooting: Quick fixes or inspecting generated files.

# SFTP access details

{#sftp-access-details}

Host:       ssh.{{region}}.frbit.app
User name:  {{app-env-id}}
Password:   No password required, private SSH used
Protocol:   SFTP (not FTP)
Port:       22
raw

# SFTP clients

{#sftp-clients}

There are various SFTP clients out there. Check our SFTP clients section.

# SFTP is not FTP

{#sftp-is-not-ftp}

SFTP is short for SSH File Transfer Protocol. It is used for uploading and downloading files over a SSH connection. Despite the similar name, SFTP is very different than FTP or FTPS internally, but for most practical purposes they are very similar. SFTP is preferable to FTP because the the transferred data is encrypted and not visible to everyone on the network.

# SFTP command line interface

{#sftp-command-line-interface}

The sftp command line tool is available on most Unix-like systems, including macOS and Linux.

## Connect to your environment via SFTP
{#connect-to-your-environment-via-sftp}
sftp {{app-env-id}}@ssh.{{region}}.frbit.app

## Example: Upload a file
{#example-upload-a-file}
put /path/to/local/file.txt /path/to/remote/file.txt

## Example: Download a file
{#example-download-a-file}
get /path/to/remote/file.txt /path/to/local/file.txt
bash

# Alternatives

{#alternatives}

Consider using more modern alternatives to SFTP, such as:

• Git deployment - advanced code deployment
• SSH - interactive terminal access
• rsync - repeatable file transfer

# Directory structure

{#directory-structure}

When you login with SFTP or SSH to your environment you can see the file directory structure. This is what you'll find:

srv
  data
    www
    home
raw

# www

{#www}

The default web root (aka document root) directory is the main tree 'visible' from the web. You can change the routing root path, to any folder below the htdocs directory. The git deployment syncs to the htdocs folder as well. htdocs is also your 'login folder' - starting point for SSH/SFTP. The whole path looks something like this:

• /srv/data/www

# home

{#home}

Like your ~ on your local machine. Contains bash history, private SSH keys.

• /srv/data/home

# Code access troubleshooting

{#code-access-troubleshooting}

Can't login by SSH or by SFTP or to your database? Most connectivity issues are related to local configuration. Test with SSH first. Here is what to look for.

# Are your SSH keys correctly set up?

{#are-your-ssh-keys-correctly-set-up}

• Have you setup SSH keys and uploaded the public part to fortrabbit?
• Have you been able to access code before?
• Is the same key you are using now here working elsewhere?

See our SSH key setup article if you are unsure about your SSH keys.

# Use verbose mode to see what's going on

{#use-verbose-mode-to-see-what-s-going-on}

Add the -v (verbose) flag to your login command. The output from this command is useful for troubleshooting issues.

$ ssh {{app-env-id}}@ssh.{{region}}.frbit.app -v

## OpenSSH_8.4p1, OpenSSL 1.1.1i  8 Dec 2022
{#openssh-8-4p1-openssl-1-1-1i-8-dec-2022}
## debug1: Reading configuration data /home/user/.ssh/config
{#debug1-reading-configuration-data-home-user-ssh-config}
## debug1: /home/user/.ssh/config line 6: Applying options for *
{#debug1-home-user-ssh-config-line-6-applying-options-for}
## debug1: Reading configuration data /etc/ssh/ssh_config
{#debug1-reading-configuration-data-etc-ssh-ssh-config}
## debug1: Authenticator provider $SSH_SK_PROVIDER did not resolve; disabling
{#debug1-authenticator-provider-ssh-sk-provider-did-not-resolve-disabling}
## … more lines here
{#more-lines-here}
shell

# Check your local SSH configuration

{#check-your-local-ssh-configuration}

Open the files ~/.ssh/config and ~/.ssh/known_hosts and see if there is anything unusual. Delete all entries related to fortrabbit services to reset your local configuration.

# Access error for recently created environment

{#access-error-for-recently-created-environment}

If an environment was recently created, please wait about 5 minutes for it to become ready. Trying to connect before it is ready produces an error. If more than 10 minutes have passed and you still get a similar error (despite successful authentication), then please contact us.

# Access error with recently created SSH key

{#access-error-with-recently-created-ssh-key}

After importing a key in the dashboard, please allow up to 5 minutes for it to be activated.

# You are asked for a password

{#you-are-asked-for-a-password}

If you face a password prompt it can mean a few things:

• Your SSH key is protected by a local passphrase
• The keys in standard location ~/.ssh/ have been rejected
• Other issues on your side, check the verbose output, reset config

# If it takes forever

{#if-it-takes-forever}

If you can't establish a connection at all, or if it takes "forever" to connect and nothing actually happens a few things may be the cause.

• a firewall on your end blocking outgoing connections (not very likely)
• your IP has been quarantined by our service due to too many failed attempts (possible)

Try to figure out if you can connect to external services on port 22 from your network. Try disabling your (corporate) VPN connection, if any.

# Connecting from within a container

{#connecting-from-within-a-container}

When your local development environment is containerized with Docker, DDEV or alike and you want to deploy from within the container, make sure to have the SSH keys installed there as well.

# If it worked before and suddenly stops working

{#if-it-worked-before-and-suddenly-stops-working}

If you have deployed using SSH keys before and now it doesn't work any more:

1. Check if you have changed something, compare your local keys with the remote one
2. See if any change in collaboration happened, do you have access on the app still?

# Host authenticity warning

{#host-authenticity-warning}

The first time you are connecting to fortrabbit service via SSH, there will be a warning about connection to a new SSH server. Just type yes, which will record the fingerprint of the fortrabbit deploy service into the ~/.ssh/known_hosts file. Say yes here:

The authenticity of host '…' can't be established
RSA key fingerprint is …
Are you sure you want to continue connecting (yes/no)?
shell

If this fingerprint changes in the future, then you will se an error about that and will have to take further action depending on the situation.

# Code access overview

{#code-access-overview}

Get direct access on the deployed files on the environment.

# Deployment intro

{#deployment-intro}

Code deployment is a multi-step process to deliver code from your local computer to a web server in a reliable and automated fashion.

In regard of deployment, Git is not only used as a version control system, but also as a transport layer to copy over the latest code changes. A typical code deployment on fortrabbit consists of the following deployment pipeline:

# High level concept

{#high-level-concept}

1 Local   2 Git provider   3 fortrabbit       4 environment
┌─────┐   ┌────────────┐   ┌──────────────┐   ┌──────────────┐
│ Git ├───▶  Git repo  ├───▶  Deployment  ├───▶   web space  │
└─────┘   └────────────┘   └──────────────┘   └──────────────┘
raw

1. You work on your local Git repo
2. You push code changes to the git provider (GitHub), to trigger a deployment
3. The deployment service is runs at fortrabbit
4. The build is getting distributed into the web space of the environment

# Code moves up, content moves down

{#code-moves-up-content-moves-down}

Development is usually happening in the local development environment. Code changes are pushed up.

• Code tracked with git: templates,plugins, themes, CSS, JS …
• Content not tracked: images, uploads, database …
• Runtime data not tracked: logs, sessions, vendor folder, temporary files …

Content updates whoever are often created in the production environment directly, for instance when an editor is adding a new blog post. In many software systems, code and content are separated and do not interfere. A classical PHP project consists of these blocks:

In addition to git deployment, direct code access via SSH and SFTP is also available. This is useful to sync down contents.

# What the storage contains

{#what-the-storage-contains}

The Git repo is not a one to one representation of the storage. After you Git push, first the Git repo will be updated, then changes will be synchronized (overwrite but not delete) to the storage. So the storage contains:

1. The latest Git changes synced in
2. Artifacts from build steps
3. Changes done by direct code access
4. Runtime data like uploads, assets, logs, template fragments …

# Git only syncs up

{#git-only-syncs-up}

Git is a one way street here and the only way is up. You can not pull the changes, which are made via SSH or SFTP, from the storage back into your Git repo. So you can not upload something via SFTP and clone it down later via Git. While this might looks odd at first: this design keeps your Git repo clean of temporary, binary and other blob data. The diagram above visualizes this. Use Git only for code deployment, not to manage all of your Apps runtime data. Separate code - managed in Git - from content - managed via SSH/SFTP.

# Not all applications work well with Git

{#not-all-applications-work-well-with-git}

Git deployment is great when the skeleton has clean folder structure with exclude patterns and Composer support. Laravel and Symfony are poster-child-level for good Git support. WordPress and other CMS are not Git compatible, out-of-the-box. Craft works well with Git and Composer.

# Detailed run down

{#detailed-run-down}

               ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐             ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐

               │                        Deploy service                   │    ─ ─ ─ ▶  │          Environment          │

┌───────────┐  │  ┌──────────────┬────────────┬────────────────────┐   ┌─┴─────────────┴─┐  ┌──────────────────────┐   │
│           │     │              │            │                    │   │                 │  │                      │
│ 1 Queue   │  │  │ 2 Allocation │ 3 Code     │ 4 Build            │   │ 5 Deploy        │  │ 6 Post deploy        │   │
│           │     │              │ sync       │                    │   │                 │  │                      │
│ Waiting   │  │  │ Preparing    │            │ Build commands     │   │ Syncing deploy  │  │ Executing post       │   │
│ for free  │     │ deployment   │ Pull code  │                    │   │ package into    │  │ deploy commands      │
│ slot      │  │  │ containers   │ from git   │ composer install   │   │ web storage     │  │                      │   │
│           │     │              │ repo into  │ pnpm run prod      │   │                 │  │ artisan migrate:all  │
│           │  │  │              │ deploy     │                    │   │ merge           │  │                      │   │
│           │     │              │ container  │                    │   │ …               │  │                      │
│           │  │  │              │            │                    │   │                 │  │                      │   │
│           │     │              │            │                    │   │                 │  │                      │
│           │  │  │              │            │                    │   │                 │  │                      │   │
│           │     │              │            │                    │   │                 │  │                      │
└───────────┘  │  └──────────────┴────────────┴────────────────────┘   └─┬─────────────┬─┘  └──────────────────────┘   │
               └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘             └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
                                       ▲
                                       │
                                       │
                         ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐

                         │          GitHub           │

                         └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
raw

# Deployments and jobs

{#deployments-and-jobs}

After each deployment all running jobs (workers and crons) will be restarted to make sure they'll be using the latest code.

# The fortrabbit GitHub App

{#the-fortrabbit-github-app}

Connect the most popular Git-as-a-service provider with your fortrabbit. Login with GitHub and use automatic git push to deploy.

# Get ready

{#get-ready-1}

• You are confident using Git.
• You also have a good understanding of the fortrabbit deployment options.
• Finally, you have an account here at fortrabbit as well as with GitHub already.

# Installation

{#installation}

To connect GitHub with fortrabbit you need to install the fortrabbit GitHub App with your account at GitHub:

• github.com/apps/fortrabbit

You can do this when signing up to fortrabbit by choosing GitHub or later with the account settings.

You will be prompted to give it access on your repos as well as to create repos on your behalf. You will also need to choose which context at GitHub you will want to give it access.

# Connect, create or change a repo

{#connect-create-or-change-a-repo}

The Git repo maps to the app at fortrabbit. When creating an app you will be asked to either choose a repo from GitHub to be connected to the app or to create a new empty repo for the app. Later on you can change the repo of the app.

# Connect, create or change a branch

{#connect-create-or-change-a-branch}

The Git branch maps to the environment at fortrabbit. You can create environments for your branches.

# Repos from organizations at GitHub

{#repos-from-organizations-at-github}

You can choose repositories from organizations on GitHub if you have any, and you have given the fortrabbit GitHub app access to them.

# Only matching fortrabbit accounts can deploy

{#only-matching-fortrabbit-accounts-can-deploy}

Automatic deployment is limited to people who have an account at GitHub as well as on fortrabbit and the fortrabbit GitHub app installed. This is a security feature.

# GitHub Actions

{#github-actions}

GitHub is also offering Github Actions, an integrated continuous integration solution. You can use GitHub Actions in combination with our git deployment or with our direct code access as an alternative workflow to deploy. GitHub Actions give you more control control over the deployment pipeline.

# Removing access

{#removing-access}

You can at any time uninstall the fortrabbit GitHub app from your GitHub account. This will break deployments. When deleting an app from fortrabbit, the connection over at GitHub will also be removed. Cancelling fortrabbit services will not automatically uninstall the fortrabbit GitHub app.

# Build commands

{#build-commands-1}

# Get ready

{#get-ready-2}

• Follow the deployment section.
• Be ready to deploy code by git via the GitHub integration.

# How build commands work

{#how-build-commands-work}

Build commands are a list of commands that will get executed after the fortrabbit GitHub app has received the latest updates from Git and before those are getting deployed into the web space of the environment. The Git updates, together with the results from the build steps are forming the build package to be released with a deployment.

# Automatic configuration

{#automatic-configuration}

When setting up an app or environment, the fortrabbit GitHub app will use the stack detector to detect and autoconfigure all deployment settings, including build commands. Predefined software templates and detection are combined. The most basic auto detected build commands are:

• When composer.json file is detected, composer install will run.
• When package.json is discovered npm run prod will run.

# Manually editing build commands

{#manually-editing-build-commands}

Build commands can be found with the git deployment settings in the fortrabbit dashboard. Define them for each environment.

# Composer

{#composer}

Most PHP development is done with the help of frameworks or content management systems. These are usually installed as a dependency and themselves using other dependencies. All that code is not part of Git, so when the code get's delivered, those dependencies need to be installed or updated for the given environment. Find more details with our Composer article.

# Node.js

{#node-js}

Most web development is done with the help of JavaScript build tooling. Specific production build steps create optimized build bundles to be served to clients from the web application.

# Post deploy commands

{#post-deploy-commands}

Run tasks such as migrations and cache clearing after deployment.

# Get ready

{#get-ready-3}

You have followed the deployment section and are ready to deploy code via git using the GitHub integration.

# Architecture

{#architecture}

Post deploy commands are similar to build commands, but they run after the build files have been copied into the live environment. Both build commands and post deploy commands are run in a separate deployment container.

# Use cases

{#use-cases-2}

• Database migrations: Apply schema changes after code deployment
• Cache clearing: Refresh application caches to reflect new code
• Configuration updates: Apply environment-specific settings
• Search index rebuilding: Update search indexes with new content structure

# Relation to deployments

{#relation-to-deployments}

Post deploy commands are done as part of the deployment object. This means that a deployment might show as failed, but new files were already deployed, if the failure happened in the post deploy commands.

# Setting up post deploy commands

{#setting-up-post-deploy-commands}

Post deploy commands are configured in the fortrabbit dashboard for each environment. You can access these settings through the deployment configuration:

# Preset via software templates

{#preset-via-software-templates}

Many software presets, such as those for Laravel, Symfony and Craft CMS, already include pre-configured post deploy commands.

# Examples

{#examples}

## Laravel
{#laravel}
php artisan migrate --force
php artisan config:cache
php artisan route:cache

## Craft CMS
{#craft-cms}
php craft project-config/apply
php craft clear-caches/all

## Symfony
{#symfony}
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console cache:clear --env=prod
bash

# Limits

{#limits}

Post deploy commands are run in a separate deploy resource, which is separate from frontend web delivery resources. The deploy resources are still limited by your booked PHP plan.

# Timing and execution

{#timing-and-execution}

Post deploy commands run after the deployment has been marked as successful. This means:

• If a post deploy command fails, deployment is shown as failed, but new files have already been copied
• Commands execute in sequence, not parallel
• Each command must complete before the next one starts
• Total execution time should be kept reasonable to avoid timeouts

# Best practices

{#best-practices}

• Cache management: Consider the impact before clearing all caches every time, especially in production. Cache clearing not only consumes resources, but cache rebuilding can also significantly slow performance.
• Error handling: Design your commands to be idempotent (safe to run multiple times) and handle errors gracefully.
• Monitoring: Log important post deploy actions so you can troubleshoot issues later.
• Performance: Keep commands lightweight and avoid long-running processes that might timeout.

# Deployment trigger

{#deployment-trigger}

This settings define how deployment happens from GitHub to the environment.

# Push to deploy

{#push-to-deploy}

This is the default trigger. Deployment happens automatically on every push to the branch that is connected to the environment.

# Manual deployment

{#manual-deployment}

When manual deployment is selected, no automatic deployments will happen. Initiate a deployment from the dashboard.

# Deploy now button

{#deploy-now-button}

Trigger a new deployment for an environment, based on the latest commit. You will find a 'deploy now button' with the deployment settings of the environment and with the deployment that is based on the latest commit. This will use the latest commit as the source and apply all deployment related settings.

The deploy now action is shown with both deployment trigger settings. Deploying a commit again can be useful when a setting related to deployment has changed. To avoid inconstant states, it is not allowed to deploy an older commit again.

# Cached directories

{#cached-directories}

This settings controls whether and which folder are cached for deployment. This will speed deployment from the second time you deploy.

# How it works

{#how-it-works-1}

During most deployments the build commands will include something like composer install or npm install. These processes will download dependencies and populate the vendor and the node_modules folders. The cached directories defines folder to be preserved and re-used without downloading all dependencies with each deployment. Thus first deployment may take a couple of minutes, but successive deployments will be much faster.

Note that this is a setting that happens on the deploy service, not on the environment, see the deployment intro.

# Default settings

{#default-settings}

vendor
node_modules
plain

In most cases the default setting is what you want. To disable cached directories, save an empty value.

# Purging cached directories

{#purging-cached-directories}

It can be helpful to purge the cached directories. Purging the cached directories, as the title suggests, will delete all files and folders, so next time during deployment a new cache will be created.

There is a button with the dashboard to purge the cache. Saving the cached directories will also purge the cache.

# Deployment strategy

{#deployment-strategy}

This setting defines how the deployment result will be distributed to the web space of an environment.

The result of the changes received by git push and the build steps execution is called a deploy package - a temporary file set. This will be put into the storage of the environment somehow. You can change the deployment synchronization strategy setting with the dashboard. The strategy matches with the software and deployment flows to be used. With the software template defaults for the deployment strategy are set.

# Blend strategy

{#blend-strategy}

The save strategy for deployment package synchronization is overwrite but not delete:

• Newer files will replace older files on the storage
• New files will be created on the storage
• Files not present in the deploy package but on the storage will not be touched

With this no runtime data, like uploads, transforms, caches template fragments and other content will get deleted. It however can result in some weird edge case side effects. When blend strategy is enabled, patterns to replace certain files and folders can be defined.

# Replace strategy

{#replace-strategy}

Create an exact replica of the current deploy package within the web space. That means, all files in the web space will be deleted first and replaced by the contents of the deploy package. This is sometimes called an immutable deployment. It's related to 12-factor design and ephemeral storage where the web application should not write anything to disk. It allows to rollback to any previous state more easily. This may not play well with old school PHP based web applications.

In addition to the full replace strategy you can set certain excluded files and folders that will be sustained from replacement.

# Git source directory

{#git-source-directory}

The Git source directory is a dashboard settings for environments that have git deployment enabled. Define which folder with the Git repo should be deployed. In most cases the root path of the repo will work fine. Leave the field empty for that.

# Use cases

{#use-cases-3}

The most common use case is when you have a mono repo that holds multiple websites on one Git repo. For this scenario you can choose to deploy only a sub folder of the root directory, for instance /apps/website-1.

# Exclude patterns

{#exclude-patterns}

A setting to define files and folders not be replaced during deployment with replace strategy.

This is essential to preserve user uploads, assets, and other user-generated content. This setting is only available when the deployment strategy is set to 'replace'. Note that with the replace strategy, all files from the deployment build will replace the content of the actual web storage. Generally, you want to exclude runtime data (files and folder created by the website not with git). Usually this about user uploads, logs, sessions.

Sensible defaults based on software templates are provided.

Rsync syntax is supported, allowing regex like patterns. The asterisk * serves as a wildcard.

# Examples

{#examples-1}

### WordPress
{#wordpress}
/wp-content

### Laravel
{#laravel-1}
/storage

### Kirby CMS (if using git + rsync)
{#kirby-cms-if-using-git-rsync}
/content
/media

### Wildcard (rsync regex) syntax
{#wildcard-rsync-regex-syntax}
*/files

### Exclude things to show up in final build
{#exclude-things-to-show-up-in-final-build}
/node_modules
yml

# One setting, two use cases

{#one-setting-two-use-cases}

• Exclude from deployment: Prevent files from being copied to the environment.
  • Useful for files that are only needed during deployment.
  • node_modules are often excluded to keep the runtime clean.
• Preserve on environment: Prevent files from being overwritten or deleted.
  • Essential for runtime data created by the application.
  • Example: User uploads, content files, and logs.

# Related

{#related}

When the deployment strategy is set to blend, there is an opposite setting to define replace patterns.

# Replace patterns

{#replace-patterns}

A setting to define files and folders to be replaced during deployment with blend strategy.

This is essential to avoid old files cluttering the system and confusing the software. This setting is only available when the deployment strategy is set to 'merge'. Note that with the blend strategy, all files from the deployment build will synced into the content of the actual web storage. No old files will be deleted.

For certain folders, it's better to delete their content.

Sensible defaults based on software templates are provided. Rsync syntax is supported.

Rsync syntax is supported, allowing regex like patterns. The asterisk * serves as a wildcard.

# Examples

{#examples-2}

### Craft CMS
{#craft-cms-1}
/config/project

### Pattern to replace all JPGs
{#pattern-to-replace-all-jpgs}
*.jpg
yml

# Related

{#related-1}

When the deployment strategy is set to replace, there is an opposite setting to define exclude patterns.

# Deploy logs

{#deploy-logs}

Use deployment logs to understand why a deployment failed.

# Availability

{#availability}

• Deploy logs are available in the Dashboard; each deployment has its own log.
• Deploy logs appear shortly after the deployment ends.
• Deploy logs are only kept for 14 days after the deployment has finished.

# Common issues for failed deployments

{#common-issues-for-failed-deployments}

It's possible, but not very likely, that failed deployments are caused by a service issue. In most cases they are related to problems in your code and config — likely the with build commands or post deploy commands.

It's also completely normal to see failing deployments while you are still setting things up.

# Build command errors

{#build-command-errors}

If the deployment is marked as failed and deploy log shows errors and no new code is deployed, most likely the build steps have failed. Read the error message carefully to understand what went wrong. Sometimes build commands are pre-configured by software templates. In some cases these defaults don't match your project and need adjustment.

# Composer errors

{#composer-errors}

Composer errors are usually caused by configuration issues in your project. Check your composer.json (and lock file) for:

• Invalid or conflicting version constraints
• Missing PHP extensions
• Repositories or packages that are no longer available

# Node.js errors

{#node-js-errors}

Node task errors when running npm run prod or similar scripts are also common.

• Are all Node dependencies installed?
• Is the task defined in your package.json?
• Does the task succeed in your local development environment?

# Post deploy command errors

{#post-deploy-command-errors}

If the deployment is marked as succeeded, but the log shows errors and the code is actually deployed, the problem is most likely with the post deploy commands. These run after the deployment and can fail even though the new code is already live.

# How to fix failing deployments

{#how-to-fix-failing-deployments}

Use the deploy logs to see where the process breaks and what the error message is. Many issues can be resolved just by carefully reading and following the hints from the log.

A frequent problem is a mismatch between local and remote environments: on fortrabbit the environment is usually set to production, while locally you might still be running a development build. Try running your production build locally (for example npm run build or composer install --no-dev) and fix any issues you see there first.

# Contacting support

{#contacting-support}

We're happy to help you figure out why your deployment fails. When you contact support, please include:

• Details about your project and environment
• What you changed before deploying
• The time of the failing deployment
• The specific error message or relevant excerpt from the deploy log

# Deployment troubleshooting

{#deployment-troubleshooting}

Can not deploy by Git? Let's start from scratch to make sure we don't miss anything.

# Get ready

{#get-ready-4}

Before starting to troubleshoot deployment issues, specifically if you are setting up things for the first time, make sure to have everything configured correctly:

• New to Git? Read the git intro first
• Read the deployment intro
• Have the fortrabbit GitHub app installed with GitHub
• Have an environment connected to a repo at GitHub

# GitHub connectivity errors

{#github-connectivity-errors}

You can NOT push to GitHub? You may see an error in the command line when trying to push or no changes arrive with the repo at GitHub.

• GitHub: Troubleshooting SSH
• GitHub: Troubleshooting connectivity problems

# Transit errors

{#transit-errors}

You can push to GitHub, the new deployment does not arrive with fortrabbit environment. There is no deployment at fortrabbit.

• Do you have an account at fortrabbit and one on GitHub?
• Make sure to have the fortrabbit GitHub App installed and connected
• Are you deploying to the branch that is connected?
• How did you set up automatic deployment with fortrabbit?

# Deployment errors

{#deployment-errors}

Everything above is set up correctly, there are deployments with fortrabbit, but they fail.

• Check the deploy logs to see the error

# title: Deployment overview naviTitle: Deployment navigation: false

# Using ENV vars on fortrabbit

{#using-env-vars-on-fortrabbit}

Manage environment variables with the fortrabbit dashboard.

The input supports the dotenv file format and allows you to create or update multiple variables at once. The changes will be distributed after you save the page. That may take around 60 seconds.

# ENV var types on fortrabbit

{#env-var-types-on-fortrabbit}

There are four different kinds of ENV vars here on fortrabbit which are available to your environment at runtime.

# Software template ENV vars

{#software-template-env-vars}

Depending on the detected or chosen software, additional ENV vars will be seeded for you. This selection will configure the server ENV vars in ways, the software can work with it. For example, for Laravel and Craft, an ENV var like DB_PASSWORD will be populated with the password of the database. So, most likely, your fortrabbit environment will work out of the box. As a bonus you even reset the database password without touching any configurations.

# System ENV vars

{#system-env-vars}

System ENV vars are automatically updated values that contain access details for services offered by fortrabbit. For example:

MY_MYSQL=${FORTRABBIT_MYSQL_PASSWORD}
## MY_SQL is the key
{#my-sql-is-the-key}
## ${FORTRABBIT_MYSQL_PASSWORD} is an alias for a value populated by fortrabbit
{#fortrabbit-mysql-password-is-an-alias-for-a-value-populated-by-fortrabbit}
apache

System ENV vars will not overwrite existing, manually created ENV vars. This means: if you manually create an ENV var, we guarantee that we won't replace it's value by a dynamically generated ENV var.

# Custom ENV vars

{#custom-env-vars}

Those are the ones you add yourself in the dashboard.

# Nested ENV vars

{#nested-env-vars}

You can use simple, nested variables in your custom ENV vars. Simple means, that you can set variables which reference other variables, which contain a value, for example:

## will work:
{#will-work-1}
OTHER_VAR=something
MY_VAR=${OTHER_VAR}
apache

Order matters. First define something before referencing. Multiple levels of interpolation are not supported. That means that you cannot use variables, which reference other variables, which again reference other variables, for example:

## will not work:
{#will-not-work-1}
MY_VAR=${OTHER_VAR}
OTHER_VAR=${ANOTHER_VAR}
ANOTHER_VAR=something
apache

# ENV var validation

{#env-var-validation}

Strict validation rules for ENV vars are in use in the dashboard while entering. Chars like the "$" sign can be harmful in Linux systems. Here is the regex we use to validate the ENV var input in the dashboard:

/^[\p{L}\p{N}\ _\-\+=\.,:;\?!@~%&\*\(\)\[\]\{\}<>\/\\#]+$/u
raw

So sometimes, when you want to store an external API key as an ENV var, you might get a validation error like: "Variable value contains invalid characters".

# Base64 encoding and decoding

{#base64-encoding-and-decoding}

Use the Base64 helper in the dashboard to handle special characters, multi-line values, or long strings.

## Can NOT save this due to special characters
{#can-not-save-this-due-to-special-characters}
MOTTO=$$$$ Rules Everything Around Me

## The tool converts it to Base64 with a prefix
{#the-tool-converts-it-to-base64-with-a-prefix}
MOTTO=fr+base64:JCQkJCBSdWxlcyBFdmVyeXRoaW5nIEFyb3VuZCBNZQ==

## The environment receives the original value
{#the-environment-receives-the-original-value}
MOTTO=$$$$ Rules Everything Around Me
shell

The tool encodes your value to Base64 and adds the fr+base64: prefix. This encoded value is stored safely. At runtime, the platform automatically decodes it, so your application receives the original value without any extra work.

Laravel and Symfony have similar built-in functionality for variables prefixed with base64:. If you use that, the framework handles the decoding. The fr+base64: prefix is a platform-level feature that works for any application, regardless of the framework.

# Reserved environment variable names

{#reserved-environment-variable-names}

There are some names you can not use here:

, __FRBIT__, argc, argv, AUTHTYPE, CHARSET, CONTEXT_DOCUMENT_ROOT, CONTEXT_PREFIX, DOCUMENT_ROOT, FCGI_ROLE, FORTRABBIT, GATEWAYINTERFACE, GROUP, HOME, HTTP_, HTTPS, LANG, LC__, LOGNAME, MAIL, MUSL_LOCPATH, OLDPWD, ORIG_PATH_INFO, PAGER, PATH, PATH_INFO, PATH_TRANSLATED, PHP_AUTH_DIGEST, PHP_AUTH_PW, PHP_AUTH_USER, PHP_SELF, PS0, PS1, PS2, PS3, PS4, PWD, QUERY_STRING, REDIRECT_REMOTE_USER, REMOTE_ADDR, REMOTE_HOST, REMOTE_PORT, REMOTE_USER, REQUEST_METHOD, REQUEST_SCHEME, REQUEST_TIME, REQUEST_TIME_FLOAT, REQUEST_URI, SCRIPT_FILENAME, SCRIPT_NAME, SCRIPT_URI, SCRIPT_URL, SERVER_ADDR, SERVER_ADMIN, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, SERVER_SIGNATURE, SERVER_SOFTWARE, SHELL, SHLVL, SSH_CLIENT, SSH_CONNECTION, SSH_TTY, TERM, USER

# Password protection

{#password-protection}

Control public access to your environment with HTTP Basic Authentication for staging and development workflows.

When enabled, visitors must enter a username and password before accessing any page on your website. It applies to all domains routed to the environment.

# Use cases

{#use-cases-4}

• Staging environments: Protect environments from public access while allowing stakeholders and team members to review content before going live.
• Development workflows: Restrict access during development to prevent search engine indexing and public access to work-in-progress features.
• Client previews: Share protected environments with clients for review without public access.
• Content preparation: Protect environments during content updates, data imports, or major changes.

# Configuration

{#configuration}

• Enable/disable: Toggle protection without losing configured credentials.
• Username and password: Set custom credentials independent of your fortrabbit account.

Each environment has its own password protection settings, allowing different access controls across environments.

# How it works

{#how-it-works-2}

Password protection uses HTTP Basic Authentication (HTTP-auth) to restrict public access via HTTP to your environment. it:

• Shows a browser authentication dialog to visitors
• Persists authentication for the browser session
• Protects all pages, assets, and API endpoints
• Prevents search engine indexing

# Considerations

{#considerations}

• Security level: Provides basic access control suitable for preventing casual access, not high-security protection.
• SEO impact: Password-protected environments are not indexed by search engines.
• Team access: Share credentials securely with team members and stakeholders.
• Production use: Consider user experience impact before enabling on live websites.

# Technical details

{#technical-details}

Password protection is implemented at the web server level before your application code executes, ensuring consistent protection across all content. The authentication header is available to your application for additional logic if needed.

# Alternatives

{#alternatives-1}

Username/password can also be configured through .htaccess instead of the dashboard setting. Some software systems also offer settings or plugins for that.

# Routing options

{#routing-options}

How to configure public HTTP access for environments.

# Test domain

{#test-domain}

Each environment has a unique public test domain assigned that is constructed like {{app-env-id}}.frbit.app. Use it during development, testing or multi staging. Look up the actual name for your test domain with the dashboard under the environment overview.

# External domains

{#external-domains}

You can register your environment to accept requests from any external custom domain you route to fortrabbit — see also the domain article. To set up a domain routing, you add a new custom domain within your App's domain settings in the dashboard.

# Main domain

{#main-domain}

Each environment has a main domain. It is exposed as a routing setting with the environment of the dashboard. The thumbnail preview shown with the dashboard uses the main domain as the source. It's also used for internal monitoring services. There is also a dynamic ENV var that maps to the currently configured value.

# PHP settings

{#php-settings}

Environments ship with an opinionated (think optimized) pre-configuration of PHP settings. Those also depend on the software template. The dashboard exposes the most important settings to configure the PHP version and certain PHP extensions.

# Available settings

{#available-settings}

• PHP version
• PHP extensions
• PHP ini settings
  • post_max_size
  • max_input_size
  • output_buffering
  • max_execution_time ← Keep it low. Why?
  • upload_execution_filesize

# See all specific settings

{#see-all-specific-settings}

Use phpinfo to dump all the PHP settings.

# Add additional settings

{#add-additional-settings}

Use user.ini for more fine grained control over PHP settings.

# Root path

{#root-path}

The root path refers to the directory that serves as the entry point for public requests from the world wide web.

Per default all the domains of the environment will route to the same root path (sometimes this is also called: document root, docroot or root folder): htdocs. This path is where the first index.php will be called, when people are visiting your App on any domain. This path setting can vary, depending on what the framework or CMS you have selected in the software chooser when creating the app.

You can however set the root path afterwards at any given time by tinkering with .htaccess to enable per domain routing.

# Plain default

{#plain-default}

In a typical old school PHP project, the root path is on top level and contains the index.php file, which is the default script to be executed.

www <-- Root path
├── index.php  <-- file to be called
├── css/
├── js/
├── images/
├── includes/
raw

• index.php: Main entry point
• includes/: PHP scripts included

# Modern root path settings

{#modern-root-path-settings}

For a better file structure and increased security, it is recommended to keep most PHP files outside the publicly accessible directory and use a folder as the document root:

www
├── public/ <-- Root path
│   └── index.php <-- file to be called
├── src/
├── vendor/
└── composer.json
raw

• public/: Public-facing files
• src/: PHP source code
• vendor/: Composer dependencies

By configuring the public/ directory, you prevent direct web access to sensitive files in src/ and vendor/. This pattern is standard for all modern PHP frameworks and CMS:

• public - Laravel, Statamic, October CMS …
• web - Craft CMS …

# Root path setting on fortrabbit

{#root-path-setting-on-fortrabbit}

On fortrabbit you can set the root path for each environment with the routing settings in the dashboard. When choosing a software template the correct root path will pre-configured.

# Incoming firewall (WAF)

{#incoming-firewall-waf}

Bots and crawlers scan your website for vulnerabilities and content. Keep out the bad actors.

Even unsuccessful requests do harm by consuming hosting resources and spamming logs. This can be bad for performance and consumes unnecessary energy. Specifically AI bots that ignore robots.txt can hammer websites considerably.

# Implementation

{#implementation}

The current incoming firewall implementation is a 'poor mans WAF'. nG Firewall by Perishable Press is used. It blocks out bad requests and most bad bots on the web server level by using a standard set of .htaccess rules.

# Usage

{#usage}

We provide an easy to use interface to turn on/off a WAF. Visit the PHP settings of the environment to enable or disable the setting.

# Quirks

{#quirks}

Bots are a major problem. The current solution provided is in testing while we are also exploring alternative approaches.

# Possible performance impacts

{#possible-performance-impacts}

We are testing performance impacts. While this keeps the Apache more busy with each request, fewer requests will reach the PHP engine.

# Chicken egg problems

{#chicken-egg-problems}

The firewall should only be activated after a software has been installed. An active WAF setting may prevent software to be installed.

# Alternatives

{#alternatives-2}

There are plenty of alternatives to using the WAF setting.

# Create your own .htaccess

{#create-your-own-htaccess}

There are rules which may be specific to your use case but which are not necessarily required for everyone. Use an .htaccess file to write your own rules. See our htaccess section for more.

# Use an external service

{#use-an-external-service}

Some DNS infrastructure providers offer 'bot control' services where bad traffic will be filtered before it even reaches the web server.

• Cloudflare bot management
• AWS WAF Bot control

# Outgoing firewall

{#outgoing-firewall}

By default, outgoing (egress) traffic is limited on most non-standard ports for security reasons. Open ports from the dashboard to make outgoing calls from the app environment.

Open ports with environment settings in the dashboard. Outgoing firewall rules are environment specific.

# Outgoing IPs

{#outgoing-ips}

The outgoing firewall settings also show the outgoing IP for the environment.

# Logs

{#logs}

Analyzing logs is an important part of maintaining a stable and secure website. Error logs often help to identify bugs and other issues. Here is how on fortrabbit.

# Tailing logs

{#tailing-logs}

1. Login by SSH to the environment
2. Run frbit-tail-logs to see live log streaming

This will provide you a stream of logs.

# Log files in your CMS or framework

{#log-files-in-your-cms-or-framework}

Mind that your CMS or framework might pipe logs to a different location, other than stderr and stdout. If they do, you will not see the error output in the fortrabbit dashboard. You can still access the logs by SSH or SFTP, please see your CMS / framework docs where the logs are stored.

Most CMS and frameworks also offer options to send these logs to the standard locations. With the software template the setting is getting pre-populated, if possible, by ENV var.

• Craft CMS logging
• Laravel logging

# Verbose logging

{#verbose-logging}

Your CMS / framework might offer verbose logging, often this is connected to environment settings of the CMS / framework. Often more debugging information is printed with the error and sometimes errors are even send to the browser. Use that with care, since it can have a considerable performance impact. The general advice is to use it for development and staging environments, but not for production. If you happen to have an issue in production that requires verbose logging, turn it off, after you have finished.

# Metrics

{#metrics}

Working with metrics in the dashboard.

# Usage metrics

{#usage-metrics}

Those show you the current status of the storage, MySQL storage in context.

# Performance metrics

{#performance-metrics}

Those show you how fast your App is and where you might need to improve. Performance metrics are: requests, PHP response time, traffic, errors and other useful stuff. You can set different time intervals to monitor performance over time.

# Hosting settings

{#hosting-settings}

These hosting settings are all exposed through the dashboard, individually for each environment.

# Database access intro

{#database-access-intro}

# Get ready

{#get-ready-5}

To connect to the remote MySQL database, it first need to be booked. The MySQL component is optional but pre-booked for database driven software systems.

To be able to connect to the remote database from your computer, also a local development environment with mysql and mysqldump is required for terminal usage. A database GUI such as Workbench or Sequel Ace is another option. Different local development environments come with different paradigms for working with a database. For containerized systems, the database service might not be directly exposed.

# Next steps

{#next-steps}

• Connect from within the environment
• Database access via terminal from local
  • Database up via terminal
  • Database down via terminal
• Database access via GUI from local
  • Database up via GUI
  • Database down via GUI

# Dashboard settings

{#dashboard-settings}

# Database access via terminal

{#database-access-via-terminal}

Connect to the remote database hosted on fortrabbit from your local machine by terminal commands.

The following commands are run on your local computer. The mysql command line client is required. Exact commands may differ depending on the kind of local development environment.

## 1. Create a tunnel in a dedicated terminal window
{#1-create-a-tunnel-in-a-dedicated-terminal-window}
ssh -N -L 13306:mysql:3306 {{app-env-id}}@ssh.{{region}}.frbit.app
## This will have no output. That's Ok. Open a new window
{#this-will-have-no-output-that-s-ok-open-a-new-window}
shell

## 2. In a new window connect to the database
{#2-in-a-new-window-connect-to-the-database}
$ mysql -u {{app-env-id}} -h127.0.0.1 -P13306 -p -D {{app-env-id}}
## In the next step you will be asked for your MySQL password.
{#in-the-next-step-you-will-be-asked-for-your-mysql-password}
shell

# Next

{#next}

• Database upload via terminal
• Database download via terminal

# Port setting

{#port-setting}

Port local 13306 is just an example, any port in the range 1025-65535 can be used. The remote port 3306 must be 3306. This command is not supposed to print a confirmation message. If nothing shows up: you did it right!

# Troubleshooting

{#troubleshooting}

• The most common issue is to expect output with the tunnel command. No response is good. Open a new terminal window and continue.
• The second most common issue is to expect output with the tunnel command. No response is good. Open a new terminal window and continue.
• The third most common issue is to expect output with the tunnel command. No response is good. Open a new terminal window and continue.
• It's 127.0.0.1 not localhost.

# Database access via GUI

{#database-access-via-gui}

Connect to the remote database hosted on fortrabbit from your local machine using a GUI.

Using a database graphical user interface has many benefits: Visually browse and edit the database, get hints running queries, save connection details as bookmarks. It's also practical to have the client connect to the remote and to the local database. See our database integration section with specific guides for Sequel Ace, Workbench and others.

# General instructions

{#general-instructions}

fortrabbit requires database connections via SSH tunnel. All MySQL clients support this configuration, typically through a dedicated SSH tunnel tab.

• SSH part
  • SSH Host: ssh.{{region}}.frbit.app
  • SSH User: {{app-env-id}}
  • SSH Keyfile: Your local SSH private key
• MySQL part
  • MySQL Host: mysql
  • MySQL Server Port: 3306
  • Username: {{app-env-id}}
  • Password: Look it up in the dashboard
  • Default Schema: {{app-env-id}}

# Next steps

{#next-steps-1}

• Database up via GUI
• Database down via GUI

# Troubleshooting

{#troubleshooting-1}

The most common issues setting up the remote connection via database GUI are:

• Using no tunnel. Connect via SSH tunnel.
• Using localhost. Hostname is mysql.

# Database access from within the environment

{#database-access-from-within-the-environment}

How to configure code to connect to the database on fortrabbit.

# Automatic software configuration

{#automatic-software-configuration}

We recommend ENV var configuration. Thanks to software templates ENV vars for connecting to the database are automatically mapped. Software like Laravel, Symfony, Craft CMS or Statamic will connect to the database without additional configuration.

// Generic example for illustration purposes
$pdo = new \PDO(
  'mysql:host='. getenv('MYSQL_HOST'). ';dbname='. getenv('FORTRABBIT_DATABASE'),
  getenv('DATABASE_USER'),
  getenv('DATABASE_PASSWORD'),
);
$pdo->query("SELECT * FROM ...")
php

Environment variables for database connections that are automatically mapped to specific keys for various software systems:

• FORTRABBIT_DATABASE
• FORTRABBIT_DATABASE_USER
• FORTRABBIT_DATABASE_PASSWORD
• FORTRABBIT_DATABASE_HOST
• FORTRABBIT_DATABASE_PORT

# Manual software configuration

{#manual-software-configuration}

WordPress, for example, does not support ENV configuration. You will need to enter the database credentials during the install process or with the configuration files. Please look up the database credentials, such as database name, user and password with the dashboard.

# Connecting via SSH session

{#connecting-via-ssh-session}

The command-line tools mysql and mysqldump are available via SSH. When you are logged just type mysql to login to the MySQL server.

# MySQL access

{#mysql-access}

All the ways to connect to the remote database.

# Database export/import

{#database-export-import}

Options to upload a database from local to remote and downloading a database from remote to local.

# Get ready

{#get-ready-6}

Database import/export is a crucial task. Sync the state of a remote environment with a local environment. For that it requires:

• Have a local development environment running.
• Be able to access the remote fortrabbit database.

MySQL doesn't support incremental updates, so you'll always export the complete database structure and contents. This involves creating a dump.sql file from the source database and importing it to the destination database. The process works in both directions:

• Upload: Export from local and import to fortrabbit
• Download: Export from fortrabbit and import to local

During initial setup, you'll typically import your local database to fortrabbit at least once. Later, as content is added with the production environment, sync changes back to the local environment periodically.

Using mysqldump and mysql is the standard approach to migrate data between MySQL servers from the command line.

# Next

{#next-1}

Depending on your local development environment setup and preferences, certain commands may differ.

• Database access via terminal from local
  • Database up via terminal
  • Database down via terminal
• Database access via GUI from local
  • Database up via GUI
  • Database down via GUI

# Database up via terminal

{#database-up-via-terminal}

• Database access intro
• Database export/import intro
• How to connect to the remote database via terminal

The following commands are run in your local development environment. mysql and mysqldump are required.

## Terminal 1
{#terminal-1}
## Export database from your local machine
{#export-database-from-your-local-machine}
$ mysqldump --set-gtid-purged=OFF -u{{local-db-user}} -p {{local-db-name}} > dump.sql
## You'll be prompted for your local database password
{#you-ll-be-prompted-for-your-local-database-password}

## Open the SSH tunnel
{#open-the-ssh-tunnel}
ssh -N -L 13306:mysql:3306 {{app-env-id}}@ssh.{{region}}.frbit.app
## No output. Open a new terminal window!
{#no-output-open-a-new-terminal-window}
shell

## Terminal 2 (new window)
{#terminal-2-new-window}
## Import Database
{#import-database}
mysql -h127.0.0.1 -P13306 -u{{app-env-id}} -p {{app-env-id}} < dump.sql
## You'll be prompted for your MySQL password (found in the dashboard).
{#you-ll-be-prompted-for-your-mysql-password-found-in-the-dashboard}
## The `dump.sql` file is from the first step.
{#the-dump-sql-file-is-from-the-first-step}
## Can take a while, depends on size.
{#can-take-a-while-depends-on-size}
shell

# Development environments

{#development-environments}

Local developments based on containers may require some extra steps, like logging in to the MySQL container or executing commands on the container.

• Docker
  • docker exec -i {container} … - execute a command
• DDEV
  • ddev export-db > dump.sql command to export a database
  • ddev auth - login to the container (first)
  • ddev exec … - execute a command

# Database down via terminal

{#database-down-via-terminal}

• Database access intro
• See database export/import intro
• How to connect to the remote database via terminal

## Terminal window 1
{#terminal-window-1}
ssh -N -L 13306:mysql:3306 {{app-env-id}}@ssh.{{region}}.frbit.app
## This has no output. Open a new terminal window next.
{#this-has-no-output-open-a-new-terminal-window-next}
shell

## Terminal window 2
{#terminal-window-2}
## 01. Create a dump from the remote database
{#01-create-a-dump-from-the-remote-database}
mysqldump --set-gtid-purged=OFF --no-tablespaces -h127.0.0.1 -P13306 -u{{app-env-id}} -p {{app-env-id}} > fortrabbit-backup.sql

## 02. Import to your local database
{#02-import-to-your-local-database}
mysql -u{{local-db-user}} -p {{local-db-name}} < fortrabbit-backup.sql
shell

# Other development environments

{#other-development-environments}

Steps may differ on containerized development environments. It might be required to login to a container or specifically execute a command on the container.

• Docker
  • docker exec -i {container} … - execute a command
• DDEV
  • ddev import-db < dump.sql - import a database from host
  • ddev auth - login to the container (first)
  • ddev exec … - execute a command

# MySQL database upload from local to remote by GUI

{#mysql-database-upload-from-local-to-remote-by-gui}

Upload a local database to the fortrabbit remote via a graphical user interface.

# Get ready

{#get-ready-7}

• Database access intro
• Database export/import intro
• How to connect to the remote database through a MySQL GUI

# Export from local

{#export-from-local}

1. Open your MySQL GUI
2. Open your local database connection
3. Choose: Server > Data Export from the menu
4. Select your local database name
5. Make sure to "Dump Structure and Data"
6. Choose a local destination file
7. Start the export

# Import to fortrabbit

{#import-to-fortrabbit}

1. Open your MySQL GUI
2. Open the remote database connection
3. Choose: Server > Data Import from the menu
4. Choose your previously generated dump file
5. Start the import

# MySQL database download from remote to local via GUI

{#mysql-database-download-from-remote-to-local-via-gui}

Upload a remote database to your local development environment.

# Get ready

{#get-ready-8}

• Database access intro
• Database export/import intro
• How to connect to the remote database through a MySQL GUI

# Export from fortrabbit

{#export-from-fortrabbit}

1. Open your MySQL GUI
2. Open the remote database connection
3. Choose: Server > Data Export from the menu
4. Select the remote database name
5. Make sure to "Dump Structure and Data"
6. Choose a local destination file
7. Start the export

# Import to local

{#import-to-local}

1. Open your MySQL GUI
2. Choose: Server > Data Import from the menu
3. Choose your previously generated and downloaded dump file
4. Start the import

# MySQL export/import

{#mysql-export-import}

Syncing the database down and up.

# Advanced database tips

{#advanced-database-tips}

# Time zone

{#time-zone}

MySQL has time zone support. Our Nodes are defaulting to the standard time zone UTC+00 (aka GMT). If you want to change this time zone, you can do so on a "per connection" basis.

There are two approaches to tackle this issue: handle the time zone on application level or handle the time zone on database level. Each has its merits and which one is better strongly depends on the use case.

# GTID flag for import/export

{#gtid-flag-for-import-export}

The --set-gtid-purged=OFF option prevents GTID-related permission errors during import. This is required when:

• Your source database has GTID enabled
• You're using MariaDB locally
• You encounter #1227 - Access denied; you need SUPER privilege(s) errors

# Setting time zone in MySQL

{#setting-time-zone-in-mysql}

The syntax to change the time zone is:

-- set time zone to +3 hours
SET time_zone = '+03:00';

-- set time zone to -7 hours
SET time_zone = '-07:00';
sql

You can query the current time zone like so:

SELECT @@session.time_zone;
sql

# Setting time zone with PDO

{#setting-time-zone-with-pdo}

PDO offers configurable options when setting up the connection. One of them allows you to issue commands right after initialization (connection).

$pdo = new PDO(
    'mysql:host='. getenv('MYSQL_HOST'). ';dbname='. getenv('MYSQL_DATABASE'),
    getenv('MYSQL_USER'),
    getenv('MYSQL_PASSWORD'),
    array(
        PDO::MYSQL_ATTR_INIT_COMMAND => 'SET time_zone = \'+02:00\''
    )
);
php

# Resetting the MySQL password

{#resetting-the-mysql-password}

Instead of looking up the existing MySQL password, you can also reset it. Do so in the Dashboard > app > environment > MySQL. Please mind that this comes with consequences:

• Unless your are using env vars: You'll need to change the password in your code configuration files
• Your coworkers need to change their password in their locally configured remote access tools (see below)

# Accessing MySQL from a different environment

{#accessing-mysql-from-a-different-environment}

It is possible to access a MySQL from another environment within the same region (EU, US). The database from environment-A can be accessed from environment-B. This works since both environments are within the same network. You will only need to update the MySQL access credentials to do so. There are not many good use cases for this, but it might be good to know.

# Accessing the remote MySQL from your local environment

{#accessing-the-remote-mysql-from-your-local-environment}

It is also possible to access the fortrabbit database from the local installation. You will need to open a tunnel, as described above to do so. While possible we do not recommend that approach. You local App will feel slow, unless you have a very good internet connection. Further, you will run the risk of messing up the database if several apps are writing to it at the same time. The best practice here is separating the local development environment from production.

# MySQL limits

{#mysql-limits}

Each App has one database named like the App. The mysql-user you have received is not granted the privileges to CREATE DATABASE. Please mind that CREATE SCHEMA requires the same permission.

# Using MySQL functions, procedures and triggers

{#using-mysql-functions-procedures-and-triggers}

By default you don't have permissions to create MySQL functions, procedures and triggers as it requires SUPER privileges.

# Database troubleshooting

{#database-troubleshooting}

Common issues connecting to your database on fortrabbit.

# Can't connect from local

{#can-t-connect-from-local}

The most common misunderstanding when trying to connect from a local machine, is that people overlook to first open up the SSH tunnel and then connect to the database. Graphical MySQL clients support this connection method out of the box.

You'll need to enter both: SSH access and MySQL access details. Within the fortrabbit dashboard under your App > Access, there is a small link labeled: "Show SSH tunnel info" which will reveal everything you'll need to enter in a MySQL client to connect to the remote database.

# max_user_connections error

{#max-user-connections-error}

You'll see a max_user_connections error when you've reached the max connection limit.

SQLSTATE[HY000] [1226] User 'xxxxxx' has exceeded the 'max_user_connections' resource (current value: 10)
sql

The limit is defined by the MySQL component. Typical causes are:

• too many concurrent connections from the web
• every requests starts multiple connections to MySQL
• a background cron job or worker keeps connections open for a long time
• lingering queries that run for a long time
• MySQL GUI client opens too many connections (see below)

Figure out what's causing connections to linger → eliminate those causes.

# GUI clients eating MySQL connections

{#gui-clients-eating-mysql-connections}

You are trying to connect to the database with a MySQL GUI, like Navicat, Workbench or Sequel Ace? Some those clients are "eating" MySQL connections like popcorn. With fortrabbit, the MySQL connections and the PHP processes are limited. If you use up all the allotted connections, it can take a little until the App recovers. If this turns out to be a problem for you, look into limiting the number of concurrent connections from your MySQL gui or the App itself.

# Access denied; missing SUPER privileges

{#access-denied-missing-super-privileges}

When importing a database dump you've created with a recent version of mysqldump, you may experience errors like this:

#1227 - Access denied; you need (at least one of) the SUPER privilege(s) for this operation
raw

To prevent this error, create the dump again using the --set-gtid-purged=OFF option. If you don't use the mysqldump command line tool directly, but a GUI that relies on it, the chance is very high there is a checkbox to disable "GTID PURGED".

# Connection timeouts during large imports

{#connection-timeouts-during-large-imports}

• Split large dumps into smaller files
• Use --single-transaction flag for consistent snapshots

# Permission errors

{#permission-errors}

• Ensure you're using correct MySQL credentials from the dashboard
• Add --set-gtid-purged=OFF to the mysqldump command to maximize compatibility
• Add --no-tablespaces to the mysqldump command to maximize compatibility
• Check that you're running commands from your local machine, not via SSH

# Encoding issues

{#encoding-issues}

• Add --default-character-set=utf8mb4 to both export and import commands
• Ensure your dump file is saved with UTF-8 encoding

# MySQL overview

{#mysql-overview}

Everything we know supporting our clients running MySQL.

# PHP

{#php}

The PHP component provides instantly scalable computing power for PHP.

# Booking

{#booking}

Choose the PHP component plan while creating a new app or a new environment. For an existing environment you can visit the components page to change the PHP plan.

# Configuration

{#configuration-1}

Find PHP related setting pages with each of your environments in the dashboard. Here you can switch the PHP version and configure various PHP extensions and settings. There are also metrics and PHP related logs.

# Scaling

{#scaling}

PHP plans differ mostly in the available memory, as well as the number of PHP processes. Start small, scale later. Test and experiment with different scaling settings. Usually you will not need to change it over time. Keep an eye on memory and swap metrics in the dashboard.

# Autoscaling

{#autoscaling}

Autoscaling for PHP is not available. This is because of the flaky nature of PHP processing time going up and down and different customer requirements.

# Shared plans

{#shared-plans}

These are the most commonly used plans. Indeed the XS and the S plan are covering most normal website scenarios already. Some software systems have system requirements. The values below are good starting points from our experience:

The actual memory requirements are highly individual. It depends on the number of visitors, plugins and configuration and the custom code you write. See our performance design section for more.

# Dedicated plans

{#dedicated-plans}

Higher plans are available for heavy users and e-commerce systems.

# MySQL connections for PHP

{#mysql-connections-for-php}

The PHP plan also comes with matching MySQL connections, so that each PHP process can make one connection and there are some extra MySQL connections for connecting with a client from outside.

# MySQL

{#mysql}

Scalable database resources, optional, on demand. MySQL is part why PHP is so popular. It's the M in the LAMP stack.

Most classical CMS systems, such as WordPress and Craft CMS are using it as the central data storage. Alternatives to MySQL are PostgreSQL and Redis derivatives like Valkey.

# Booking MySQL

{#booking-mysql}

A MySQL database is an optional component available in different plans. Each environment can have one database component containing one database booked. The database can have multiple tables of course. Currently, only MySQL databases are available.

# Configuration

{#configuration-2}

When the database is enabled, multiple settings and metrics become available in the dashboard. Please refer to the MySQL usage section to learn more.

# Scaling

{#scaling-1}

Database plans differ mostly in the available storage, as well as the associated computing power. Usually MySQL and PHP are scaled alongside since they rely on each other. As a rule of thumb, match PHP XS with MySQL XS, PHP SM with MySQL SM etc.

When autoscaling is enabled, smaller and larger plans are automatically booked, based on usage.

# MySQL OFF

{#mysql-off}

The database is optional on fortrabbit. Your application may not require a database at all. Kirby, Statamic and Grav as static file systems are not requiring MySQL in the basic setup at all. Or maybe you run a Laravel application that only consumes a third party API or uses Redis. Please refer to the software requirements of your CMS or framework.

# Shared plans

{#shared-plans-1}

These are the most commonly used plans. Indeed the XS and the S plan are covering most normal website scenarios already. You can store a lot of text in 256 MB.

# Dedicated plans

{#dedicated-plans-1}

Higher plans are available for heavy users and large databases.

# Autoscaling

{#autoscaling-1}

MySQL has an autoscaling option. When turned on the next tier will be booked, once the storage limit is reached.

# Storage

{#storage}

Persistent local web space for code and files.

# Booking

{#booking-1}

Web storage is a required component available in different plans. Each environment needs to have storage booked.

# Configuration

{#configuration-3}

The storage is integrated as a persistent file system. You have direct code access by SSH and SFTP. The storage contains the deployed code, as well as runtime data, such as uploads and temporary files. See the directory structure article to learn about pre-configured folders. The dashboard shows metrics about the storage size.

# Scaling

{#scaling-2}

When autoscaling is enabled, smaller and larger plans are automatically booked, based on usage. When autoscaling is disabled, the storage is capped at the chosen plan. Once the limit is reached, the environment can not write on the file system until space is cleaned. Web storage may grow over time as your website writes more files to the disk. Keep an eye on the metrics provided in the dashboard.

# Backups

{#backups}

Web storage backups are available through the additional backup component.

# Traffic

{#traffic}

Outgoing bandwidth (egress) in bit and bytes.

# Booking

{#booking-2}

Traffic measures the data transfer that is caused by visitors browsing around your website (environment). It is booked per environment. Traffic is a passive component. It just happens. The max usage is billed over the month. It's designed in tiers and as most websites have predictable traffic patterns you can expect the same costs monthly. Most websites hosted here stay on the lowest tier.

# Scaling

{#scaling-3}

When autoscaling is enabled, smaller and larger plans are automatically booked, based on usage. When autoscaling is disabled, the traffic will capped at the chosen level. Once the limit is reached, the environment will go offline until the next billing cycle (next month) or until the plan will be upgraded.

In many cases, increased traffic usage will correlate with more website visitors. This also can have an effect on other booked resources. Check the website performance.

# Avoid website obesity

{#avoid-website-obesity}

Keep the footprint of your website slim. Send as few bytes over the wire as possible, so that you can serve more visitors with the same amount of traffic. Reducing your website weight will also make it load faster for your visitors and improve your SEO score. See also topic performance.

# Backups

{#backups-1}

Offsite code and database copies of environments.

Backups are an optional scalable component available per environment in various plans. They include file and database backups, see working with backup files. The encrypted backups are stored off-site on a block storage and do not count towards your storage usage. Backups can be downloaded from the dashboard, backup restore is offered too.

The number of backups created depends on your plan size, see backup retention. The backup schedule will start after booking. The first daily backup will become available the next day. On the next Monday, the weekly backup spot will be filled. On the first of the month the monthly backup will be stored.

# Jobs

{#jobs}

Offload long-running and compute-intensive worker tasks, and schedule cron scripts to run at specific times.

Jobs is an optional component that can be booked and scaled per environment in the dashboard. The scaling increases in available RAM and number of jobs.

┌─────────┐                        ┌───────────────────┐      ┌─────────────┐
│ visitor │ ◀─ Request/response ─▶ │  environment  │ ◀──▶ │ worker/cron │
└─────────┘                        └───────────────────┘      └─────────────┘
raw

Jobs run in a separate runtime container with access to the environment's file system and database. They are deferred from the front-end web layer to a background process that operates outside the web request/response life-cycle. This ensures that web requests are delivered swiftly, even when heavy processing is happening in the background. Environment variables and settings are kept in sync.

# Job types

{#job-types}

Worker jobs and cron jobs are widely supported by modern PHP frameworks like Laravel and Symfony, as well as CMS systems like Craft CMS and Statamic.

• Workers: Non-stop running in the background, event driven triggers
• Crons: Scheduled at certain times

# Scaling

{#scaling-4}

The available job plans differ in available memory and the number of jobs, that can be booked. Use the dashboard metrics to understand usage to determine the right plan to choose. Experiment with different plans to find the optimal scaling the project requires.

# Performance

{#performance}

Beside scaling up the component to improve performance, consider code refactoring or adjusting usage patterns.

# Sign of bad performance

{#sign-of-bad-performance}

• Overlapping jobs not finishing in decent time
• Increased 503 or 504 errors are

# Key-value store

{#key-value-store}

In-memory data store based on Valkey.

The key-value store is a Redis-compatible versatile open source software to be used as in-memory data structure store, key-value database, cache or even queue message broker.

The key-value component is based on Valkey - a high-performance, open-source key-value data store that evolved from Redis. It supports various data structures including strings, hashes, lists, sets, and sorted sets. With sub-millisecond latency and the ability to handle millions of operations per second, it's perfect for modern web applications that need fast data access.

# Use cases

{#use-cases-5}

• Caching: Store frequently accessed data in memory to reduce database load and improve response times.
• Session storage: Keep user sessions in memory for fast access across multiple servers.
• Real-time analytics: Track page views, user interactions, and other metrics in real-time.
• Message queuing: Implement pub/sub patterns for real-time features like notifications or chat.
• Rate limiting: Track API usage and implement throttling mechanisms.
• Temporary data: Store short-lived data like shopping carts or form data.

# Booking

{#booking-3}

The key-value store is implemented as an optional component on fortrabbit with various plans differing the available memory. It can be booked and scaled per environment. To book and scale the key-value store, navigate to the dashboard and select your environment. Find the components section. Choose the key-value store and select the desired plan based on your memory requirements. Confirm your selection to book the key-value store.

# Scaling

{#scaling-5}

Using a key-value store can contribute to better website performance. The component itself might also be scaled to further improve performance. As there are many different usage scenarios, there are no specific scaling recommendations. For most applications, the key-value store component will not hit critical limits. Thus autoscaling will not apply. When memory runs out, least recently used (LRU) keys are automatically removed to make space for new data.

• Start small and scale up based on your needs
• Monitor memory usage in the dashboard to understand your patterns
• Test performance at different scales to find the sweet spot
• Scale up gradually if you notice memory pressure
• Consider usage patterns - frequent writes need more memory than read-heavy workloads

# Using the key-value store

{#using-the-key-value-store}

Valkey is supported by many PHP frameworks and CMS's out of the box, it's popular among Laravel developers. For specific integrations check out the install guides and find out how to use it with your favorite framework or CMS.

# Session handler

{#session-handler}

If you don't use a framework, configure session.save_handler and session.save_path in your php.ini to tell phpvalkey where to store the sessions. Make sure to do it very early in your application, before accessing session data.

// Read the secrects you've set in the Dashboard
$secrets = json_decode(file_get_contents($_SERVER["APP_SECRETS"]), true);
$host    = $secrets['CUSTOM']['VALKEY_HOST'];
$port    = $secrets['CUSTOM']['VALKEY_PORT'];
$auth    = $secrets['CUSTOM']['VALKEY_PASSWORD'];

// Change the session handler
ini_set('session.save_handler', 'valkey');
ini_set("session.save_path", "tcp://{$host}:{$port}?persistent=1&timeout=2&auth={$auth}");
php

# Persistent connections

{#persistent-connections}

We recommend using persistent connections. Most adapters are configurable with a setting like persistent: 1.

# Best practices

{#best-practices-1}

1. Use meaningful key naming patterns like user:123:profile
2. Set appropriate expiration times for temporary data
3. Monitor memory usage regularly
4. Use persistent connections to reduce overhead
5. Implement proper error handling for connection failures
6. Test failover scenarios in your application

# Related resources

{#related-resources}

• Laravel Redis documentation
• Valkey documentation
• environments
• Component scaling strategies

# Components

{#components-1}

Individually scalable and billable hosting resources for environments AKA the service you buy here.

# The app

{#the-app}

Apps are grouping environments together and are the main subject of collaboration.

# Creating an app

{#creating-an-app}

Start a new app with the fortrabbit dashboard. The wizard will walk you through setting up the app, including plans and pricing, collaboration, software templates, data center location and git deployment.

# Apps and environments

{#apps-and-environments}

Each app represents one website or web application. Think about an app like a Git repo. In fact you can link a Git repo to an app. Each app has one ore more environments. Think about environments as git branches containing all data and runtime settings.

# Collaboration

{#collaboration-1}

The app is the main collaboration object. Developers can be added and removed from apps to manage settings, environments, deploy and access code.

# Billing

{#billing}

Apps are owned by payment methods and managed by developers in teams or directly. The app can be moved from one payment method to another.

# Deleting an app

{#deleting-an-app}

You can always delete Apps you have access on. To delete an app, visit the app in the dashboard, find and hit the "delete" button. The app will then get deleted within a couple of minutes - this includes all files and the database and is irreversible.

# Preview image and links

{#preview-image-and-links}

In some lists, apps can show a preview image and a link to be visited in the browser. The image and the link will use the environment that is most likely production and it's main domain.

# App name

{#app-name}

While creating an app, a name is suggested. When connecting a Git repo, the name of the repo is used. You can change that to anything you like. Choose a name that is easy for you to identify your project. The app name is only an identifier for the dashboard. It's not used anywhere else.

There is also an option to add a description to the app name.

# Changing the Git repo of an app

{#changing-the-git-repo-of-an-app}

You can change the repo of the app with the dashboard. It's a multi step process, as all environments will need to have branches mapped.

# Changing the payment method of an app

{#changing-the-payment-method-of-an-app}

You can move an app to a different payment method you have access to.

The app will be billed on the old payment method until that day of change and from the next day on to the new payment method. See post paid billing for more.

# Technical contacts

{#technical-contacts}

You can set technical contacts with the app. A technical contact is a 'web master' person that can be contacted by fortrabbit.

Please see the technical contact article for more details.

# The environment

{#the-environment}

An online version of your website including a full runtime.

# Intro

{#intro-2}

• An environment is a sub object of an app
• Each app needs to have at least one environment
• Environments are managed in the dashboard
• Each environment is a separated hosting setup, with individual settings
• Each environment has individually billed components
• Create multi staging workflows with multiple environments

We usually use 'environment', in some contexts maybe 'app environment' since this explicitly names the fortrabbit object and can not be confused with a development environment. In the dashboard, the environment title will constructed lie so: {app name} / {environment id}.

# Environment maps to git branch

{#environment-maps-to-git-branch}

While the Git repo is connected with the app, the environment can be mapped to a git branch. Git deployment is optional but blends in nicely.

# Environment workflows

{#environment-workflows}

Not all apps will have multiple environments. See the project organization article on how to work with apps and environments.

# Naming an environment

{#naming-an-environment}

The default name for environments is main. This does not imply if the environment is used for development or production. Many apps only have one environment that will first be used during development and later for production.

When connecting a git branch to an environment, the branch name will be used. The environment name can also be changed in the dashboard.

# Creating an environment

{#creating-an-environment}

While creating a new app you will also create an environment along the way. You can also create new environments for any of your apps later on.

# Restarting an environment

{#restarting-an-environment}

The restart button will restart all services. This can sometimes be helpful when processes are hanging.

In some edge cases, like hanging PHP processes with 504 errors or 408 errors, restarting an environment can be an option. Here is how you can do this:

1. visit the environment in the dashboard
2. find and click the "Restart" button
3. wait a minute until changes are applied

This will restart the Apache service and the PHP-FPM processes. Nothing more, the data will stay safe. There will be a short downtime. Use carefully, it should not be used on a regular basis. This button is not a silver bullet to fix all server issues. If performance is a constant issue, see performance topic.

# Deleting an environment

{#deleting-an-environment}

You can delete any environment you own or administer. To delete an environment, go to the environment in the dashboard and click the "delete" button. The environment will be removed within a few minutes, including all files and databases.

# Recovering deleted environments

{#recovering-deleted-environments}

Environment deletion is permanent and cannot be reversed. We thoroughly remove data when requested by clients or when required due to legal or payment issues. This policy protects your privacy and security. We believe you have the right to be forgotten rather than having your data held hostage (for payment). In most cases, this complete deletion is actually beneficial. For more information, see how we handle bounced payments.

# Environment settings

{#environment-settings}

The environment has a lot of settings exposed in the fortrabbit dashboard. See the hosting settings topic.

# The person

{#the-person}

A person is an object within the fortrabbit dashboard that represents a human being. A person can actively manage things with the fortrabbit dashboard and access code and is free of charge.

# Understand individual access

{#understand-individual-access}

It's common in classical hosting to have one account shared with a group of developers. Don't do that here. An account on fortrabbit maps to a person in real life, not an entity. Learn more about account organization.

# Developers and clients

{#developers-and-clients}

There are two types of people with the fortrabbit dashboard. You can choose your type when signing up and change it later on. A client is non technical person only managing to billing. A developer is a person with tech skills managing hosting, and maybe also billing. See account types for more.

# Code access

{#code-access}

Developers can add their public SSH keys for direct private code access. See the SSH keys section for more.

# Account settings

{#account-settings}

The account settings are part of the person and refer to your user registration at fortrabbit. By signing up you create a personal account. This is how you login and use the services.

# GitHub app

{#github-app}

To enable git deployment from GitHub, developers need to install the fortrabbit GitHub app with their personal GitHub account.

# The team

{#the-team}

A group of developers collaborating on code and billing.

# Recap

{#recap}

Your fortrabbit account is your personal access. The payment method represents the legal entity owning apps. The team object in the dashboard represents a group of developers collaborating on apps and payment methods. Check out the collaboration intro for more of the basics.

# Use cases

{#use-cases-6}

A team may represent your real life connections with other developers, like:

• A whole organization - your small agency, startup, association
• An organizational unit - a smaller group within a business, team tokio
• Any other kind of group of developers

# Creating a team

{#creating-a-team}

You can create as many teams as you want with the dashboard. Teams are free of charge.

# Inviting team members

{#inviting-team-members}

You can invite more team member through the dashboard. More details here.

# Access levels

{#access-levels}

There are two roles with the team: limited and unlimited. See the team roles article for more.

# Payment method access

{#payment-method-access}

Payment methods can be attached to teams. Teams can own apps via payment methods created by their members. This also allows billing collaboration, when teams participate on payment methods by clients.

# Deleting a team

{#deleting-a-team}

When deleting a team, payment methods and apps that are only associated through this team will be deleted along the way. There is a warning screen when deleting the team, explaining what will happen and what not. Deleting a team will not cancel your personal account.

# Leaving a team

{#leaving-a-team}

Everyone, except the last full member, can leave a team. In that case the team will stay, but you will loose access to it and it's objects. When you cancel your account and you are part of a team with other members left, you will leave the team.

# Working with multiple teams

{#working-with-multiple-teams}

Just like in real life, you can create or join any number of teams with your account. So one account can be part of multiple teams in different roles.

# One person in different teams

{#one-person-in-different-teams}

If you have multiple teams and you want to collaborate with same person on all or a subset of them: Just invite them to each team. The same person then will have access to all teams while logged in with their account.

# When developers leave

{#when-developers-leave}

The developer who leaves a team will loose the ability to see and edit the apps in the dashboard and also will loose all personal code access. There are two directions of leaving a team:

# Active: A developer leaves a team

{#active-a-developer-leaves-a-team}

You might want to leave the team when the project you have collaborated on has ended or you are actually leaving the team in real life as well.

1. Dashboard > team > Team overview
2. Click the "Leave" button

You can not leave a team when you are the last member remaining. A team must have at least one member.

# Passive: Team access is revoked

{#passive-team-access-is-revoked}

Let's say a project phase has ended, so that developer does not need have access any more.

How to revoke developer access

{#how-to-revoke-developer-access}

1. Dashboard > teams > team overview > members
2. Click the action button to edit access
3. This will bring up a form in which you can edit and revoke access

# The invoice object

{#the-invoice-object}

The invoice object is a recording of booked component plans across environments per month and payment method.

# Invoice details

{#invoice-details}

Each payment method with attached apps will get an invoice for each service period (monthly) - after the service period ends. The invoice contains all the apps, their environments and booked components.

• Invoice number - An individual number.
• Invoice date - The day, the invoice was printed.
• Service period - The backdating month.
• Invoice address - Postal address from payment method.
• Invoice email - Email address from payment method.
• VAT - See VAT article.

# States

{#states}

Invoices have a lifetime, going through various phases:

# Draft

{#draft}

During an ongoing service period, an invoice draft is kept and updated daily and with each booking. The invoice draft helps customers to keep track of current costs. During the DRAFT state the invoice will have a column to display current costs so far.

# Paid

{#paid}

At the enf of the service period, the invoice will be finalized, send to customers. The payment credentials of the payment method will be used to automatically pay the invoice. When successful, the invoice is paid.

# Bounced

{#bounced}

When the payment credentials on file fail, the invoice will be marked as bounced. If that will not resolved after various automatic retries, service cancellation is next. See late payments.

# Invoice item rows

{#invoice-item-rows}

Each invoice contains a number of rows. They are grouped by environment as each has a set of booked components. Each invoice row contains the booked component and it's plan and how many days it is billed for by days. The table gives you an idea how components and plans appear on an invoice.

In this example PHP XS was booked for a couple of days and then replaced by PHP S. See the postpaid billing article for more on that.

The printed invoice document may look a bit different.

# The payment method

{#the-payment-method}

A payment method owns apps, receives invoices and is managed by people.

# Overview

{#overview}

• A payment method has: payment type, invoice address, VAT settings …
• Each app - except during trial - is owned by a payment method
• Payment methods can own multiple apps
• Payment methods are managed by people directly or in teams
• Each team or person can have access on multiple payment methods
• Each payment method has its own invoice archive
• Payment methods are free of charge, apps they own cost something
• People are connected to payment methods by a billing connection

# Creating a payment method

{#creating-a-payment-method}

When creating your first paid app up or upgrading a trial app, you will create a payment method on the fly and link that app to it. You can also create a payment method from scratch to be used later on.

# Multiple payment methods

{#multiple-payment-methods}

You may need one app to be paid by one credit card and another app to be paid by another credit card. The payment method is not a part of your account but an individual object. You can create multiple payment methods and assign apps to them.

# Shared payment methods

{#shared-payment-methods}

You may be collaborating with other, in a team or in a client relation. Payment methods can also be shared. You can invite someone to collaborate or to take over a payment method.

# Changing the invoice address

{#changing-the-invoice-address}

Your invoices contain the street address of your payment method. You will be asked for that while setting up a payment method. You can change this invoice address for future invoices at any time in the dashboard.

# Changing payment credentials

{#changing-payment-credentials}

You have a new credit card or the old one is about to expire? You can change the payment credentials of a payment credentials of the payment method in the dashboard. Changing the payment credentials will affect future payments and will also be used to balance possible open invoices. In order to change the payment method you will need to have a fortrabbit account with access to the payment method.

# Adding a VAT IN

{#adding-a-vat-in}

It is recommended to add your VAT IN to your payment method when your organization is registered in the European Union. This can save you (and us) upfront value added taxes. Please see our VAT topic.

We need to validate the VAT IN. So the number you enter needs to match the correct format. Please mind that your VAT IN is not the tax number. The correct number should start with your country code. Entering the VAT IN will change how VAT will be charged for future invoices, entering the VAT IN can not affect past invoices.

# Changing the payment method of an app

{#changing-the-payment-method-of-an-app-1}

In case you want an app to be billed from another credit card or bank account but still want to keep the team of the app the same. Either replace the payment credentials or create a new payment method.

# Deleting a payment method

{#deleting-a-payment-method}

Deleting a payment method is similar to a service cancellation, since all the apps owned will be deleted as well and the invoice archive will be removed.

# Troubleshooting setup issues

{#troubleshooting-setup-issues}

From time to time clients report issues with setting up new payment methods. Here are some common issues:

• Debit cards might not be accepted, use a full blown credit card please
• Sadly credit cards from certain countries like Nigeria seem to have less acceptance
• We are debiting the card with a test transaction with a small amount - that's not a payment, you'll get it back right after
• EU clients might need to solve strong authentication (redirect to bank website)
• US and other countries might need to authorize the test debit, in some cases that means calling up the bank

We can do little about this. We pass your data directly to the payment gateway. Thanks for your understanding.

# The domain

{#the-domain}

Each fortrabbit environment has a test domain. Additionally you can route external domains.

# External domain

{#external-domain}

An "external domain" is a domain registered with a third party domain name registrar. fortrabbit does not provide domain registration services. Proceed here:

• Domain provider integration - combine domain provider with fortrabbit
• External domains intro - options and limits
• Point an external domain - step by step instructions

# Target settings

{#target-settings}

For most domains the target can be changed. Target settings can not be changed for:

• apex domains: will always forward to their www counterpart
• main domains: define a different main domain first

# Environment setting

{#environment-setting}

Change the environment of an external domain with this setting. External domains can be moved across environments without DNS changes. This can be useful when switching the production domain to a new environment.

# Root path setting

{#root-path-setting}

A root path is a folder in the file system of the environment where a domain will end. The root path is saved with the environment for all it's domains. That means, no interface is offered to configure individual root paths per domain. You can however configure custom routing of domains in your code and config, either by .htaccess rules or by some routing options with your software.

# Domain forwarding

{#domain-forwarding}

The dashboard allows you to forward domains with the same environment. Usually you will want to forward all domains to your main domain. See the www domain forwarding article.

# The deployment object

{#the-deployment-object}

After your git push, a deployment is happening, updating the web space with code changes from the Git repo. The deployment object makes that transparent with the dashboard.

The deployment object displays metadata, including deployment logs, the issuer, the environment, and a link to the deployed commit.

With the dashboard you can see a list of deployments that can be filtered down. Each list item links to an individual deployment which provides more insights and links. Older deployment events might be partially or fully pruned.

Deployments are recorded only for Git deployments using the official fortrabbit GitHub app. Deployments via GitHub Actions are not recorded.

SSH/SFTP sessions are not considered deployments either. With the deployment settings of an environment you can control the rules for deployment.

Please proceed to the deployment intro to learn more about the steps and what happens during a deployment.

# The SSH key object

{#the-ssh-key-object}

Remember, on fortrabbit an account represents a person. SSH key authentication is used to securely identify you for your personal code access. SSH keys are an object within the fortrabbit dashboard. Personal SSH keys can be managed with your account settings, deploy keys with each environment.

Don't have local SSH keys already or don't know what that is? See the SSH key setup and intro.

# Adding SSH keys to fortrabbit

{#adding-ssh-keys-to-fortrabbit}

The public part of the key must be imported in the fortrabbit dashboard. Paste the PUBLIC part of the key and not the private part. The value to paste into the text field can be read into the clipboard.

## macOS
{#macos}
$ pbcopy < ~/.ssh/id_ed25519.pub

## Linux
{#linux}
$ xclip -i < ~/.ssh/id_ed25519.pub

## Windows
{#windows}
## Open the `id_ed25519.pub` file, select all, then copy.
{#open-the-id-ed25519-pub-file-select-all-then-copy}
shell

# Personal keys

{#personal-keys}

In most cases you want to add SSH keys to your personal developer account at fortrabbit to directly login to the environment and opening an SSH tunnel. Personal SSH keys will be automatically added to all the environments you have a developer connection to.

Already using GitHub and our deployment flows? The fortrabbit dashboard may directly import public keys associated with your GitHub account so you don't need to setup additional keys for this.

# Deploy keys

{#deploy-keys}

In certain scenarios, you may want to grant a non-human service access to an environment. Use deploy keys for that. The deploy keys are managed via the dashboard with the environments. Adding and removing such keys follows the same concepts as described above. Use deploy keys to integrate with Git hosting services or deploy services.

# Dashboard objects

{#dashboard-objects}

Terminology, concepts, explanations.

# Pricing structure

{#pricing-structure}

Apps are grouping environments. Environments consist of components. Components are available in plans.

The example diagram below illustrates the billable structure of a payment method with two apps, one with one environment, the other with two environments. The environments have different plans of components booked.

- App 1 (takas)
  - Environment (production)
    - Components
      - PHP S
      - Web storage XS
      - Traffic S
      - Database OFF
      - …
- App 2 (project-earth)
  - Environment (production)
    - Components
      - PHP M
      - Web storage M
      - Database L
  - Environment (staging)
    - Components
      - …
raw

Most component plans are available as shared resources. Some higher plans of components are available as 'dedicated'.

# Postpaid billing

{#postpaid-billing}

First use, then pay: Service usage is measured throughout the billing period, with costs calculated and invoiced at completion.

# How prepaid works

{#how-prepaid-works}

In order to understand postpaid, it might be beneficial to describe the dominating model first: Most hosting providers offer prepaid pricing. That means you pay upfront for what you plan to use over the service period. Many hosting providers are requiring yearly subscriptions (with monthly payments). This in favor for the hosting provider, as it locks in the customers and guarantees long running contracts with fixed revenue.

# How postpaid works

{#how-postpaid-works}

With a postpaid model, also called in arrears, on the other side. Customers make use of the service and pay later after usage for the monthly service period.

• You don't pay on booking, only after the first month of usage
• After deletion, final charges appear on the next invoice

# Postpaid benefits

{#postpaid-benefits}

Postpaid enables prorated billing with daily usage aggregation. This again makes it easy to experiment with the hosting service as you'd aspect for agile workflows.

# No yearly payments

{#no-yearly-payments}

Postpaid usage is not compatible with yearly payment. As that would require to be able look into future usage or to only write yearly in arrears.

# Daily aggregation

{#daily-aggregation}

This is prorated billing where each day of service is billed at 1/30th of the monthly rate.

If you book a plan on the 16th day or create an app or environment, the invoice items will be calculated for 15 active usage days. The dollar signs indicate days that would be included in the invoice:

       April
Mo Tu We Th Fr Sa Su
     -  -  -  -  -
 -  -  -  -  -  -  -
 -  -  -  $  $  $  $
 $  $  $  $  $  $  $
 $  $  $  $
plain

The above example gives you a clue that we are charging after usage, see proration. First you use the service, at the end of the service period, actual costs are calculated together and invoiced.

# Examples

{#examples-3}

## Adding a component mid-month:
{#adding-a-component-mid-month}
Monthly rate: €30
Start date: 15th
Days used: 16
Charge: €16 (€30 ÷ 30 × 16)

## Upgrading a plan:
{#upgrading-a-plan}
Old plan: €30/month (€1/day)
New plan: €60/month (€2/day)
Charge: €19 (19 days × €1) + €22 (11 days × €2)
yml

# Benefits

{#benefits}

The daily cost usage aggregation promotes testing, tinkering and experimenting without much obligations and having to pay a fortune.

• Create a environment to test a feature branch for a couple of days
• Test best settings for scaling the production environment
• Scale up hosting resources for temporary events such as media coverage

# The largest plan counts

{#the-largest-plan-counts}

Let's say you want to find the best matching PHP plan size. For that you scale up and down the PHP plan while monitoring PHP response time and reloading the website to see effects in performance. On that day, PHP XS, PHP SM and PHP MD may have been in use. The invoice will show PHP MD for that day.

# Monthly prices for reference

{#monthly-prices-for-reference}

In our experience website projects most often run over months and even years. That's why monthly prices are most appropriate to show and reason about.

# 30 days monthly base

{#30-days-monthly-base}

Some months have 31 days, while February has either 28 or 29 days. To ensure consistency in monthly invoices, all months are normalized to 30 days. This means that when a component is booked for an entire month, it is always billed for 30 days.

The daily price is calculated as 1/30th of the monthly price. If a component is used for less than a full month, the cost is determined by multiplying the daily price (1/30th of the monthly price) by the number of days the component was active.

# No hourly prices

{#no-hourly-prices}

Some other hosting vendors offer hourly prices. We believe, that this is confusing and does not match the reality of most projects. To get an idea for the daily price you only need to divide the monthly price by 30. In most cases this about cents, costs one need not to worry much about anyways.

# Billing schedule

{#billing-schedule}

Within the first few days of every new month, you will get the invoice for the service period of the last month. After receiving the invoice, the payments are due and are charged automatically.

* See late payments for details

# Payment types

{#payment-types}

The fortrabbit service operates automatic monthly payments. This is how you can pay and under which conditions.

# Credit card

{#credit-card}

Visa, MasterCart and Amex are the supported credit cards. Many debit cards are not supported, some are, try it out. US clients might need to ask their bank to allow payments from us. When setting up the payment option we'll do a test charge. That's not a real charge. You may get a notification about this.

# SEPA direct debit (planned)

{#sepa-direct-debit-planned}

SEPA direct debit is accessible to clients in the European Union.

# Data sharing

{#data-sharing}

Billing data entered will directly be send to our payment provider.

# Autoscaling

{#autoscaling-2}

Scale components automatically when usage demands more resources.

Autoscaling is an option that can be toggled per environment with the component booking.

Autoscaling is available applies to the following components in the following ways:

Components are grouped in tiers. Even with autoscaling on, price fluctuation is not likely.

# Details

{#details}

• Selected plan is the minimum when autoscaling is on
• For traffic, the largest plan reached applies for the month
• Monitor MySQL memory alongside database storage usage

# Plans

{#plans}

A plan defines the scaling of a booked component. Each plan has a price and a set of included resources.

# Plan resources

{#plan-resources}

Each plan includes specific hardware resources and performance limits. Detailed specifications are available with the pricing page. While most components represent single scalable resources (like traffic or storage), some plans combine multiple resources. For example, MySQL plans scale both storage capacity and computing power together.

# Tiers

{#tiers}

Plans are grouped in carefully designed buckets. That makes the costs predictable and unlikely to fluctuate often over time. In fact most standard websites and applications will work with small plans just fine.

# Changing plans

{#changing-plans}

Plans can be upgraded or downgraded at any time with immediate effect. Changes are prorated with daily aggregation. Common reasons to change plans include:

• Handling increased traffic
• Optimizing costs during quiet periods
• Preparing for marketing campaigns
• Scaling for seasonal peaks

# Finding the right plan

{#finding-the-right-plan}

Start small and scale up as needed. Each application has unique requirements that depend on:

• Traffic patterns
• Application architecture
• Caching strategy
• Database usage
• Storage needs

The monitoring tools help you track resource usage and determine when to scale. Contact us if in doubt.

# Regional pricing

{#regional-pricing}

Plan prices vary by data center location due to local infrastructure costs. Consider this when choosing a region.

# Currency rules

{#currency-rules}

fortrabbit services are offered in (€) EUR and ($) USD. Different prices may apply based on the selected currency. It's also possible that prices differ by data center location.

# Ruleset

{#ruleset}

• All payment methods within the EU are required to pay in EUR.
• Payment methods from other countries can pay in USD or EUR.

# Changing the currency

{#changing-the-currency}

It is not possible to change the currency of a payment method later on. However, you can create a new payment method with a different currency and then move apps there.

# VAT rules

{#vat-rules}

fortrabbit is mainly a B2B service, clients are entrepreneurs or other businesses. It can also be used for B2C, clients are end consumers.

# Fiscal implications

{#fiscal-implications}

• Prices are shown as net prices, without Value Added Tax (VAT)
• No VAT is charged for customers outside EU
• No VAT is charged for registered business in EU (+ GB) with valid VATIN
• VAT is charged for VAT-registered business in Germany

# VATIN for EU clients

{#vatin-for-eu-clients}

It's recommended to enter your VATIN (Value Added Tax Identification Number), sometimes referenced as VAT TAX ID or similar. This way you save upfront costs for VAT — reverse charge makes this possible.

# EU VAT exemption

{#eu-vat-exemption}

We may not charge VAT, if article 151(1)(a) VAT Directive applies, e.g. for international bodies, embassies or other EU organizations with a valid VAT exemption certificate. Please get in touch if VAT exemption applies to your organization.

# Late payments

{#late-payments}

Sometimes payments don't go through. That happens. We understand it. Don't panic, but take care. This article guides you through the steps.

# Why payments bounce

{#why-payments-bounce}

There are various reasons why payments bounce:

• Insufficient funds - we will try to debit again after a few days
• Expired credit cards - Update your payment method
• Something else - Update your payment method

Please contact us if you are aware about open invoices with us and or if you have questions about an invoice. In any case, we will inform you by by e-mail about failed payments.

# Automatic retries

{#automatic-retries}

Over the course of the month we will retry to previously failed payments. This helps to resolve half on initial bounces.

# Service cancellation

{#service-cancellation}

At some point, after several unsuccessful attempts to charge the payment credentials on file, apps will be deleted. Deleted apps can not be recovered. Read why we do this in a story from our blog. Deleting apps for bounced payments is carefully considered with human review on a per customer basis.

# App deletion policy

{#app-deletion-policy}

If there are 3 consecutive unpaid invoices with no response, apps will be deleted.

• New clients: If the first or second invoice bounces and there is no response to our emails, apps will be deleted.
• Clients with fewer than 6 invoices: If an account has fewer than 6 invoices, or if the credit card processor flags potential fraud or the account appears suspicious, apps may be deleted.
• Long-term clients with more than 6 paid invoices: If there are at least 2 consecutive bounced invoices or a total of 4 unpaid invoices, we will attempt personal contact in addition to automated emails. If there is no response, apps may be deleted.
• High-value invoices: For clients with invoices exceeding €1k MRR, different rules may apply.

# Paying open invoices

{#paying-open-invoices}

Open invoices can be found in the Dashboard. Login to our Dashboard > follow the instructions in the "open invoices" warning. Credit card payments are done immediately. SEPA direct payments are delayed. If your credit card has insufficient funds at the time of charging, we may try to charge it again during the month.

# Refund policy

{#refund-policy}

We do not offer refunds due to the complexities involved with our custom billing system and German accounting regulations. Issuing refunds would require generating negative invoices and additional manual bookkeeping steps.

If you believe there is an error in your invoice, please contact our support team. We may offer credits towards future invoices as a gesture of goodwill.

Please note that all booked apps and environments utilize hardware resources regardless of visitor traffic or usage patterns.

# Additional fees for bounced payments

{#additional-fees-for-bounced-payments}

Please note that our bank collects fees for failed charges or insufficient funds. We may pass those fees to you. Currently we usually don't.

# How to download previous invoices

{#how-to-download-previous-invoices}

Options to download previous invoices from fortrabbit.

# A - See your mailbox

{#a-see-your-mailbox}

Search your e-mail inbox for "fortrabbit invoice". Each invoice e-mail contains a secret link to the invoice. From there you can print or download the invoice.

# B - Download from the dashboard

{#b-download-from-the-dashboard}

Login to the fortrabbit dashboard. Navigate to the payment method and see the invoice archive. The payment method needs to be active and you need to have access on that payment method to do this.

Invoices are shown as HTML. Depending on support in your browser, a PDF can be generated using the "Print to File" feature from your Browser/OS.

# Invoice threshold

{#invoice-threshold}

Invoices for partial usage may be below a minimum required invoice amount.

The threshold value may change over time and may be differ depending on currency and payment type. Consider something like 50 cent. We use Stripe as our invoicing provider and their threshold functionality. Invoices below threshold will be nullified automatically, so nothing needs to be paid for that service period. The amount will be added to the payment methods balance and applied to the next invoice.

# Example

{#example}

€0.30 Invoice March -> Threshold applied
€4.50 Invoice April - Apply threshold from balance
€4.80 Amount due in April
raw

# Billing

{#billing-1}

All stuff related to payments, invoices, VAT and what not.

# External domains

{#external-domains-1}

An "external domain" is a domain registered with a third-party domain name registrar. Connect an external domain with an environment to have it receive traffic for that address.

# Configure the external domain

{#configure-the-external-domain}

Please see external domain configuration.

# TLS certificates

{#tls-certificates}

Please see the HTTPS article for information on secured connections.

# Choosing a domain provider

{#choosing-a-domain-provider}

Please see our domain provider article what you may want to look for when choosing a domain provider to be used in combination with fortrabbit.

# Wildcard domains

{#wildcard-domains}

Wildcard domains are currently not supported at fortrabbit. Please file a support ticket to describe your use case.

# Configuring a domain for e-mail

{#configuring-a-domain-for-e-mail}

To receive and send e-mails from your domain you will configure the MX record of your domain with your domain provider. Please see your e-mail hosting provider for instructions, here is more on e-mail hosting from us.

# Troubleshooting

{#troubleshooting-2}

See our DNS troubleshooting guide if it is stuck.

# Point a domain to fortrabbit

{#point-a-domain-to-fortrabbit}

How to add an external domain and configure the domain provider to receive traffic on an environment hosted on fortrabbit.

# 1. Tell fortrabbit about your domain

{#1-tell-fortrabbit-about-your-domain}

1. Click New > "Add a new domain" and follow the steps
2. Choose a domain name and an environment
3. Keep the overview tab open to copy the desired DNS settings

# 2. Point the domain to fortrabbit

{#2-point-the-domain-to-fortrabbit}

Use the provided DNS information from the fortrabbit dashboard to change the domain routing with your domain provider.

• For sub domains like www, use the CNAME record
• Apex domains get an A record for forwarding
• Leave any other records untouched, especially MX
• Remove any AAAA records (IPV6)

Save the settings with your domain provider and wait a while. The while depends on the TTL settings of the DNS records, or usually up to 6h.

# Domain forwarding

{#domain-forwarding-1}

The fortrabbit domain forwarding service redirects incoming requests to another domain. It is mostly used to route an apex domain to 'www.'.

# Features

{#features}

• It uses '301 Moved Permanently' headers
• It works for https
• It also works for deep links like https://your-domain.com/page
• It works for www. and other subdomains

# General usage

{#general-usage}

Domains registered with the dashboard have a target setting. You can choose to route the domain directly to the root path of an environment or to be forwarded.

# Limitations

{#limitations-2}

• The target of a forwarded domain needs to be routed directly
• It is not possible to forward a domain to a forwarded domain
• Deleting a domain will delete domains forwarded to this domain as well

# Forwarded apex domains

{#forwarded-apex-domains}

When adding a www domain to the dashboard you will be provided a CNAME record (host name) for the www prefix and another domain for the apex domain. Here the routing is via A record (IP address). The IP address is the forwarding service. You will add both records with your domain provider.

# Recommendations

{#recommendations}

• Use www.domain.tld instead of just domain.tld in all links
• Send your external traffic (e.g. advertisement clicks) to the www. domain
• Configure your uptime checks with a URL to the the www. domain

# Alternatives

{#alternatives-3}

You don't have to use the fortrabbit free domain forwarding service, other options:

• ALIAS / ANAME routing
• Forwarding, using your domain provider
• Use .htaccess for more fine tuned control, see htaccess redirects

# HTTPS

{#https}

Zero-config TLS certificates for all domains at no additional costs are provided. Read on if you want to learn about advanced options.

# HTTPS on fortrabbit

{#https-on-fortrabbit}

All external domains correctly routed will receive a TLS certificate, no configuration or extra setup required. The certs will also be renewed automatically.

# HTTPS options

{#https-options}

The following practical tips on how to deal with HTTPS are applying to all TLS options on fortrabbit:

# Redirect all requests to HTTPS

{#redirect-all-requests-to-https}

It is recommended to forward all requests to the secure line, so no more "http://", only "https://". You can do that with .htaccess, see htaccess redirects.

# Secure your domain with a CAA record

{#secure-your-domain-with-a-caa-record}

A Certification Authority Authorization (CAA) is a DNS record to specify which certificate authorities (CAs) are allowed to issue certificates for a domain. It's an extra security layer, so that now one else can intercept any certificates by wrong authorities. There is no integration here on fortrabbit needed. See if your DNS / domain provider supports CAA entries, set the according identifying domain name. When you are using our free Let's Encrypt certs, see this article on how to set it up. Mind that already existing CAA entries can also become a problem when trying to issue new certificates.

# About HTTPS, TLS & SSL

{#about-https-tls-ssl}

HTTPS is Hyper Text Transfer Protocol over Transport Layer Security. It is used to secure the data transport between a client (browser) and a server. HTTPS is based on TLS (Transport Layer Security), which is the successor to the still better known SSL (Secure Sockets Layer). HTTPS is considered a standard must have for each website. Browsers show a lock in the address bar if the connection is over HTTPS.

# Troubleshooting HTTPS

{#troubleshooting-https}

See the HTTPS troubleshooting guide for some tips you can debug a secure connection on your own.

# Apex domains

{#apex-domains}

Apex domains, also called 'naked domain', 'root domain' or even 'bare domain', have no prefix and look like 'fortrabbit.com'.

# Apex routing at fortrabbit

{#apex-routing-at-fortrabbit}

Direct routing of apex domains to environments is not supported at fortrabbit. You can ese a www domain, the www forwarding service will redirect all requests.

# No CNAME for apex domains

{#no-cname-for-apex-domains}

Although not impossible, apex domains should really not be routed using a CNAME record. Use an A-Record instead. This is because of DNS specs. Receiving e-mails like info@fortrabbit.com would not be possible when DNS entries have CNAME record at the same time. Modern DNS providers support ANAME/ALIAS records for this.

# No direct A-record routing here

{#no-direct-a-record-routing-here}

A host name is more flexible than an IP. Any domain routed to an IP is bound to that IP. This doesn't give us the flexibility to move environments around, in case of scaling or incidents, for example with a DDoS attack.

# Our opinion on apex domains

{#our-opinion-on-apex-domains}

Some think that the minimal look of an apex domain is aesthetically more pleasing than their subdomain counterparts. But as described above, apex domains don't play well with flexible host name routing. Big players like Google use a www. subdomain without you noticing, and most bigger sites do the same. Safari and Chrome don't show the www. prefix in the address bar anymore. Firefox greys out the protocol of this trivial domain. The www. prefix is so common, you hardly recognize it. Some people think, moving from bare to www. will impact SEO negatively. This should not be the case if done properly, as long as the apex domain will forward all requests.

# DNS and domain troubleshooting

{#dns-and-domain-troubleshooting}

Solving common DNS problems when connecting an external domain to fortrabbit.

# Common issues

{#common-issues}

Here are the most common reasons why domain routing is not working. Start with this list first.

# Wrong DNS settings

{#wrong-dns-settings}

Most domain issues are related to wrong DNS settings. Carefully check if your actual target DNS settings match the desired DNS settings. It's possible that you have additional contradicting rules.

# Time delays

{#time-delays}

Many domain providers default to a long TTL (Time To Live). The TTL value is in seconds. Often it's 3600 meaning one hour. The TTL caching itself is actually a good thing as it helps to reduce round trips. Most domain providers let you set down the TTL, which is very useful to do before moving domains. See below on how to query the current DNS settings.

# Internal routing issues

{#internal-routing-issues}

When you see a 404 - file not found error after the domain is correctly via DNS and ending up at fortrabbit, then most likely your code configuration is not setup to receive traffic for the domain. This can be a wrong root path setting, or a siteUrl setting that is wrong. Also check our 404 tips.

# No DNS settings

{#no-dns-settings}

Depending on your browser you might see a DNS_PROBE_FINISHED_NXDOMAIN or This site can't be reached or This webpage is not available error. In such cases, it is likely that the domain is not registered or there are no DNS settings for that domain. You need to fix that with your domain provider.

# Certificate errors

{#certificate-errors}

Once a domain is correctly routed, the TLS certificate needs to be installed. This takes some additional time in which requests to the https version of the website will display a certificate warning in the browser. This is actually not a DNS issue, see the HTTPS troubleshooting guide.

# No domain configured with fortrabbit

{#no-domain-configured-with-fortrabbit}

Sometimes people forget to register and configure the domain with fortrabbit. Check if the domain is correctly setup with fortrabbit as well.

# Debugging DNS issues

{#debugging-dns-issues}

The following tips can help you to verify DNS settings for your domain. This is useful especially with time delays and wrong DNS settings.

# Use the dashboard as a guidance

{#use-the-dashboard-as-a-guidance}

When visiting your external domain within the dashboard, you'll see the desired and the currently active DNS values for the domain. Those two settings should match.

# Use dig to verify current DNS values

{#use-dig-to-verify-current-dns-values}

You can verify DNS settings with the dig command.

# Use a DNS checker website

{#use-a-dns-checker-website}

You can also use DNS test websites to rule out caching, those can query your DNS entries from different locations at once.

# DNS and domains

{#dns-and-domains}

# Collaboration intro

{#collaboration-intro}

The fortrabbit dashboard is build around collaboration. There are some unique concepts about it.

# Personal access

{#personal-access}

Sign up to fortrabbit as an individual person, not a company or entity. See account organization and the person object for more details on why and how to use your personal account. For most scenarios, you a person will only need one account and one login.

# Two levels of collaboration

{#two-levels-of-collaboration}

There are two types of collaboration on the fortrabbit hosting platform:

• Developer collaboration - sharing technical aspects
• Billing collaboration - sharing billing access

This enables to share developer access to an app without sharing billing access at the same time. It's also the foundation to work with non-technical business owners (clients).

With teams it's practical that the unlimited members have combined control on developer access and billing access.

# Team invite

{#team-invite}

Share access to a team with fellow developers by inviting them.

# Use cases

{#use-cases-7}

A team is group of developers working together on multiple apps. Use this flow to invite a developer to collaborate on multiple (current and future) apps and take part in the team as well. Invite people you know well and trust.

# How it works

{#how-it-works-3}

This describes the team invite flow from both sides:

# On the inviter side

{#on-the-inviter-side}

1. You need to have unlimited access on a team already
2. In the dashboard, find the link.
3. Select the team you like to invite someone to
4. Select the role of the invited developer - see team roles
5. Select the apps they should have access on - see developer connection
6. Enter the email address of your colleague

# On the invited side

{#on-the-invited-side}

1. They receive an email with an invite link
2. They login to their fortrabbit account or create a new account for this
3. Then they need to accept the invite

# Consequences

{#consequences}

• They will become part of your team with role you selected for them
• Their team role defines their access level

# Alternative app invite

{#alternative-app-invite}

You can also invite developers or teams to specific apps, see the app invite flow.

# Invite to app

{#invite-to-app}

Share access to a single app. Use this flow to invite an external developer or team of developers to a specific app.

# Use cases

{#use-cases-8}

The app invite is a flow to share app access between developers who don't know each other so well or don't have to collaborate on a lot of apps.

• A solo developer invites a colleague
• A loosely connected group of developers collaborating per project
• A team works together with another team and shares one app
• A team invites a freelancer to a specific app but not to the whole team
• A client invites a developer

# How it works

{#how-it-works-4}

This describes the app invite flow from both sides:

# On the inviter side

{#on-the-inviter-side-1}

1. You need to have an app already
2. In the dashboard, find the link to invite to an app
3. Select the app you like to invite someone to
4. Enter the email address of your colleague

# On the invited side

{#on-the-invited-side-1}

1. Receive an email with an invite link
2. Login to fortrabbit or create a new account for this
3. Accept the invite to gain a developer connection

# Consequences

{#consequences-1}

• Invited developers have a developer connection
• They have the same access on the app as yourself
• They can change all settings, deploy code and delete the app
• They can also change collaboration of the app
• This does not change billing or access on the payment method of the app

# Alternative team invite

{#alternative-team-invite}

If you plan to collaborate with someone on a regular basis and on more than one app, consider using a team.

# Invite to a payment method

{#invite-to-a-payment-method}

Share access to a payment method. Use this to invite a developer or team to a payment method.

# Get ready

{#get-ready-9}

Understand that an account at fortrabbit represents a person. Apps are owned by payment methods, which are objects that are controlled by people. See billing collaboration for the concepts.

# Use cases

{#use-cases-9}

Use the 'invite to payment method' flow to invite someone to access an existing payment method. The invited person can be a non technical business owner (client, see account types) or a tech-savvy developer to connect a team. Use this flow to invite:

• A co-founder of a startup or agency
• Someone from the billing department
• Another team

Depending on the account type people connected to a payment method can:

• Clients and developers: receive invoices, change the billing credentials
• Developers: attach the payment method to new apps or existing apps

# How it works

{#how-it-works-5}

This describes the app invite flow from both sides:

# On the inviter side

{#on-the-inviter-side-2}

1. You need to have a billing connection to a payment method
2. In the dashboard, find the link
3. Select the apps you like them to pay
4. Enter the email address of payee

# On the invited side

{#on-the-invited-side-2}

1. Receive an email with an invite link
2. Login to fortrabbit or create a new account for this
3. Accept the invite and follow the steps to create or choose a new payment method for the apps

# Consequences

{#consequences-2}

• The inviter will loose their billing connection to the app
• The inviter will keep the developer connection
• The invited account is in power to delete the app or assign other developers
• It's also possible to connect a team to a payment method

# Alternatives

{#alternatives-4}

This flow is specifically made to share access on a payment method. You can also invite someone to a take over billing.

With team collaboration members with unlimited access - see team roles - automatically have access to payment methods that are connected to the team.

# Invite to take over billing

{#invite-to-take-over-billing}

Invite someone to take over billing and transfer the payment method of an app - works for trial apps too.

# Get ready

{#get-ready-10}

Understand that an account at fortrabbit represents a person. Apps are owned by payment methods, which are objects that are controlled by people. See billing collaboration for the concepts.

# Use cases

{#use-cases-10}

Use the 'invite to pay' flow to invite your client or the new owner to pay for the apps.

• A freelancer developer invites his client
• The owner of a project is changing

In most cases the invited person is a non technical business owner and thus will choose to become a client, see account types, to not be bothered with developer topics.

# Designed for freelancers and their clients

{#designed-for-freelancers-and-their-clients}

With the invite to pay flow you will pass on control of ownership. You will not have a billing connection to the apps after any more. This is by design. The invite to pay flow specifically supports freelancers working with their clients. Freelancing developers should not be responsible for the hosting.

# How it works

{#how-it-works-6}

This describes the app invite flow from both sides:

# On the inviter side

{#on-the-inviter-side-3}

1. You need to have an app already, this can be a trial app
2. In the dashboard, find the link
3. Select the apps you like them to pay
4. Enter the email address of payee

# On the invited side

{#on-the-invited-side-3}

1. Receive an email with an invite link
2. Login to fortrabbit or create a new account for this
3. Accept the invite and follow the steps to create or choose a new payment method for the apps

# Consequences

{#consequences-3}

• The inviter will loose their billing connection to the app
• The inviter will keep the developer connection
• The invited account is in power to delete the app or assign other developers

# Alternatives

{#alternatives-5}

This flow is specifically made to transfer payment for apps. You can also invite someone to a payment method that already exists.

# How to

{#how-to}

Git things done.

# Developer collaboration

{#developer-collaboration}

Concepts and workflows to share app access with other developers.

# Get ready

{#get-ready-11}

Have a look at the collaboration intro to understand the basics of the fortrabbit collaboration features.

┌───────────┐    ┌───────────┐
│ developer │    │ developer │
└─────┬─────┘    └─────┬─────┘
  unlimited         limited
┌─────▼────────────────▼────┐
│           team            │
└───┬─────────┬─────────┬───┘
┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│  app  │ │  app  │ │  app  │
└───────┘ └───▲───┘ └───────┘
        ┌─────┴─────┐
        │ developer │
        └───────────┘
raw

The illustration above shows the different ways to connect developers to apps, directly or through teams.

# Direct app access and collaboration

{#direct-app-access-and-collaboration}

Suited for freelancers, solo developers and solopreneurs. By default apps are directly attached to your personal account. Use cases:

• Personal projects, portfolios, learning, weekend hacks
• Direct client work

It's possible to share developer access on an app by app basis. You can invite a colleague, or another freelancer to specific apps:

• About app invites

# Team collaboration

{#team-collaboration}

Work together on multiple apps in a team of developers with simple role based access. Instead of sharing app by app, share access to a group of apps with a group of people.

• About teams
• Team roles
• About team invites

# Billing collaboration

{#billing-collaboration}

Share access to billing with clients, the boss, the billing department and fellow founders.

┌───────────┐    ┌───────────┐
│   team    │    │  person   │
└─────┬─────┘    └─────┬─────┘
    access           access
┌─────▼────────────────▼────┐
│       payment method      │
└───┬─────────┬─────────┬───┘
   owns      owns     owns
┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│  app  │ │  app  │ │  app  │
└───────┘ └───────┘ └───────┘
raw

The above illustrates how teams and individuals can share access on a payment method, which owns the apps.

# Non technical client access

{#non-technical-client-access}

Most parts of the fortrabbit platform are very technical. Often the business owners are not developers. That's why there are two type of accounts with the fortrabbit dashboard: developer and clients. See account types for more.

# Direct billing access

{#direct-billing-access}

People can be connected to payment methods directly. This includes developers, as well as clients. When a connection between a payment method and a person is established by invitation, the person can control the payment method and it's apps.

# Billing access with teams

{#billing-access-with-teams}

Teams can also be connected to payment methods. In such cases the billing access is role based. All team members with unlimited team access have full access on the connected payment methods as well.

# Separation of concerns

{#separation-of-concerns}

Some of our agency and freelancer clients prefer to bill their clients a yearly maintenance fee for websites (retainer) which includes the fees for hosting. That's OK and you can continue doing that. But inviting clients to become fortrabbit themselves has some benefits:

Most importantly, responsibility gaps can be avoided. When end clients are becoming our clients are directly, we will have to deal with them. It includes an exist strategy for agencies and freelancers as well, they can simply leave the client apps alone.

We believe transparency is important for such business relations. So we don't offer a white label hosting solution or agency bonus programs.

# Two levels of collaboration

{#two-levels-of-collaboration-1}

# Technical contact

{#technical-contact}

Assign developers to be contacted by fortrabbit.

A technical contact is a person with a developer connection to the app - usually the responsible developer with good knowledge of the project and code base. Think 'web master'.

Each app should have one or more technical contacts associated. There is a dashboard setting with the app to select technical contacts from a list of developers connected with the app. By default, the developer creating the app will be assigned.

fortrabbit staff may get in touch with the technical contacts by e-mail to inform about important updates related to specific apps. Examples are:

• Software vulnerabilities
• Important software updates or incompatibilities
• Targeted DDoS attacks
• Excessive resource over-usage
• Suspicious activities
• Website hacked

Pro-actively contacting customers about important issues is done by fortrabbit at a best effort basis. fortrabbit does not guarantee contact coverage for any potential problem. It remains the responsibility of the customer to keep the software up-dated, as well as the list of technical contacts.

# Billing connection

{#billing-connection}

A billing connection associates a person with an app through a payment method, either directly or through a team. A billing connection allows administrative tasks on an app, but has nothing to do with code access.

## Billing connection
{#billing-connection-1}
person → payment method → app
person → team → payment method → app
plain

# What you can do with a billing connection

{#what-you-can-do-with-a-billing-connection}

• Add/remove developers and teams
• Delete apps
• Create apps
• Change the payment method

# Who can have a billing connection?

{#who-can-have-a-billing-connection}

• Developers and clients, see account types

# Billing connection types

{#billing-connection-types}

One can either have direct billing connection or through a team.

# Direct billing connection

{#direct-billing-connection}

You can have your own personal payment method that can also be shared. You can also be invited or invite other developers to directly connect to an app you have access on.

# Team billing connections

{#team-billing-connections}

Team members with unlimited access - see team roles- have access on all payment methods connected to the team.

# Relation to developer connection

{#relation-to-developer-connection}

A similar concept is the developer connection, which defines how a person has technical access on an app.

# Developer connection

{#developer-connection}

A developer connection defines how a developer is associated with an app.

## Developer connection
{#developer-connection-1}
person → app
person → team → app
plain

# What you can do with a developer connection

{#what-you-can-do-with-a-developer-connection}

• Change settings and deploy code to an app
• Delete apps
• Create apps

# Who can have a developer connection?

{#who-can-have-a-developer-connection}

• Developers only, see account types

# Developer connection types

{#developer-connection-types}

A developer can have a direct developer connection or through a team:

# Direct developer connection

{#direct-developer-connection}

You can have your own personal apps that can also be shared. You can also be invited or invite other developers to directly connect to an app you have access on. See app invite.

# Team developer connections

{#team-developer-connections}

When creating an app and you have access on teams, you will be asked about the context, which can either be personal or team.

Not all team members are automatically connected to all apps of the team. Instead you can subscribe to apps that you'd like to be connected to. Unlimited team members can subscribe themselves. Limited team members can request access on team apps. See team roles.

# One developer connection per app

{#one-developer-connection-per-app}

Each developer can only have one active developer connection to an app. While it is possible that an app is connected to different teams and also a developer can be part of different teams, the developer still needs to decide how they want to be connected to the app.

# Relation to technical contacts

{#relation-to-technical-contacts}

Not all developers connected to the app need to be technical contact.

# Relation to billing connection

{#relation-to-billing-connection}

A similar concept is the billing connection, which defines how a person has billing access on an app.

# Account types

{#account-types}

# Understand individual access

{#understand-individual-access-1}

An account on fortrabbit represents a person, not an entity. Your account settings are part of your personal access to the fortrabbit system, also see account organization. You can choose your type of account when signing up and change it later on if you made mistake initially.

# Developer

{#developer}

As a developer you are exposed to all dashboard and platform features. You have technical access to apps and all collaboration features such as teams. Developers can:

• Create and delete teams
• Collaborate in teams
• Create, delete and change apps
• Create, delete and change environments
• Deploy code to environments
• Create, delete and change payment methods
• Change billing for apps

# Client

{#client}

As a client you have limited access on the dashboard. Most technical aspects are hidden to remove unnecessary complexity. A client account is also a personal login and should not be shared. A client can be the client of a freelancing developer or an agency. It can also be the boss or someone from the billing department. Clients have the power to manage billing aspects and certain parts of collaboration. This includes:

• Add and remove developers and teams to apps
• Delete apps
• Create, delete and change payment methods
• Change billing for apps

# Convenience

{#convenience}

The client features are freeing you from babysitting the billing setup with your client. It's a more enjoyable experience for your client too. They are in control, yet not overwhelmed.

# Responsibility

{#responsibility}

The most important part of the client feature is separation of concerns. When the website goes down because of service issues with us, we - not you the developer - need to face the client. For that, we have the service level agreement with your client directly. And when your client forgets to pay the hosting fees or to update the payment credentials, it's our job to run after the money.

# Not limited

{#not-limited}

While the client feature is popular and recommended, we know that it will not fit all business workflows. More corporate clients might have restrictions on 3rd party providers, or you simply prefer to have a yearly retainer with your client. That's why there are additional workflows for consolidated billing using payment methods to be separated or shared by teams or projects.

# Team roles

{#team-roles}

Each team member has an associated role within a team. Developers with one role in one team can have a different role in a different team.

# Unlimited

{#unlimited}

This is the standard role and is often suitable for all members small teams or senior developers of large teams. It gives the person with thr role full access on the team, it's apps, it's members and billing.

• create, delete, configure & scale all apps with the tam
• create and delete environments
• access code of all apps of the team
• subscribe and unsubscribe from apps
• delete, create, change payment methods connected to the team
• manage all other member roles
• invite new member for any role to the team
• leave the team (if other members are present)
• delete the team

# Limited

{#limited}

Use this role to limit access for junior developers or developers that are not part of the core team.

• delete, configure & scale chosen apps of the team
• create and delete environments
• unsubscribe from team apps
• request access on team apps
• access code on chosen apps
• leave the team

# Collaboration

{#collaboration-2}

Sharing access infra resources with others.

# Backup files

{#backup-files}

What is included and excluded. How to use the files downloaded from the backup component to actually restore a website.

The fortrabbit backup component provides you with a downloadable file archive of an environment at a given time, see retention. This archive contains everything required to restore the state of that backup.

• Files: Everything present on the file system
• Database: a database dump file, if database is booked

# Use cases

{#use-cases-11}

• Grab a single file that was deleted
• Restore only the database but not the files
• Additional backups: store backups offsite for long time retention
• Boarding a new developer: Set up a local development
• Verifying the state of a backup before restoring

# Backups VS git deployment

{#backups-vs-git-deployment}

Developers using git deployment already have access to an archive with a complete history of the code base. The fortrabbit backups also contain runtime data such as the vendor folder contents and user uploads. Given the nature of most PHP based applications.

# Backup file sizes

{#backup-file-sizes}

The shown size of the backups is unlikely to match what is shown with actual usage for MySQL size and web storage. Mind that the backups are compressed, while the data in production is not.

The size of the backup shown in the dashboard likely will not match with the downloaded files. This is because the sizes with the dashboard are shown in binary (mebibyte) not decimal format (megabyte) like with most Operating Systems. Also the local file system may have a different block size.

# Excludes

{#excludes}

Some run-time and cache files are excluded from the backups.

## Craft
{#craft}
'storage/backups/',
'storage/logs/',
'storage/runtime/',
'web/cpresources/',

## Laravel
{#laravel-2}
'storage/framework/',
'storage/logs/',

## Symfony
{#symfony-1}
'var/cache/',
'var/log/',

## WordPress
{#wordpress-1}
'wp-content/cache/',

## Archives
{#archives}
'*.zip',
'*.tar',
'*.tar.gz',
'*.tgz',
'*.tar.bz2',
'*.tbz',

## Misc
{#misc}
'.git/',
'*.sql',
raw

# Restore from backup files

{#restore-from-backup-files}

While you can restore from backup using the dashboard, you also have the option to manually revert to a previous state by uploading the necessary files to the environment.

# Restore files

{#restore-files}

To recover files from a backup, first ensure to have the unpacked files from the backup archive on your local machine. Then upload these files to your environment at using SFTP or rsync. Be sure to remove any unnecessary files from the remote environment and don't forget to include hidden files.

# Restore database

{#restore-database}

The database backup file is a standard dump created by the mysqldump tool. Restore it by importing the data into your MySQL database. For detailed instructions, refer to our database export/import guides. It may be necessary to drop the old tables before importing the new data.

# Topic backups

{#topic-backups}

# Restore from backup

{#restore-from-backup}

Rollback an environment to a prior state.

# Requirements

{#requirements}

To restore from a backup, the backup component needs to be booked and at least one backup already needs to be present with the environment to be chosen as backup source.

# Use cases

{#use-cases-12}

• Something broke the site, you want to go back to a working state
• The site has been hacked

# How to restore a backup

{#how-to-restore-a-backup}

• Visit the backups section of an environment
• With the list of available backups choose the one you want to restore
• Click the restore button, confirm, wait until finished

The process can take a while. The time it takes depends on the size of the project. It is usually finished within a couple a couple of minutes but can also take hours. While the backup restore is in progress, the environment will stay online for most of the time, but may have degraded performance. A short downtime is expected.

# What happens during restore

{#what-happens-during-restore}

The chosen backup will be unpacked and prepared. Once ready, the state will be switched. The environment will serve the state of backup, the previous state will be deleted.

# Recommendations

{#recommendations-1}

• Back up the current state, by manual backup or by downloading a snapshot
• Know about the state of the backup you are about to roll back to, see backup files
• Don't change anything while the backup rollback is in progress

# No guarantees

{#no-guarantees}

It can not be guaranteed that the backup restoration will leave the environment in a working state. It's possible that the environment returns an error after the restoration. In many cases that's a 500 error, which is easy to debug, by looking at the logs.

# Backup restore VS git deployment

{#backup-restore-vs-git-deployment}

Mind that the backup includes the actual state of files present at the time when the backup was made. When git deployment is used, the head of the connected branch might be ahead. So it's possible that the next git deployment will cause issues. One way to deal with that is to reset the connected Git repo to a state that matches the restored backup, but there is no general rule of thumb for that.

# Backup excludes

{#backup-excludes}

See backup excludes.

# Backup retention

{#backup-retention}

The backup component is available in different plans. Larger ones include more backups. Backup retention determines how long backups are kept. This concept is crucial for ensuring data availability, compliance, and efficient storage management.

Depending on the plan chosen, multiple backups of the same type might be included. If the plan includes three monthly backups, then monthly backups are retained for three months.

# Daily backups

{#daily-backups}

• kept for a short period
• created daily at randomized times

# Weekly backups

{#weekly-backups}

• retained for a longer period
• Sunday backups are kept

# Monthly backups

{#monthly-backups}

• kept for an extended period
• Backups from the start of the month are kept

# Manual backups

{#manual-backups}

In addition to automatically scheduled backups, it's possible to trigger the immediate creation a backup from the dashboard. This backup will be treated like a new daily backup.

• If the currently booked backup plan includes one daily backup, the new manual backup will replace the current backup.
• If the currently booked backup plan includes two daily backups, the oldest backup from two days ago will be deleted and the backup from yesterday will move down one slot.

# Jobs usage

{#jobs-usage}

Jobs are an optional component, see booking and scaling jobs. After booking a new settings page will become available with the environment in the dashboard. Here you can add, remove, start, stop and edit jobs.

# Job settings

{#job-settings}

• Status: active/disabled
• Job name: A unique name, identifier
• Command: The command to run, see below
• Job type: Cron or worker
• Exit signal: Graceful shutdown - default is usually fine
• Exit timeout: Time to forceful kill when graceful shutdown is not responding

When choosing the type cron these additional settings become available:

• Interval: How and when the job should run, see crontab help
• Max runtime: How long the job is allowed to run

# Command settings

{#command-settings}

You need to call a command or script via the runtime. To call a PHP task you need to prefix it with php. To call a shell script you need to prefix it with bash:

• php artisan queue:listen -v
• bash path/to/my-script.sh

# Job types

{#job-types-1}

• Workers: Non-stop running in the background, event driven triggers
• Crons: Scheduled at certain times

# Crons

{#crons}

Cron basics, crontab syntax.

# About crons

{#about-crons}

A cron job is a scheduled task in Linux that automates executing software, typically shell scripts or executables. They allow you to schedule tasks, such as running scripts or commands, to occur automatically at specific times or intervals. The fortrabbit platform offers some additional abstraction. Crons are available with the jobs component and managed through the dashboard, see job usage. The job component runs in an isolated container, so that frontend and backend processes are separated.

# Cron use cases

{#cron-use-cases}

• Publish a scheduled story
• Periodic email sending
• Read and parse RSS feeds
• Collect and analyze data
• Generate reports
• Run database optimizations
• Update contents
• Clear caches

Cron jobs are entries in the cron table (crontab), each containing a schedule and a command to execute. The cron daemon (crond) reads the crontab to determine which jobs to run and when to run them.

# Crontab schedule reference

{#crontab-schedule-reference}

* * * * *
| | | | |
| | | | Day of week (0-6 | Sun-Sat)
| | | |
| | | Month (1-12)
| | |
| | Day of Month (1-31)
| |
| Hour (0-23)
|
Min (0-59)
plain

Online tools like crontab.guru can help you with configuration.

# Crons in PHP today

{#crons-in-php-today}

Crons are common and have been around for a long time in the PHP world. You can call any PHP script as a cron at a specified time or interval. Having the cron script in PHP gives you the benefit of version controlling the logic of the job to run. Modern PHP frameworks, such as Laravel and Symfony have added their own scheduling components and logic with advanced features. They offer additional abstraction so developers don't need to deal with nitty gritty.

• Laravel: artisan schedule:run, see Laravel queuing

# Crons on fortrabbit

{#crons-on-fortrabbit}

The fortrabbit platform offers additional abstraction. Crons are part of the jobs component. See job tuning.

# Crons and deployments

{#crons-and-deployments}

Each successful deployment will restart all running crons. This assures the jobs are running on the latest code base.

# Workers

{#workers}

Long running scripts, isolated in the background.

# About workers

{#about-workers}

A worker job is a long running task that is executing software, scripts or executables. The fortrabbit platform offers some additional abstraction. Workers are available with the jobs component and managed through the dashboard, see job usage. The job component runs in an isolated container, so that frontend and backend processes are separated.

Unlike crons, which offer scheduled execution of scripts, worker jobs can run non-stop in the background.

# Worker jobs use cases

{#worker-jobs-use-cases}

• Image processing
• API communication
• Meta data aggregation

# Workers and deployments

{#workers-and-deployments}

Each successful deployment will restart all running workers. This assures the jobs are running on the latest code base.

# Jobs tuning

{#jobs-tuning}

# Logging

{#logging}

Both STDOUT and STDERR generated by any job are logged by our platform, but aren't accessible right now. They will eventually be shown in the dashboard.

# Restart after code update

{#restart-after-code-update}

This happens automatically. Whenever you push a new code update via git deployment, jobs will be shutdown and started anew.

# Considerations

{#considerations-1}

• The total (max) memory amount of all jobs should be below the memory limit of the plan.
• Exits of jobs should be looked into. Usually nonstop worker jobs should run continuously and not exit often.

The memory limit is for all jobs combined. Resources needed for each application can vary largely, depending on what each particular job is doing.

# Graceful shutdown

{#graceful-shutdown}

If your job does really long running processing, it's likely running at all times. Any code push or manual deployment forces a restart of all jobs.

To avoid losing valuable state when our system kills the job, you can use Unix signal handling to write a graceful shutdown handler. For this you can use the automatically available PCNTL extension.

The most simplistic PHP script for a job is a while loop:

while (true) {
  do_something();
  sleep(5);
}
php

To make sure that do_something() is never aborted, you can extend the script like so:

declare(ticks=1);

$shutdown = false;
pcntl_signal(SIGTERM, function($signo) use (&$shutdown) {
    error_log("Received shutdown signal");
    $shutdown = true;
});

while (true) {
  do_something();
  foreach (range(1, 5) as $num) {
    if ($shutdown) {
      error_log("Shutting down safely");
      exit(0);
    }
    sleep(1);
  }
}
php

# Do not detach

{#do-not-detach}

If you don't know what that is: never mind. If you do know: don't detach. To guarantee that we can monitor jobs correctly they need to run with-under the parent processes which started them. All detached processes will be killed.

# Overlapping jobs

{#overlapping-jobs}

Sometimes a cron job may be called quickly multiple times and thus end up with multiple instances of the same job running. At best you should design your application so that this does not happen or happens in a controlled manner. We have reasonable limits in place to control how many instances of the same job are allowed to run in parallel.

# Jobs

{#jobs-1}

Working with crons and workers.

# Platform

{#platform}

Familiarize yourself with the building blocks of fortrabbit.

# Install Laravel locally

{#install-laravel-locally}

# Get ready

{#get-ready-12}

Have a local development environment up and running.

# Install Laravel on your local machine

{#install-laravel-on-your-local-machine}

Recommended: Use the detailed official Laravel install guide as your guideline to install Laravel on your local machine first. Here is the gist:

## Install the Laravel installer
{#install-the-laravel-installer}
composer global require laravel/installer

## Create a Laravel project
{#create-a-laravel-project}
laravel new {project_folder_name}
shell

In some cases Laravel is the framework for the actual software that runs on top - like with Statamic or October CMS.

# Install Laravel on the server

{#install-laravel-on-the-server}

Another option is to install Laravel directly on the environment like so:

1. Login to an environment by SSH
2. Run the above steps to install a Laravel project
3. Move all files in {project_folder_name} one level up again

We believe it's better to start with a local development environment first. A local first approach is easier for Git deployments too.

# Add your magic

{#add-your-magic}

Installing a plain Laravel will not do much. Now add your templates, design and content to make it shine. You probably don't need hosting right away. Most development can happen locally. Start thinking about deployment, once it's ready.

# Setup GitHub

{#setup-github}

Optional but recommended: To enable git deployments later on, init git and add GitHub as remote repo, either as a public or private.

• Deployment intro - concepts on fortrabbit
• Git intro - new to Git?

# Laravel setup

{#laravel-setup}

Prepare your local Laravel installation for fortrabbit.

# Get ready

{#get-ready-13}

• Local development environment up and running.
• Laravel installed locally best with attached Git repo.
• Install the fortrabbit GitHub App for automatic deployments.

# Create an app at fortrabbit

{#create-an-app-at-fortrabbit}

Create a new app in the fortrabbit dashboard. The wizard will guide you through the steps. You can connect the repo from GitHub.

# Software template

{#software-template}

If Laravel is detected or you have chosen it in the software list, the Laravel software template will be applied. This will pre-configure common ENV vars, build and post-deploy commands and set the root path to public.

# MySQL configuration

{#mysql-configuration}

Not all Laravel projects require a database connection. Some do. Just keep config/database.php as it is when you have chosen Laravel with the software template. The all CAPITAL configs in the config/database.php file will be replaced by the contents of the environment variables. For your local development setup you can populate the .env file with your local database credentials. See the ENV var topic as well.

This will enable the environment to connect to the database.

# Laravel deployment

{#laravel-deployment}

Setup automatic git deployment for your Laravel application hosted on fortrabbit.

# Get ready

{#get-ready-14}

1. Have a local development environment running
2. Local Laravel installation
3. Know about deployment features
4. Install the fortrabbit GitHub app with your GitHub account
5. Completed Laravel setup steps

# Initialize Git and add GitHub

{#initialize-git-and-add-github}

Here's an example using Git and GitHub CLI to set up a local repository and connect it to GitHub:

## Setup local git repo
{#setup-local-git-repo}
$ git init
$ git add -A
$ git commit -m 'Init'

## GitHub CLI to create/connect remote Git repo
{#github-cli-to-create-connect-remote-git-repo}
$ gh repo new
## Follow the steps
{#follow-the-steps}
## Push an existing local repository to github.com
{#push-an-existing-local-repository-to-github-com}
## Add as remote and assign current branch as 'origin'
{#add-as-remote-and-assign-current-branch-as-origin}
shell

At the end, the Git repo at GitHub is created and content already pushed. From now on you only need to run git add, git commit, and git push to send code changes to GitHub.

See the git deployment intro for more details on how to connect a local repo to a GitHub remote and enable automatic deployment using the fortrabbit GitHub App.

# Connect your GitHub repo with fortrabbit

{#connect-your-github-repo-with-fortrabbit}

If you already created an app on fortrabbit, connect the repository through the app settings. If not, create a new app on fortrabbit and set up the deployment:

Choose Laravel as the software preset. Use Git deployment and select the Git repository you created previously.

# Laravel deploymentbuild settings

{#laravel-deploymentbuild-settings}

Configure git deployment for your Laravel application hosted on fortrabbit.

# Get ready

{#get-ready-15}

1. Have a local development environment running
2. Local Laravel installation
3. Know about deployment features
4. Install the fortrabbit GitHub app with your GitHub account
5. Completed Laravel setup steps
6. Ready for Git deployment.

# Recommended Laravel build steps

{#recommended-laravel-build-steps}

If you import an already existing app from GitHub, we detect what is needed for deployment and you should have sensible defaults already.

But Laravel is versatile. It can act as a backend to exchange with a frontend or it can be used as a monolith. It might be extended with additional software. Therefore deployment build step pipeline options differ.

Laravel Livewire and Laravel Inertia (without Server Side Rendering) should work out of the box.

Because Inertia with SSR (Server Side Rendering) requires a node runtime, this is not currently supported by our platform.

Configure the build steps in the fortrabbit dashboard. These are commonly used:

# Composer build step

{#composer-build-step}

In almost all cases you will want to run Composer during deployment for Laravel based applications, see also Composer on fortrabbit.

composer install --no-dev --prefer-dist --no-interaction --no-ansi --no-progress
shell

# NPM build step

{#npm-build-step}

Vite is the default asset bundler for Laravel. For more details on using Vite, see Laravel's docs.

npm install
npm run build
shell

This will first install node dependencies. It will then compile the assets and place them in a build folder in the public directory. This folder is by default excluded from the repo in .gitignore.

# Post-deploy commands

{#post-deploy-commands-1}

Laravel requires a few directories to run correctly.

If you are using a database, you likely will want to run database migrations after you have deployed. We advice to run these post-deploy commands:

mkdir -p storage/framework/{sessions,views,cache}
php artisan migrate --force
shell

# Mostly done

{#mostly-done}

Now you should have setup an automatic deployment pipeline that will listen to changes on your GitHub repo branch and deploy these automatically, running the configured build steps.

# Database syncing

{#database-syncing}

Laravel applications with databases may require content syncing from your local development to the environment or the other way around. Please see MySQl import/export guides.

# Additional workflows

{#additional-workflows}

The fortrabbit platform is not limited to GitHub deployment. Your application might has runtime data such as uploaded assets that require syncing. Have a look at our deployment features in 'Code VS Content' for options and concepts.

# Laravel installer

{#laravel-installer}

Beside the artisan CLI, there is also a laravel installer CLI. It adds a convenience layer installing Laravel and some a lot of commands using the Laravel Cloud solution (bloatware). It can be installed as a global composer dependency.

• Laravel docs install

It's possible, but not recommended, to install and use the laravel installer CLI on the remote environment with fortrabbit. Better use it in your local development environment.

# Laravel tuning

{#laravel-tuning}

Configure Laravel and run on fortrabbit.

# Get ready

{#get-ready-16}

You have already started your Laravel on fortrabbit journey with the setup and continued over deployment. This is the final article to address most common configuration options to successfully run Laravel based applications on fortrabbit.

# Emoji support

{#emoji-support}

Laravel uses the utf8mb4 character set by default, which includes support for storing "emojis 🔥" in the database. You need to manually configure the default string length generated by migrations in order for MySQL to create indexes for them in your AppServiceProvider:

use Illuminate\Support\Facades\Schema;

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
  Schema::defaultStringLength(191);
}
php

# Manually running artisan migrate

{#manually-running-artisan-migrate}

While it's recommended to run database migrations automated each time you deploy, you can also do that manually. Log in by SSH and execute artisan:

## login and execute
{#login-and-execute}
$ ssh {{app-env-id}}@ssh.{{region}}.frbit.app
$ php artisan migrate --force
shell

Note: If APP_ENV is set to production - which is the default - the --force flag for migrate commands will override the confirmation prompt. You can also add this command to your composer.json to have it run automatically every time you push changes.

"scripts": {
  "post-install-cmd": [
    "php artisan migrate --no-interaction --force",
  ],
}
composer.json
json

With that in place, any time you deploy your code, database changes will be applied immediately. If no database changes are required, nothing happens, so it is safe to run all the time. Just make sure to test your upgrades and migrations locally first.

# Logging

{#logging-1}

Logs for Laravel are stored in storage/logs per default. Our software preset for Laravel however pre-configures log output to stderr and stdout so the logs become available in the dashboard - see the logging article.

If for some reason you can not access the logs in the dashboard, see if you can access these via SSH or SFTP.

See Laravel logging help for more.

# User sessions

{#user-sessions}

There are various session drivers available in Laravel. Whichever driver you end up using, will need to be specified in the environment variables. Add a new ENV var SESSION_DRIVER in the dashboard and give it the appropriate value. Since fortrabbit environments have persistent storage, you are able to use the default file driver for sessions.

To use the database driver, follow these steps:

## Create a migration for the session table  - locally
{#create-a-migration-for-the-session-table-locally}
$ php artisan session:table

## Apply the migration - locally
{#apply-the-migration-locally}
$ php artisan migrate

## Add, commit and push the migration file
{#add-commit-and-push-the-migration-file}
$ git add .
$ git commit -m "session migration"
$ git push

## Run the migration on the App via SSH remote execution
{#run-the-migration-on-the-app-via-ssh-remote-execution}
$ ssh {{app-env-id}}@ssh.{{region}}.frbit.app php artisan migrate --force
shell

# Queueing

{#queueing}

Laravel supports multiple queue drivers. One which can be used with fortrabbit out of the box is database, which simply uses your database connection as a queue:

## Create a migration for the jobs table locally
{#create-a-migration-for-the-jobs-table-locally}
php artisan queue:table

## Apply the migration locally
{#apply-the-migration-locally-1}
$ php artisan migrate

## Add, commit and push the migration file
{#add-commit-and-push-the-migration-file-1}
$ git add .
$ git commit -m "queue migration"
$ git push

## Run the migration on the App via SSH remote execution
{#run-the-migration-on-the-app-via-ssh-remote-execution-1}
$ ssh {{app-env-id}}@ssh.{{region}}.frbit.app php artisan migrate --force
shell

That's great for small use-cases and tinkering, but if your application handles very many queue messages you should consider using the key-value store.

Once you've decided the queue you want to use, just open config/queue.php and set default to either redis, database, sqs - or even better: set the QUEUE_CONNECTION environment variable accordingly in the dashboard.

To run php artisan queue:work in the background, spin up a new worker job and define the artisan command as a job.

Laravel offers two commands to process queues: queue:work and queue:listen. We recommend using queue:work, and not using queue:listen. This is because the queue:listen command boots the Laravel framework for each iteration, whereas queue:work boots the framework once and runs as a daemon. Using queue:work offers high memory and performance gains in comparison with queue:listen.

# Using artisan down

{#using-artisan-down}

artisan down generates the file storage/framework/down, which is then checked from your App's HTTP kernel with the CheckForMaintenanceMode middleware. You can run the command run the command via SSH or during deployment.

# Using Laravel Envoy

{#using-laravel-envoy}

Easy. Here is an Envoy.blade.php example:

@servers(['fr' => '{{app-env-id}}@ssh.{{region}}.frbit.app'])

@task('ls', ['on' => 'fr'])
  ls -lha
@endtask

@task('migrate', ['on' => 'fr'])
  php artisan migrate
@endtask
php

Then execute locally:

envoy run ls
envoy run migrate
shell

# Sending mail

{#sending-mail}

You can not use sendmail on fortrabbit but Laravel provides an API over the popular SwiftMailer library. The mail configuration file is app/config/mail.php, and contains options allowing you to change your SMTP host, port, and credentials, as well as set a global form address for all messages delivered by the library.

# Laravel

{#laravel-3}

Setup, deploy and tune Laravel based web applications on fortrabbit.

# Install Craft CMS local

{#install-craft-cms-local}

# Install and deploy run down

{#install-and-deploy-run-down}

1. Install Craft CMS locally ← you are here
2. Setup an app at fortrabbit
3. Deploy code via Git
4. Database syncing
5. Assets syncing

# Get ready

{#get-ready-17}

• Have a local development environment running. DDEV is recommended.
• Use the official Craft CMS install guide as your guideline.
• Skip this step when you have a Craft project running locally and a GitHub repo connected see below.

# Choose your install workflow

{#choose-your-install-workflow}

The way you will install Craft will set the course on how you will deploy Craft CMS here on fortrabbit:

# A - Create with Composer (recommended)

{#a-create-with-composer-recommended}

This is the recommended - more sophisticated - way. You will use Git and Composer in the Terminal. Run this command on you local machine to create a Craft CMS project to get started:

composer create-project craftcms/craft my-project
shell

See an error? Check your local development. Later on you can deploy Craft with Git on fortrabbit.

# B - Download zip file

{#b-download-zip-file}

Are you more "designer" and less "developer"? Just download Craft directly from the Craft website: craftcms.com/latest-v3.zip. Unpack that zip file to get to the actual project files.

# Install Craft CMS locally

{#install-craft-cms-locally}

Configure it to work on your local machine now. You have two options to install Craft:

# A - Terminal setup (recommended)

{#a-terminal-setup-recommended}

## 1. go into your local Craft folder
{#1-go-into-your-local-craft-folder}
$ cd my-project

## 2. run the terminal installer
{#2-run-the-terminal-installer}
$ ./craft setup
content/index.md
shell

This will ask you some questions, the defaults will work mostly, you can change these settings later.

# B - Browser setup

{#b-browser-setup}

You can also run the installer in the browser by visiting this address: http://{{host}}/index.php?p=admin/install in your browser. Substitute {{host}} with the host name of your local development environment.

# Add your magic

{#add-your-magic-1}

Installing a plain Craft CMS will not do much. Now add your templates, database structure, design, plugins and content to make it shine. We recommend to do this work mostly in your local development environment.

# Choose a code deployment workflow

{#choose-a-code-deployment-workflow}

Now is a good time to think ahead a bit. How do you plan to keep your local project and the remote app environment at fortrabbit in sync? Understand that Craft CMS basically consists of three parts that needs special treatment for deployment:

• Code - Craft CMS (vendor) + templates/config ← decide now
• Database - Content tables
• Assets - Volumes

# A - Git deployment (recommended)

{#a-git-deployment-recommended}

To connect your app environment to a GitHub repo set up one now. Init git and add GitHub as remote repo - either as a public or private. Here is an example using the GitHub CLI.

## Initialize a new git repository
{#initialize-a-new-git-repository}
git init

## Add files and commit
{#add-files-and-commit}
git add .
git commit -m "Init"

## Create a new public repository on GitHub from the current directory
{#create-a-new-public-repository-on-github-from-the-current-directory}
gh repo create --public --source=. --push
bash

We recommend to exclude asset volumes from Git to sync them up and down. In most cases this is already the case.

Skip this step if your code is already at GitHub, see Git provider integration for other providers with CI/pipeline/actions flows. If this fuzzy to you see:

• Deployment intro
• GitHub CLI guide
• Git intro

# B - SFTP / rsync deployment

{#b-sftp-rsync-deployment}

Later on you can upload Craft with SFTP.

# Craft CMS setup at fortrabbit

{#craft-cms-setup-at-fortrabbit}

# Install and deploy run down

{#install-and-deploy-run-down-1}

1. Install Craft CMS locally
2. Setup an app at fortrabbit ← you are here
3. Deploy code via Git
4. Database syncing
5. Assets syncing

# Install the fortrabbit GitHub App (recommended)

{#install-the-fortrabbit-github-app-recommended}

To enable automatic git deployments the fortrabbit GitHub App needs to be installed with your personal account. You can do and verify this with your account settings:

You can also do that later or skip it all together if you don't plan to use automatic git deployment, but SFTP upload.

# Create an app at fortrabbit

{#create-an-app-at-fortrabbit-1}

Create a new app in the fortrabbit dashboard. The wizard will guide you through the steps.

If you have the GitHub app connected and already a Git repo for your project you can connect the repo now. It will detect the software. If not, choose Craft CMS as software.

# Configuration

{#configuration-4}

If Craft CMS is detected or you have chosen it in the software list, the Craft CMS software template will be applied. This will pre-configure common ENV vars, build commands, post deploy commands and set the root path to web.

# Deploy Craft CMS to fortrabbit

{#deploy-craft-cms-to-fortrabbit}

# Install and deploy run down

{#install-and-deploy-run-down-2}

1. Install Craft CMS locally
2. Setup an app at fortrabbit
3. Deploy code via Git ← you are here
4. Database syncing
5. Assets syncing

# Git deployment

{#git-deployment-1}

You are mostly set when you have followed our Craft CMS guides so far. Your local Craft CMS project is connected with a Git repo at GitHub and you have created an app and connected it to your GitHub repo.

You can now trigger a code deployment by issuing git push or clicking the deploy button with the dashboard. This will update the GitHub repo and deploy the latest commit to fortrabbit. See the Git deployment intro on how this works. The fortrabbit platform is not limited to GitHub based deployment. See code access for available options.

# Deployment configuration

{#deployment-configuration}

Likely nothing to do here. Craft CMS is a pretty standardized application. In most cases the build commands are pre-configured through stack detection (scanning the repo) or software template.

# Deployment strategy

{#deployment-strategy-1}

Craft CMS projects are set to blend deployment strategy with replace patterns for all project config YML files in the config folder by default. This is because the Craft asset volumes can be placed anywhere in the file structure.

Consider using the replace strategy with exclude patterns for each asset volume. It works either way.

# Build commands

{#build-commands-2}

This setting is most likely pre-configured.

composer install # Always
npm run prod # If detected
shell

# Post deploy commands

{#post-deploy-commands-2}

This setting is most likely pre-configured. In most cases it's useful to run database migrations after deployment to apply changes from project config and migrate all changes.

php craft project-config/apply
php craft migrate/all
shell

# Database syncing with Craft CMS

{#database-syncing-with-craft-cms}

# Install and deploy run down

{#install-and-deploy-run-down-3}

1. Install Craft CMS locally
2. Setup an app at fortrabbit
3. Deploy code via Git
4. Database syncing ← you are here
5. Assets syncing

# Database configuration setup

{#database-configuration-setup}

In most cases, the Craft CMS installation on fortrabbit can already connect to the remote MySQL database through pre-populated environment variables.

But when initially installing Craft CMS on your fortrabbit environment, after Git deployment or SFTP upload your database is still missing. In most cases you want to import your local database now, to have database content and structure up.

Visit the MySQL import/export guides to learn how to sync the database up and down using different techniques.

# Database up

{#database-up}

1. Export the local database
2. Upload the the dumped .sql file
3. Import the database dump into the app environment database

• Database up via terminal
• Database up via MySQL GUI

# Database down

{#database-down}

In later live cycle stages of your project you more often likely would like to download the database.

1. Export the remote database
2. Download the dumped .sql file
3. Import the database in your local development

• Database down via terminal
• Database down via MySQL GUI

# Craft CMS assets handling

{#craft-cms-assets-handling}

# Install and deploy run down

{#install-and-deploy-run-down-4}

1. Install Craft CMS locally
2. Setup an app at fortrabbit
3. Deploy code via Git
4. Database syncing
5. Assets syncing ← you are here

# About Craft assets

{#about-craft-assets}

Craft CMS "assets" are user generated stuff: uploaded files, mostly images that lives in "volumes" — also see the official Craft docs on that.

# Assets and Git

{#assets-and-git}

When creating asset volumes in the Craft CMS control panel, their contents are by default excluded from Git, so that code and content are separated. However, if you've already created a directory in your web folder and you now reference that directory as the webroot of a volume you're creating, you will need to manually configure Git to ignore the files in it. To do this, add a file .gitignore in the volume's directory, with the following contents:

*
!.gitignore
gitignore

Another reason that assets should be managed and deployed independently from Git deployment, is that files uploaded to the environment would not be represented in Git, as Git deployment is a one way street.

# Options to sync assets

{#options-to-sync-assets}

There are two directions you want your assets to flow:

• UP — When you first developed Craft locally, you may want to upload all the images you already have locally to the environment;
• DOWN — When the environment is running in production for some time and the clients or editors have created content on the environment you want to download that, so your local version is in sync.

# 1 — Manage assets with rsync

{#1-manage-assets-with-rsync}

Give the good old rsync command line tool a try. It's easier than you think:

## Sync UP local assets with remote
{#sync-up-local-assets-with-remote}
$ rsync -av ./web/{your-asset-folder} {{app-env-id}}@ssh.{{region}}.frbit.app:web/
shell

Replace the path and your individual folder name with your own settings. Our rsync tutorial covers many useful rsync options, like excludes, --dry-run and --delete.

# 2 — Manage assets with SFTP

{#2-manage-assets-with-sftp}

Good old SFTP access is another valid way to to do it. Just fire up your SFTP client, log in to the App and manage the assets manually. Many SFTP clients are offering sync options, to keep local and remote files up-to-date.

# 3 — Outsource assets to a cloud storage

{#3-outsource-assets-to-a-cloud-storage}

The assets are not stored on the file system of the App any more; once the user uploads files, they get uploaded to external cloud storage like S3 (or the Object Storage here). Then, within the templates you hot-link all the files to the external storage. This more professional design helps to reduce load on the App. Look out for S3 Craft plugins to get started with this. Only use this if you really need it. Don't over-engineer.

# Craft CMS tuning

{#craft-cms-tuning}

Tips, tricks, best practices and advanced topics on how to run Craft CMS successfully on fortrabbit.

# ENV var configuration

{#env-var-configuration}

Craft CMS uses modern .env style configuration, see topic ENV vars. This means you can run your Craft locally and remotely without code or configuration file changes. Locally, your .env file will be modified and read. That file is not part of Git, you don't need it on fortrabbit.

# Manually setting ENV vars

{#manually-setting-env-vars}

The software templates will populate required ENV vars. If you didn't choose the Craft preset when creating the app or the ENV vars have been deleted, this is likely what needs to be set.

# Craft ENV vars for fortrabbit

{#craft-env-vars-for-fortrabbit}

CRAFT_DB_DRIVER=mysql
CRAFT_DB_PASSWORD=${FORTRABBIT_MYSQL_PASSWORD}
CRAFT_DB_DSN=mysql:host=${FORTRABBIT_MYSQL_HOST};port=3306;dbname=${FORTRABBIT_MYSQL_DATABASE}
CRAFT_ENVIRONMENT=production
CRAFT_SECURITY_KEY=LongRandomString
.env
apache

The syntax of the keys may differ by Craft CMS version. See ENV var usage for more details on aliases.

# Software template

{#software-template-1}

If Craft CMS is detected or you have chosen it in the software list, the Craft CMS software template will be applied. This will pre-configure common ENV vars, build and post-deploy commands and set the root path to web.

# Database setup

{#database-setup}

On fortrabbit the environment variables are seeded from the ones set in the fortrabbit dashboard (not from the .env file). If you chose Craft in the software preset when creating the app, all ENV vars at fortrabbit will already be pre-populated.

# Multi-environment configuration

{#multi-environment-configuration}

Craft embraces the idea of storing environment specific configurations in ENV vars. You can create groups in every config file. The top level array key maps with the CRAFT_ENVIRONMENT constant, which defaults to the CRAFT_ENVIRONMENT ENV var. With this flexible approach you decide which configurations are under version control to share with your team and which are not. We assume fortrabbit to be your production environment, so the CRAFT_ENVIRONMENT ENV var is set to production on remote and locally to dev.

## Local environment ENV
{#local-environment-env}
CRAFT_ENVIRONMENT=dev
shell

# Using .htaccess for redirects and to force https

{#using-htaccess-for-redirects-and-to-force-https}

Craft CMS comes with a predefined .htaccess file that lives inside the web folder. You can extend that with your own rules, like forwarding all requests to https or disabling access on the App URL. Please see our .htaccess articles for examples.

# X-Powered-By headers

{#x-powered-by-headers}

You probably think it's a good idea to disable headers that expose which PHP version and CMS you use. And we think so too!

However, internally we analyze this header to determine if it is a static or dynamic PHP response. With this information we generate two different metrics for the dashboard: PHP requests and Static requests. In config/general.php you can disable the header with 'sendPoweredByHeader' => false, (default: true). This is not required, since we strip all X-Powered-By headers eventually.

# Enabling dev mode

{#enabling-dev-mode}

Sometime while developing you might want to see some error output directly on your browser screen. That's what the devMode flag is for. See the Craft docs for more details.

DevMode is disabled by default via software template on fortrabbit as the installation is public. You can change that setting with by ENV vars in the fortrabbit dashboard:

# Don't allow updates in production

{#don-t-allow-updates-in-production}

Craft CMS has the option to run updates directly from the Craft Control Panel. A client or editor might be tempted to use that update button in production. This is not a good idea. On fortrabbit Git is a one-way street, so any changes on the App itself can not easily be ported back to the local development environment. Also composer update might be triggered on the App and that can lead to performance problems.

So it's better to prevent the shiny "update" button from showing up at all. You can do that in your Craft configuration in the general settings with the allowUpdates flag.

allowUpdates is disabled by default via software template too. Change by ENV var.

# Don't allow admin changes in production

{#don-t-allow-admin-changes-in-production}

We highly recommend not making any admin changes to your production environment (fortrabbit) at all. Only do editorial changes. Have one single source of truth and only one direction (up). Please also see the official Craft CMS docs on that.

Otherwise you can run into trouble: Imagine you make changes to the database structure, by adding tables for example, changing the field layout in production. Now you don't have the changes locally. But you deploy other new changes from local to production. This might overwrite the project.yml in production and therefore will roll back your changes. Your local development should be your master in applying design and functional changes.

allowAdminChanges is disabled by default via software template too. Change by ENV var.

# Change the control panel URL

{#change-the-control-panel-url}

"Security through obscurity" is a widely discussed concept. We suggest to obscure the control panel URL of your Craft installation, just because you can. Do so with the cpTrigger setting. If you don't set this value it defaults to admin.

return [
  'cpTrigger' => 'godmode'
];
php

# MySQL table prefixes

{#mysql-table-prefixes}

If your local Craft installation contains a table prefix, the one on the fortrabbit app should be the same. You can set the table prefix, locally in your .env file, and on fortrabbit with the App's ENV vars like so:

## Example Table prefix
{#example-table-prefix}
CRAFT_DB_TABLE_PREFIX=craft_
.env
apache

# Craft CLI

{#craft-cli}

Craft CMS comes with a built in command line interface which can be called from the console. You can also run it one the environment itself like so:

## Call Craft CLI via php
{#call-craft-cli-via-php}
php craft
shell

Not all Craft CLI commands are safe to run in production. Our recommendations:

• setup/* — Don't, intended to run locally only
• update/* — Don't, if you deploy using git or using project config
• clear-caches/* — Don't, unless you have a good reason
• resave/* — Sometimes needed
• project-config/sync — Only needed if it's not part of your deployment
• migrate/all — Only needed if it's not part of your deployment
• backup/db — Useful to make a database backup. Can harm performance
• restore/db — Useful if you need to revert the DB to a previous state

# Logging

{#logging-2}

Without configuration, Craft CMS will pipe PHP errors to storage/logs/web.log.

The Craft CMS stream log location can be set to stderr and stdout by setting the environment variable CRAFT_STREAM_LOG=true. This is pre-populated when choosing Craft CMS in the software chooser while creating the app. When the ENV var is present and true, Craft CMS error logs can be accessed through the fortrabbit dashboard.

# Sending mail

{#sending-mail-1}

Use an external third party transactional mail provider to send emails. Pixel & Tonic (Craft CMS creators) maintain a plugin for Postmark. With that plugin installed you can easily set it up.

See our quirks article on limits sending emails. Also see transactional mail provider integration.

# Licensing Craft CMS

{#licensing-craft-cms}

Craft CMS is not all free. To enable the good parts you need to obtain a license from Pixel & Tonic (the folks building Craft CMS). A Craft CMS license is limited to a single domain, which means you can only access the Craft CP with one domain - otherwise you'll see a warning. You might have used the fortrabbit App URL for development and you might have used that to connect your Craft CMS licence with. You can change the domain of a Craft licence as well, if for instance you started with our App URL but now want to use your own domain with your Craft ID — over at https://console.craftcms.com/.

# Craft storage folder

{#craft-storage-folder}

We found a couple of Craft CMS installations blowing up the storage folder. This is often related to plugins and configuration. Some search engine bot might try to crawl all pages, causing a faceted search plugin to create gigabytes of template fragments. Some other plugin may just write very verbose logs. Best, make sure to configure your website to not cause such issues, beside the storage, such issues have impact on performance.

# Craft CMS performance tips

{#craft-cms-performance-tips}

All about performance problems with Craft CMS and how to run Craft CMS fast on not only on fortrabbit.

# Get ready

{#get-ready-18}

Please check out our general PHP performance section article as well before looking at specific Craft CMS related performance issues.

# MySQL related issues

{#mysql-related-issues}

The amount and complexity of database queries, as well as the size of your dataset, have a direct impact on the performance of your site. While the queries you create in your templates are more or less your responsibility, there are other queries that you can't directly control. We have analyzed hundreds of Craft sites to understand common query patterns. Especially sites with large amounts of data (Entries, Fields, etc) and frequent content updates suffer from these "hidden" queries.

# How Craft CMS makes use of the database

{#how-craft-cms-makes-use-of-the-database}

The beauty about Craft CMS is that you can get by with just writing TWIG templates — you don't need to write a single MySQL query yourself. Within the TWIG templates there is an abstraction layer to create a query to the database. That's a dangerous tool at your proposal since there a couple of important not so well known things about it.

• Craft is running database queries all the time, completely blocking
• Craft is joining all the time, since everything is an element, that can get slow quickly

There is much more to know, exceeding the scope of this post. Here are the most important parts:

# How the MySQL dataset size matters

{#how-the-mysql-dataset-size-matters}

The flexible content model in Craft CMS makes it easy to write code that makes either too many database queries and/or slow queries in MySQL. Most commonly poorly performing MySQL queries are easy to miss during development, since with local development you commonly only have a small dummy dataset.

Also mind your local machine has a different hardware than your hosted website. In production later on, when all the pages are published and a couple of blog posts have been written, the underlying issues will become more visible. MySQL query runtime is not just adding up, it's multiplying.

# General tips on MySQL performance with Craft CMS

{#general-tips-on-mysql-performance-with-craft-cms}

Prevention is better than cure! If you're reading this, the odds are you may already have run into performance issues on a Craft CMS project. But if you're just starting out with a new project, being aware of how Craft models content behind the scenes can spare you a lot of time-consuming debugging later on.

Look out for code smell: Common Craft performance anti-patterns include:

• where conditions on custom fields
• Queries in nested loops (N+1)
• Order on custom fields orderBy

Optimizing database queries

• Official Craft documentation on Eager loading

Database indexes

• How does database indexing work? on StackOverflow
• What columns are indexed in Craft (source code link)

# Use the Craft Debug Toolbar

{#use-the-craft-debug-toolbar}

The YII toolbar is integrated with Craft CMS. It (see article by NYS+107) provides useful information about which queries you run and how long it takes to execute them. Rule of thumb: if you run more 50 queries you should do something about it. It's easy to use and can help you to find slow queries with low efforts while developing.

• Yii debug toolbar documentation

# Use the Relax plugin

{#use-the-relax-plugin}

Fortunately, there is a plugin called Relax that takes care it. We have released it for free to help our clients and the broader craft community.

s## Issues related to blocking PHP requests

Like described above, a PHP process is busy as long as it is executing. No one will pick up the phone (return a web page) when all the PHP processes are busy. There are various reasons why PHP requests are busy or are running for too long.

Examples from support:

• A plugin is querying an external service in a blocking way and the answer is taking too long
• The database is overwhelmed by too many or too expensive queries

# Memory/CPU related issues

{#memory-cpu-related-issues}

Sometimes there is just not enough memory or computing power to perform a calculation. This is often the case when image transformations are involved or when a lot of concurrent requests hit your App.

Examples from our support:

• Image transformations are used extensively to create too many versions of a certain image in too many sizes and formats
• Thousands of queue messages need to be processed, often caused by bulk-updates
• Bots crawl the entire site including non-existing pages which are not cacheable

# Craft queue related issues

{#craft-queue-related-issues}

Craft has its own queue implementation. You can see and control it from the Craft CMS Control Panel. The craft-async-queue plugin helps to improve the performance of the Craft queue. Hanging queues are a bad sign.

To see if performance problems are related to the Craft queue, check if one is running and delete it from the Craft Control Panel. This of course is only possible when the website is still responding.

Look for errors in the Craft queue.

# Disk I/O related issues

{#disk-i-o-related-issues}

Sometimes the file system disk operations are slowing down a website. This can be when your website is accessing the disk a lot.

Examples from support:

• Using Craft's Twig {% cache %} tag missing the key attribute can lead to thousands of cache files with the same data and a terrible cache-hit-rate
• The website is configured to write verbose log files

# Static files in /templates

{#static-files-in-templates}

We've seen this many times. Developers put static assets like .css and .js in the /templates folder next to the twig templates. Craft delivers those files, but it creates massive overhead. Instead you should always put static files in /web/some-dir/ to prevent any PHP execution when delivering those files.

# Twig cache tag

{#twig-cache-tag}

Craft's {% cache %} tag is a good thing to prevent execution of expensive queries over and over again, however it's very important to use it wisely. Make sure to use a specific cache key, otherwise you risk an inefficient Cache-Hit-Rate and lots of cache items filling up the disk or Memcache.

# General configuration related issues

{#general-configuration-related-issues}

Performance problems are also often caused by general misconfiguration. Examples from support:

• Not having set the environment to production - this can contribute to bad performance since in development mode more things are getting logged
• A plugin is (mis)configured to blow up the database

# Fixing and mitigation

{#fixing-and-mitigation}

In our experience, problems are often unique to individual projects. So there is no silver bullet to make things fast. There are however some general things you can do:

# Check and maybe block certain requests

{#check-and-maybe-block-certain-requests}

Depending on your configuration, checking the source of requests might help you to understand where resources are getting spent.

Examples from support:

• A deep content structure, creating an endless amount of possible pages that are getting crawled by web crawlers. Block certain bots or rethink your content structure.
• Common bot attacks targeting WordPress requesting a wp-login page which results in a 404 page, but that page is not cached or creating an expensive database query, so that the requests are generating a lot of load.
• The Blitz plugin is configured to flush the cache every hour, which triggers cache warming. See this Twitter thread.

# Caching to the rescue

{#caching-to-the-rescue}

Caching can be highly beneficial, particularly in providing the fastest possible end user experience but shouldn't be a crutch. Instead, it's usually better to find and remediate the root cause of the issue where possible.

Doing caching wrong can also be the problem itself.

You want repeating parts of the website or full pages to be cached and rendered without hitting PHP or a database query touching the server. A "mega menu" is a perfect example and an opportunity for fragment caching. It creates the same database queries (sometimes 50+) for every page.

There are multiple approaches for caching in Craft CMS including:

• Native Twig cache tag - the out of the box tool for fragment caching, be careful when using for side effects, more above.
• Blitz Craft CMS plugin - a popular full cache plugin with tons of options
• Upper Craft CMS plugin (by fortrabbit co-founder Oliver Stark) - integrates reverse proxies (Cloudflare, Vanish, KeyCDN) with Craft

Please be careful about caching. In our experience, this is probably causing more problems than it is solving.

# Further reading

{#further-reading}

Ryan has some good educational video content (some paid, some free) on related topics:

• About the Yii debug toolbar
• Debugging in Twig and Craft
• Profiling with Xdebug live stream
• Debugging with Xdebug course

# Updating Craft CMS

{#updating-craft-cms}

Always use the latest software version for security reasons. Here are some strategies to best keep Craft CMS up-to-date.

# Update your local development environment first

{#update-your-local-development-environment-first}

Your local development environment is where changes are applied and tested first. Please update your local Craft CMS installation first and apply updates by deploying as a second step. That way you make sure that your environments are in sync.

The config/general.php file we use in our setup guide sets allowUpdates to false: this prevents plugin and Craft core updates from the Craft Control Panel in the production environment.

It's a common mistake we see. Make sure your environments are in sync and you don't mess with updates and installing plugins on the environment itself.

Here are the options to update Craft CMS and Craft plugins. Make sure to also check out the official guides on the topic.

# A) Update Craft using the Control Panel - simple

{#a-update-craft-using-the-control-panel-simple}

1. Login to the Craft CMS Control Panel of your local Craft installation
2. Go to Utilities > Updates
3. Click the "Update all" button

This will update your local development environment to the latest versions of Craft CMS as well as all plugins. After testing changes, deploy updates to your production App (see below).

# B) Update Craft using the Craft CLI - advanced

{#b-update-craft-using-the-craft-cli-advanced}

Run the following command in the terminal on your computer locally in the root folder of the Craft project:

./craft update all
shell

This will update Craft, as well as all dependencies. For a dry run just type ./craft update, that will list the available updates.

# Deploying Craft updates

{#deploying-craft-updates}

After you have tested the updates locally you can deploy them to your environment at fortrabbit. Here are your options:

# A) Deploying updates with Git

{#a-deploying-updates-with-git}

1. Add and commit the local changes (composer.json, composer.lock, project.yaml …)
2. Deploy the changes by git push to trigger deployment

During the Git deployment composer install will likely run automatically. This way your local Composer changes get applied on the remote.

# B) Uploading updates with SSH/SFTP based workflows

{#b-uploading-updates-with-ssh-sftp-based-workflows}

Continuous development with an SFTP workflow is a hassle. One strategy is to upload the changed files from local to the App. Another strategy is to re-run the very same steps that have been done locally on the App itself.

# Database migrations

{#database-migrations}

In most cases when updating a database migration is required. This will upgrade the database table structure to match the latest updates. It will be carried out when running the updates locally. But it's an extra step required to be done with your fortrabbit environment. All essential Craft CMS settings are stored in the project.yaml files.

Here are your options to run migrations:

# A) Database migrations as a build step (recommended)

{#a-database-migrations-as-a-build-step-recommended}

When you have chosen Craft CMS in the software preset while creating the environment, the following two commands are part of your deployment build steps.

php craft project-config/sync
php craft migrate/all
shell

# B) Craft Copy and Craft auto-migrate

{#b-craft-copy-and-craft-auto-migrate}

We have also created a little auto-migrate package - see it on GitHub - which triggers migrate/all and project-config/sync every time composer install runs, which means it runs every time you deploy using git.

## Install the package (locally)
{#install-the-package-locally}
$ composer require fortrabbit/craft-auto-migrate
shell

With that in place, every time you deploy your code, database and project config changes will be applied. If no changes are required, nothing happens, so it is safe to run all the time. Just make sure to test your upgrades and migrations locally first. The package is also dependency of our Craft Copy deployment tool plugin. So when you have that installed, it will always run on git push which is the equivalent to ./craft copy/code/up - one of the commands the plugin provides.

# C) Trigger a database migration by visiting the Control Panel URL

{#c-trigger-a-database-migration-by-visiting-the-control-panel-url}

After applying updates on your fortrabbit Craft App, you might see a "Service unavailable" message. Visit the control panel URL {{app-env-id}}.frbit.app/admin or whatever you have set) and you might see a message saying that database changes need to applied. Click the "apply" button to run the migration manually.

# D) Manually run database migrations on the App via Craft CLI

{#d-manually-run-database-migrations-on-the-app-via-craft-cli}

You can trigger the changes via the Craft CLI in the terminal via SSH:

## After being logged in to the environment
{#after-being-logged-in-to-the-environment}
php craft migrate/all
php craft project-config/apply
shell

# Running a headless Craft CMS on fortrabbit

{#running-a-headless-craft-cms-on-fortrabbit}

Craft can be used as a headless CMS. Here is how to on fortrabbit.

# Intro

{#intro-3}

With Craft CMS headless mode you have a Craft CMS installation that consists only of the backend without any server-side Twig templates. In addition you create another application, usually with a JavaScript framework (Next, Nuxt, React, Vue …) that will fetch content using the built-in GraphQL API and render it on the client-side in the browser.

# Headers

{#headers}

By default HTTP responses with content type text/html, text/css and text/javascript are gzipped. When you use Craft in headless mode as a GraphQL or REST API, the content type is application/json. In the article about GZIP compression you learn how to enable it for other content types.

# Related

{#related-2}

• Headless considerations
• Craft CMS help on headless mode

# Using Craft CMS plugins

{#using-craft-cms-plugins}

We highly recommend to not install plugins directly on your production environment. Instead install plugins locally first, then deploy that state to get them installed on the environment as well.

# Install Craft plugins from the control panel

{#install-craft-plugins-from-the-control-panel}

This method let's you conveniently discover, install and also "activate" (pay for) the plugins right in place.

1. Visit the control panel of your local Craft installation
2. Visit the plugin store
3. Search, install and activate plugins

Plugins installed via the plugin store are "pinned" with composer.json and must also be updated through the same mechanisms. Please also see our updating instructions.

# Install Craft plugins via command line

{#install-craft-plugins-via-command-line}

This is a more advanced method to install plugins directly from the command line:

## 1. Add the plugin to Composer:
{#1-add-the-plugin-to-composer}
$ composer require {vendor/package-name}

## 2. Install the plugin via Craft CLI
{#2-install-the-plugin-via-craft-cli}
$ ./craft plugin/install {plugin-handle}
shell