# Report Abuse Source: https://forge.laravel.com/docs/abuse Help us keep Laravel Forge safe by reporting any abuse, security concerns, or violations. Please email us at [security@laravel.com](mailto:security@laravel.com) # API Source: https://forge.laravel.com/docs/api Learn how to get started and interact with the Laravel Forge API. ## Introduction Laravel Forge provides a comprehensive JSON API that allows you to programmatically manage your Forge servers and sites. To learn more, please review the [Forge API documentation](/docs/api-reference/introduction). The official Laravel Forge [PHP SDK](/docs/sdk) provides an expressive interface for interacting with Forge's API and managing Laravel Forge servers. ## Managing API tokens ### Create a new API token To create an API token, navigate to your account dashboard and click "API". Click "Create token", provide a name for the token, an optional expiration date, and select the scopes you wish to assign to the token. Finally, click "Add token". ### Delete an API token To delete an API token, navigate to your account dashboard and click "API". Locate the token you wish to delete, click the action dropdown next to the token, and select "Delete". Deleting an API token is permanent and cannot be undone. Any applications or services using the deleted token will no longer be able to access the Laravel Forge API. # Filtering & Sorting Source: https://forge.laravel.com/docs/api-reference/filtering Learn how to filter and sort data in the Laravel Forge API. ## Filtering Several endpoints support filtering to allow you to retrieve only the data you need. For example, you can filter servers by name: ```http theme={null} GET /orgs/coinfly/servers?filter[name]=conifly-web ``` Individual endpoints may support filtering on different fields. Check the documentation for the specific endpoint you are working with. ## Sorting You can sort the results of an endpoint by passing the `sort` parameter. You must provide a comma-separated list of fields to sort by. ```http theme={null} GET /orgs/coinfly/servers?sort=php_version ``` To reverse order the results, prefix the field with a hyphen (`-`): ```http theme={null} GET /orgs/coinfly/servers?sort=-php_version ``` Individual endpoints may support sorting on different fields. Check the documentation for the specific endpoint you are working with. # Introduction Source: https://forge.laravel.com/docs/api-reference/introduction Introduction to the Laravel Forge API. The Laravel Forge API allows you to programmatically interact with your Laravel Forge account and manage your organizations, servers, sites, and other resources. ## Base URL The base URL for the Laravel Forge API is: ``` https://forge.laravel.com/api ``` ## Authentication The Laravel Forge API uses token-based authentication. You can generate an API token from your [Laravel Forge account settings](https://forge.laravel.com/profile/api). Once you have your token, include it in the `Authorization` header of your API requests as follows: ```http theme={null} Authorization: Bearer YOUR_API_TOKEN ``` ## Headers All API requests must include the following headers: ```http theme={null} Accept: application/json Content-Type: application/json ``` ## Errors The Laravel Forge API uses standard HTTP status codes to indicate the success or failure of an API request. Common status codes include: | Status Code | Description | | ----------: | :-------------------------------- | | `200` | Success | | `201` | Created | | `204` | No content | | `400` | Bad request | | `401` | No valid API key was provided. | | `403` | Forbidden | | `404` | Not found | | `422` | Unprocessable entity | | `429` | Too many requests | | `500` | Internal server error | | `503` | Forge is offline for maintenance. | # Pagination Source: https://forge.laravel.com/docs/api-reference/pagination Learn how to handle pagination in the Laravel Forge API. All API endpoints that return multiple items support cursor-based pagination. By default, `30` items are returned per page. You can specify the number of items to return per page by passing the `page[size]` parameter. ```http theme={null} GET /orgs/coinfly/servers?page[size]=30 ``` Paginated responses include `meta` and `links` objects for navigating results: ```json theme={null} { "data": [...], "meta": { "per_page": 30, "next_cursor": "eyJzZXJ2ZXJzLmlkIjozMCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ", "prev_cursor": null }, "links": { "next": "/api/orgs/coinfly/servers?page[size]=30&page[cursor]=eyJzZXJ2ZXJzLmlkIjozMCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ", "prev": null } } ``` To fetch the next or previous page, use the `page[cursor]` parameter with the value from either `meta.next_cursor` or `meta.prev_cursor` from a paginated response. ```http theme={null} GET /orgs/coinfly/servers?page[size]=30&page[cursor]=eyJzZXJ2ZXJzLmlkIjozMCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ ``` Note that `meta.prev_cursor` will be null on the first page and `meta.next_cursor` will be null on the last page. # Rate Limiting Source: https://forge.laravel.com/docs/api-reference/rate-limiting Learn about rate limiting in the Laravel Forge API. The Laravel Forge API implements rate limiting to ensure fair usage and protect against abuse. The default rate limit is set to **60 requests per minute** per authenticated user. API responses include the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers to provide information about the rate limit. ## Requesting a higher rate limit If the default rate limit is insufficient for your workflow, you can request an adjustment by contacting our support team at [forge@laravel.com](mailto:forge@laravel.com). Please include a description of your use-case so we can properly review your request. # Relationships & Includes Source: https://forge.laravel.com/docs/api-reference/relationships Learn about relationships and includes in the Laravel Forge API. ## Relationships Some resources in the Laravel Forge API have relationships to other resources. Available relationships can be found in the `relationships` object within each resource response. ```json theme={null} // ... { "relationships": { "tags": { "data": [ { "type": "tags", "id": "" } ] } } }, // ... ``` ## Includes Relationships can be included in the response by using the `include` query parameter: ```http theme={null} GET /orgs/coinfly/servers/1?include=tags ``` Multiple relationships can be included by separating them with a comma: ```http theme={null} GET /orgs/coinfly/servers/1/sites?include=latestDeployment,tags ``` # Changelog Source: https://forge.laravel.com/docs/changelog New updates and improvements to Laravel Forge. ## Multiple source control connections You can now connect multiple source control accounts per provider. ## Ubuntu 26.04 Ubuntu 26.04 LTS is now available across every server provider. Ubuntu 22.04 is no longer offered for new servers. * **In-app notifications**: Notification preferences now cover in-app notifications as well as email. * **More notification controls**: Successful deployment and stale server notifications can now be toggled individually. * **Brotli compression**: The Brotli modules are now compiled and loaded on new servers, ready to enable in your Nginx configuration. * **Custom Git migration**: Sites using a custom Git repository can now switch to a supported source control provider. * **Git switching via the API**: Added an API endpoint for changing a site's repository and deploy branch. * **Activity feed API**: Added API endpoints for organization and server activity feeds. * **MySQL 8 and PostgreSQL 13 retired**: Both versions have reached end of life and are no longer available for new database installations. * Fixed a 500 error when creating a site with an invalid site name through the API. * Fixed provisioning for OpenClaw servers. * Fixed redirect rules being dropped when a site's Nginx redirect file was rewritten. * Fixed the API PHP version endpoints returning data that the requesting account should not see. * Fixed adding database users on MariaDB 11.4. * Fixed the API allowing the same PHP version to be installed more than once. * Fixed the API site update endpoint not provisioning PHP version changes. * Fixed background process status being reported inconsistently. * Fixed long repository names overflowing the sites list. ## Log viewers Server and site log viewers now support search, a full-screen view, loading older entries as you scroll, and live tailing. * **Notification preferences**: You can now choose which email notifications you receive, with per-notification control and an option to turn off all email notifications. * **API rate limits**: Rate limit usage is now visible in the dashboard, along with guidance on requesting an increase. * **Graceful PHP-FPM reloads**: The server PHP service endpoint now supports a graceful reload action. * **Command exit codes**: The site command API resource now includes the command's exit code and details. * **Zero downtime releases via API**: The number of retained releases can now be updated through the API. * **Backups for all databases**: Database backups can now include every database on the server. * **Password confirmation for role changes**: Changing a role now requires password confirmation. * **Copyable confirmation text**: Confirmation dialogs that ask you to type a resource name now let you copy it. * **Deployment alerts clear automatically**: Deployment failure alerts are cleared after a successful deployment. * Fixed GitHub deployments failing to trigger. * Fixed incomplete deployments caused by purging old releases. * Fixed a 500 error when creating a site on a load balancer. * Fixed the Nginx Logrotate configuration. * Fixed backups being pruned when retention periods conflicted. * Fixed the managed database backup time selector always showing 5:30 AM. * Fixed the API not enforcing the correct domain redirect rules. * Fixed the sites list showing the wrong PHP version. * Fixed the command palette becoming stale when switching sites. * Fixed disabled dropdown items still being clickable. * Fixed plan downgrades not being applied. * Fixed repository names not being formatted correctly when a full URL was entered. * Fixed the account SSH key form not showing a user selector. ## Managed caches Valkey is now available as a fully managed cache option, provisioned directly from the dashboard. ## Object storage Forge now offers managed object storage. Create and manage buckets directly from the dashboard. * **Redesigned email notifications**: Transactional emails across Forge, including provisioning, alerts, backup failures, recipe runs, certificate renewals, and billing notices, have been redesigned for clarity and consistency. * **List site certificates API**: Added an API endpoint for listing a site's SSL certificates. * **Site search**: Added a search field to the site dropdown in the tab bar for quickly jumping between sites. * **Reverb environment sync**: Reverb environment variables are now updated automatically when HTTPS is enabled or disabled. * Fixed deploy branch changes not updating the site's git configuration. * Fixed deployment settings showing the wrong server SSH key fallback. * Fixed server heartbeat notifications being sent for deleted or unassigned organizations. ## Managed MySQL 8.4 Managed database clusters can now be provisioned with MySQL 8.4. This adds MySQL alongside PostgreSQL as a fully managed option in Laravel VPS, with the same observability, automated backups, and read replicas. * **Managed database alerts**: Added an interface for configuring and reviewing alerts on managed database clusters. * **Managed database user permissions**: Managed cluster users can now be limited to selected databases during creation. * **PHP 8.5 default**: Newly provisioned servers now use PHP 8.5 by default. * **DigitalOcean re-authentication**: DigitalOcean OAuth credentials can now be re-authenticated when the token expires. * **Horizon environment reloads**: Horizon is now automatically restarted when site environment variables change. * **Certificate cloning context**: The certificate clone selector now shows the source site ID and server name to make picking the right certificate easier. * Resolved PHP provisioning failures by switching the package source to the maintained `ppa.setup-php.com` mirror and cleaning up stale `ondrej/nginx` PPA entries during each provisioning run. * Fixed Bitbucket deploy hooks failing to trigger deployments. * Resolved provisioner timeouts caused by Launchpad latency. * Fixed a site's `project_type` not staying in sync when its type was changed. * Fixed overflow on the site overview page and improved the layout of the deployment cards. * Fixed an issue preventing the logrotate path from being updated when a site's primary domain changed. * Resolved an issue preventing SSL certificates from taking effect until Nginx was manually reloaded after enabling or disabling them. * Fixed an issue preventing unique site names from being enforced on worker servers. ## PHP 8.5 PHP 8.5 is now generally available. * **Multiple certificates per domain**: You can now install multiple SSL certificates on the same domain, with one certificate active at a time. This makes it easier to stage replacement certificates before switching over. * **Certificate renewal monitoring**: Customers are now alerted when SSL certificates fail to renew on time, helping prevent expired certificate downtime. * **Managed database team sharing**: Managed database clusters can now be shared with teams. * **Server API v2 endpoints**: Added `PUT /servers/{server}` for updating server attributes and `GET`/`PUT /servers/{server}/network` for viewing and syncing network peers. * **Deploy key API**: Added a deploy key creation endpoint to API v2. * **Background process API**: Added a `site_id` parameter to the Create Background Process endpoint. * **Load balancer keepalive**: Added support for the `keepalive` directive on load balancer configurations. * **Nginx reset to default**: Added a "Reset to Default" button to the Nginx configuration modal. * **Server metrics**: Server metrics are now fetched concurrently for faster page loads. * **Responsive UI**: Improved responsive layouts across the dashboard. * Fixed incorrect copy on the certificate expiry display. * Fixed server heartbeat notifications being sent to all organization-owned channels. * Resolved recipe scripts ending with a heredoc delimiter failing to execute. * Resolved primary domain changes not handling custom root paths correctly. * Resolved the Laravel VPS built-in terminal halting when editing files with VIM. * Fixed an expired GPG key error during MySQL installation. * Fixed the PHP CLI not being updated when switching PHP versions. * Fixed backup display time issues. ## Managed databases Laravel VPS now supports managed databases powered by PostgreSQL. Create, monitor, and manage database clusters directly from Forge with built-in observability, read replicas, and automated backups. * **Ubuntu 26.04 compatibility**: Servers self-upgraded to Ubuntu 26.04 or newer are now properly recognized by Forge. * **Managed database validation**: Improved form validation and error handling for managed database clusters. * **Dashboard performance**: Improved performance across server, site, and organization overview pages. * **Load balancer API**: Added an API endpoint for creating sites on a load balancer. * **Backup API**: Added `database_ids` attribute to the backup API resource. * **Server API**: Added `slug` attribute to the API server resource. * **API rate limiting**: Added rate limiting for command API requests. * **Server deletion safety**: Servers are now only removed from Forge after being successfully removed from the provider. * **Backup configuration**: Databases cannot be removed from a backup configuration when it is the last one attached. * **Envoyer deployment indicator**: Sites deployed via Envoyer are now clearly labeled in the UI. * **Scheduled job cleanup**: Scheduled jobs are now automatically removed when their associated site is deleted. * **Role permissions visibility**: Mandatory permissions are now visible but non-removable when editing custom roles. * **SSL certificate logs**: SSL certificate failure logs are now exposed for easier debugging. * **Tooltip accessibility**: Replaced tooltips across the dashboard with accessible alternatives that include proper ARIA labels and keyboard support. * **Keyboard accessibility**: Notification center actions are now reachable via keyboard navigation. * Fixed backup size always showing as zero. * Fixed managed database cluster permissions for team members. * Fixed metrics for DigitalOcean servers when data points are missing. * Fixed deleting managed database users and databases. * Fixed networking changes not reflecting in the UI. * Fixed duplicate warning icon on the server sidebar. * Fixed deleting servers from provider via API v1. * Fixed Nginx configuration for new Nuxt and Next.js sites. * Fixed backup scheduled time not being applied correctly. * Fixed responsive navbar layout and background processes card. * Fixed deployment retention period not being applied correctly. * Fixed git pull commands with arguments failing. * Fixed deployment failure notifications containing null output. * Fixed wildcard subdomain validation. * Resolved recipe execution hanging when using curl piped to bash. * Fixed zero-downtime deployments failing in certain conditions. * Fixed team invitation details being scoped to all organization users instead of the current invitation. * Resolved PM2 configuration fallback failing during deployment when provisioning had previously failed. * Fixed team members receiving notifications for servers outside their team. * Fixed deployments crashing for legacy sites without a type. * Fixed creating and updating custom roles. * Fixed server key permissions not being applied correctly. * Fixed npm credential scopes not being handled correctly during site creation. * Resolved a silent exception when repository access was lost. * Fixed GitLab nested repository names not being handled correctly. ## npm private packages You can now configure npm credentials at the server and site levels to install private packages during deployments. Forge manages the `.npmrc` configuration automatically, supporting scoped registries like GitHub Packages and custom registries. * **Vultr VX1 servers**: Added support for Vultr VX1 server types when provisioning servers. * **Server unlinking**: Added the ability to unlink a server directly from the delete server modal. * Fixed SSL certificates displaying incorrect expiry dates. * Resolved an issue preventing recipes from being unselected after selection. * Fixed wildcard domains being treated as literal values on legacy sites, causing site path and Nginx configuration conflicts. * Resolved storage provider credential fields being autofilled by the browser. * Fixed duplicated heartbeat notifications. * Fixed the add server to network modal layout issues. ## MySQL 9.x support MySQL 9 is now available as a database option when provisioning new servers. * Resolved an issue with Laravel VPS servers that do not have a private hostname. * Fixed an issue preventing the creation of scheduled jobs. * Fixed Aikido not finding the correct workspace. * Resolved an issue with database syncing creating duplicate entries. ## OpenClaw server type You can now create OpenClaw servers on Laravel VPS. * **Command palette filtering**: Improved the accuracy of command filtering. * **Server list**: Displayed the OS version in the server list. * Resolved an issue preventing the delivery of email notifications when a scheduled job's heartbeat is in a failing state. * **MySQL 8.4**: Updated the default MySQL version for newly provisioned servers from MySQL 8.0 to MySQL 8.4. * **Power cycle for Laravel VPS**: Added the ability to power cycle Laravel VPS servers. * Resolved an issue with duplicate backup configurations resulting in failed backups. * **Server configuration UI**: Improved the server configuration modal to clarify which options are included in advanced settings. * Fixed the log viewer to refresh after selecting "Delete contents" in the dropdown. * Removed the corresponding PHP-FPM pool configuration and service when a site stops using a PHP version. * Updated SSH keys for isolated users. * Fixed a bug causing the PM2 process to fail after changing primary domain on NextJS sites. * **Hetzner S3**: Hetzner S3 object storage is now available as an option for database backups. * Fixed a bug preventing users from scrolling modals across Forge. * Fixed display issues in the create certificate flow when using Safari. * Fixed shared paths so updates save properly on the deployment settings page. * Removed access key and secret key required fields from the database backup configuration modal when using EC2 assumed role. * Fixed the tooltip under the deployment script form so it opens the tooltip instead of submitting the form. * Resolved a bug preventing users from setting up Meilisearch servers. * Fixed the directory fields to support slashes again, allowing users to point to subdirectories. * **Default branch**: Added automatic default branch selection in the new site modal. * **Zero downtime tooltip**: Added a tooltip under deployments clarifying that zero downtime deployment is only supported for new Forge sites. * **Handling text overflow**: Expanded the Migrate to Forge modal, and enabled multiple lines to prevent text overflow. * **Rate limit errors**: Improved LetsEncrypt rate limit errors by differentiating user-driven and service-driven failures. * Fixed the second modal in the "create backup" flow to open at the top of the page instead of halfway down. * Resolved Let's Encrypt modal display issues when using Safari. * Removed the delete option from a site's final domain in the dropdown. * Resolved a bug leaving SSL certificate renewals stuck in a renewing state. * Resolved a caching issue preventing the new site modal from appearing after backing out of this flow using the browser back button. * Fixed domain deletion so users can delete domains even when no primary domain is set. * **New heartbeat notification settings**: Added 30-minute and 60-minute options for failed heartbeat notifications. * **Nginx API endpoints**: Implemented API endpoints to retrieve and update domain Nginx configurations. * Fixed premature Let's Encrypt certificate renewals. * Restored access to past invoices on the billing page for users without active subscriptions. * Fixed DNS verification when the root domain is not authoritative. * Fixed resized servers not updating to show new specs on the settings page. * Fixed ARIA attributes for dropdowns to resolve accessibility issues. * Fixed the backup configuration API to update the DB backup script after database removal. * Fixed the queue worker --force flag UI so the toggle state displays correctly. * Added isolated users to supervisor sudoers so they can restart background tasks after deployment. * Aligned git clone authentication behavior between Zero Downtime Deployment and non‑Zero Downtime Deployment site creation. * Fixed server metrics failures on Hetzner caused by a console error. * Corrected Let's Encrypt domain builder so wildcard certificates no longer add an unnecessary www host. * Restored visibility of Hetzner Intel/AMD (x86) servers in Forge. ## Package manager support You may now select your preferred package manager when creating new sites. Select from npm, pnpm, Bun, or Yarn. ## Improved monorepo support It's now possible to configure your application's "root" directory, making it more convenient to serve applications housed within monorepos. * **Manually update database version**: Added a refresh button on the database page, allowing you to manually sync the database version. * **Increased FastCGI buffers**: Increased FastCGI buffers and FastCGI buffer size to decrease the chances of exceeding buffer thresholds, triggering a 502 error. * **Branch details**: Branch details are now visible on the deployments tab and the deployment details page. * **Deployment logs**: Deployment logs automatically open on the deployment details page after initiating a new deployment. * **Scheduled job frequency**: The cron expression now displays when hovering over Custom frequency on the scheduled job card. * **Copy certificate output**: Added a button to copy the full certificate output in the output modal. * **Site install automation**: Site installation will trigger the install and build commands automatically. * **Accessibility**: Dropdowns are now navigable using the arrow keys when opened using the Tab key. Additionally, pressing Esc closes the dropdown. * Fixed sizing for the Add Users modal to prevent overlapping. * Fixed deployment script macros so commented lines work as expected. * Fixed overlapping organizations when switching organizations in Safari. * Fixed the Let's Encrypt modal to expand correctly for sites with many domains. * Restored archived server visibility when no active servers exist. * Updated DNS certificates to automatically reuse verification names for the same domain. * Resolved an error appearing in the console when using (command + K) to open the search feature. * Resolved a bug preventing some organization owners from removing users. * Fixed recipe logs so long output no longer collapses unexpectedly. ## Provision AWS servers with EBS gp3 You can now provision an AWS server with EBS GP3. GP2 will remain the default for already provisioned AWS servers. All new servers will be provisioned with EBS gp3. To move your existing servers from gp2 to gp3, visit your AWS dashboard. * **Recipes search results**: Updated the recipe search UI to accurately show that a search returned zero matching results, instead of displaying "no recipes". * **Manual certificate renewal**: Added manual certificate renewal for Let’s Encrypt certificates after a failed attempt on the Domains tab. * **Site notes**: Added site notes in the Settings tab, similar to notes on servers. * **Accessibility improvements**: Improved color contrast and form labeling across the platform. * **Scheduled jobs paths**: Added copy support for scheduled job paths in the scheduler. * **Clone certificate endpoint**: Added an API endpoint to clone certificates. This mirrors functionality already available in the Forge UI. * **Copy debug info**: Added the site path to the information included in the copy debug info action. * **Destructive commands**: Added a confirmation step when attempting to run destructive commands. * Resolved a bug causing the Used Memory monitor to display "unknown" after being installed. * Fixed scheduled jobs to display the next expected run time instead of always showing UTC. * Fixed a z-index issue on the domain dropdown in the Let’s Encrypt modal. * Fixed a bug causing Forge to re-add server’s SSH key to the source control provider when creating a site with a deploy key. * Restored site logs in the Observe tab when Custom and Other are selected in the Framework setting. * Fixed organization-level permissions so users with the Viewer role are not shown settings they cannot edit. * Fixed Hetzner server sizes and prices to display accurate values during provisioning. * Added a current-directory placeholder to the new scheduled job modal. * Fixed onboarding state so users see the billing button in the admin dashboard instead of a subscribe prompt. * Added the Sync Database button for server types other than Database. * Expanded the log file dropdown to accommodate longer options. * Updated backup configuration to ensure deleted databases are shown for removal. * Resolved a bug causing database backups with the server database driver set to MariaDB to fail. * Laravel VPS servers are now displayed in the drop-down when configuring a load balancer. ## Introducing support for PostgreSQL 18 Forge now offers support for PostgreSQL 18 when provisioning new servers, including Laravel VPS servers. * **Sync network rules**: Added automatic UFW rule syncing with Forge, including adding missing rules and removing orphaned rules. * **Toggle certificates via API**: Added API support for enabling and disabling existing certificates. * **Improved validation errors**: Validation errors for required fields are now easier to identify. * **Improved Composer credential validation**: Added context to clarify how fields should be formatted when adding Composer credentials. * Fixed a bug causing the Update Site API endpoint to reset other keys. * Fixed a z-index issue on site deployment pages. * Fixed an issue in Forge's API `project_type` match statement causing HTTP 500 errors. * Resolved reliability issues when adding and removing domains on sites with many domains. ## SSL Certificate Information We have made several improvements to the SSL certificate UI. You can now see relevant domains, status, issue date, and expiration date on the certificate card under Certificates, on the Domains tab. Details about why the most recent attempt to renew or issue a certificate failed are now easily accessible in the View Output option. Multiple domains sharing a certificate can be copied all at once by clicking on the domains listed in the card details. [Learn more](https://forge.laravel.com/docs/sites/domains) * **Deployment error handling**: Improved deployment error output to make troubleshooting easier. * **Firewall rule order**: Updated the order that firewall rules display to mirror UFW order on the server. * **Command palette**: Added support for command/control + click in the command palette to open multiple selections at once. * **API command output**: Added Forge API support for fetching command outputs. * **Update Ubuntu records**: Added a manual update option for Forge's Ubuntu records in server overview details. * Fixed health check URLs to update automatically when the primary domain changes. * Resolved a bug causing the deploy button to be unresponsive on the Deployments tab. * Added validation for certificate field uploads in the existing certificate upload modal. * Fixed a bug causing site and server details to display over the navigation bar. ## Deployment Pipeline Improvements We have made several improvements to the deployment pipeline to better recover from failed deployments and timeouts. Deployments will now always use the version of PHP configured on the site, even when calling `php` inside `composer.json` and `package.json` files. Notably, this fixes issues using Laravel Wayfinder during deployments. ## Site Command Improvements Commands now correctly use the version of PHP configured for the site. ## Reset Forge Sudo Password It is now possible to reset the `forge` sudo password for Laravel VPS servers. * **Tag API servers and sites**: Added support for tagging servers and sites during API creation. * **Disk usage metric updates**: Added the disk usage metric to the server Overview. * **Increased command palette results**: Increased command palette results to 10 for servers, sites, and recipes. * **VAT ID improvements**: Improved VAT ID entry for EU countries. * **Searchable team members**: Added member search on the team members page. * **Improved Octane and Reverb port selection**: Forge now suggests the next available port. * **Select all text**: Added support for selecting all text within the UI. * Fixed sudo mode so it enables correctly when restoring database backups. * Fixed background process validation for sites and servers. * Fixed the command palette hotkey display so ⌘ is not shown for Windows and Linux users. * Fixed monitoring notifications to link to the correct location. * Resolved a 404 when unsharing resources from teams. * Restored MariaDB 11.4 installation support. * Fixed invitation acceptance flow so invitations can be accepted at all times. ## Improved Mobile Experience We've improved the mobile experience for the following features: dropdowns, modals, notification center, tables, and breadcrumbs. ## Reintegrated Aikido for Sites When Aikido is enabled at the organization level (via the Integrations page), it activates Aikido features for all sites owned by that organization. Sites under that organization can then individually opt in to Aikido, enabling security scans and syncing results from Aikido’s API. This ensures a consistent setup while maintaining per-site control. [Learn more about our Aikido integration](https://forge.laravel.com/docs/integrations/aikido#aikido) * **Improved search results**: Archived servers have been removed from the command palette. * **Improved navigation**: Linked overview page section titles to their corresponding pages. * **Subdomain aliases**: Added support for retroactively enabling and disabling wildcards on domains. * **Pagination and search**: Improved command palette searchability across pages. * **Let's Encrypt controller validation**: Added domain-wide validation in the controller to avoid errors. * **Restored databases**: Added a sudo mode requirement (password confirmation) when restoring databases. * **Site repository updates**: Added support for changing site Git repositories and branches. * **New metric**: Added disk usage visibility for Laravel VPS. * **Site queue workers**: Added site queue workers to Background Processes at the server level. * **EOL Ubuntu versions**: Improved handling of servers running EOL Ubuntu versions. * Fixed visibility of Add Server and Add Recipe buttons for all users. * Fixed the ellipsis button so closing it no longer opens a selection on site and server pages. * Fixed long branch names in the "Deploy Branch" dropdown. * Fixed the server provider list to show recently authorized providers. * Fixed command palette partial searches to return complete results. * Fixed outbound bandwidth metric display scaling. * Fixed shared site visibility for team members with View access on the Site dashboard. * Fixed API site creation with custom domains so the `on-Forge` suffix is not appended. ## Optional Repositories It’s now possible to create new sites with any project type without specifying a repository. This is ideal if you’re starting a new project from scratch or want to deploy code manually. When creating a new site, leave the repository field blank. Forge will set up the server and web root for you, allowing you to upload your code later via SFTP, SCP, or any other method you prefer. ## Database Sizes Laravel Forge will now show you the estimated size of databases on your server. This is useful to identify large databases that may require optimization or archiving. [Learn more about managing databases in Forge](https://forge.laravel.com/docs/resources/databases) * **Improved dark mode**: Improved contrast and readability for dark mode users. * **Pagination and searching:** Improved the pagination and searching of larger tables. * **Rename background processes:** Added customizable names for background processes. * **Clone SSL certificates:** We’ve reintroduced the ability to clone SSL certificates. * **Copyable IDs:** Added quick copy support for resource IDs from dropdown menus. * **Deploy keys now work with zero-downtime deployments:** Added support for using deploy keys with zero-downtime deployments. * **Maintenance mode redirect path:** Added support for redirect paths when enabling maintenance mode on Laravel sites. * **Display more information about sites and servers:** Added PHP version and isolated username details to site and server list items when applicable. * **Better Statamic support:** Additional Laravel integrations have been enabled for sites using the Statamic project type. * Fixed the environment encryption key resetting. * Disabled deployments when a site does not have a deploy script. * Reinstated deploy keys for sites. You can find this in the site's Deployments tab. * Fixed issues in the Envoyer deployment hooks migration flow. * Fixed account deletion for users with organizations that do not have servers. * Fixed duplicate Nginx upstream errors in load balancers. * Fixed zero-downtime deployments to symlink `auth.json` only when the file exists. ## The Next Generation of Forge is Here Launched on October 1, [the next generation of Laravel Forge](https://laravel.com/blog/everything-you-need-to-know-about-the-new-forge-laravel-vps) delivers speed, control, and ease of use, supporting any modern web stack. This was Forge’s biggest update since its original release in 2014. ### Instant Provisioning with Laravel VPS You can now deploy a server in under 10 seconds (for most use cases) using Laravel VPS. Fully configure servers with a single click, reducing server setup time from minutes to seconds. Billing for Laravel VPS appears on your Forge invoice, so you avoid juggling multiple provider bills. An integrated terminal supports SSH collaboration, allowing multiple developers to debug the same session in real-time. [See how to provision a server with Laravel VPS](https://youtu.be/WElvWyBMsx4) ### Zero-Downtime Deployments Deployments now run without taking your site offline, giving you added confidence every time you ship. When creating a new website in Forge, zero-downtime deployments are enabled by default; however, you can choose to disable this feature. You cannot enable zero-downtime deployments for existing sites. [Learn more](/docs/sites/deployments#zero-downtime-deployments) ### Envoyer Migration Tool You can now migrate sites from Envoyer to Forge’s zero-downtime deployment system. From your site’s dashboard, click “Migrate to Forge” to start. Forge will check if your site uses multiple servers and guide you through the right steps. Zero-downtime deployments currently support one server per site. If you deploy to multiple servers, we recommend continuing to use Envoyer for now. Existing subscriptions remain fully supported. [Read the docs](/docs/integrations/envoyer#migrating-an-existing-site-to-envoyer) ### Nuxt and Next.js Support Forge now includes first-class support for Nuxt and Next.js applications. This update makes it easier than ever to manage full-stack applications on Forge. You can deploy modern JavaScript frameworks alongside your PHP or Laravel projects without extra configuration. When creating a new site, choose Nuxt or Next.js as the project type. Forge will automatically handle the build process, set up the correct runtime environment, and configure your site for production. [Start a Nuxt or Next.js project](https://forge.laravel.com/sign-in) ### Improved Domain and SSL Management Domains and TLS are now simpler, faster, and more reliable, especially for sites with multiple aliases. SSL certificates are now issued per domain, eliminating multi-domain delays and reducing configuration errors. Managing your Nginx configs is also much easier. Each new site also gets an optional default `on-forge.com` domain for quick testing and sharing, which can be disabled if you don’t need it. [Learn more](https://forge.laravel.com/docs/sites/domains#certificates) ### Streamlined UI and Command Palette Forge’s interface has been redesigned for faster, more intuitive navigation. Features are now grouped into logical tabs at the top of each page, reducing clutter and making tools easier to find. The new command palette (`⌘K`) lets you jump to any page or action without reaching for the mouse, speeding up everyday tasks. [Explore the new interface](https://forge.laravel.com/sign-in) ### Organizations and Teams Circles have been replaced with a more standard Organizations and Teams structure. * Organizations are now the primary billing entity across all Forge plans, making it easier to separate billing for different clients or projects. * Teams live inside organizations and can share servers, recipes, and resources. Teams are available on the [Business plan](https://forge.laravel.com/pricing). No action is required on your end: all existing Circles and shared resources are migrated automatically. Learn more about [Organizations](/docs/organizations) and [Teams](/docs/teams) ### Heartbeats and Health Checks You can now catch connectivity and routing issues before your users notice them with Forge’s Health checks. This feature pings your application from three regions (London, New York, and Singapore), so you’ll know right away if it’s reachable worldwide. Heartbeats monitor your scheduled jobs by expecting a ping when they finish. If a backup or data processing task fails silently, Forge alerts you immediately, turning job monitoring from a reactive chore into a proactive safeguard. [Enable Health checks and Heartbeats](https://forge.laravel.com/sign-in) * **Stacked and queued deployments**: Added complete visibility into what is deploying and when. * **Health checks and Heartbeats**: Added proactive monitoring to catch connectivity issues and routing problems before they impact users. * **Real-time metrics charts**: Added live CPU, memory, and bandwidth usage charts. * **Role-based access control**: Added role-based access control for managing permissions. * **Organizations as billable entities**: Made multi-client billing management more straightforward. * **New modern API**: Added a performant, scalable API with comprehensive documentation. * Improved DNS verification performance and reliability. * Fixed load-balanced servers appearing as "Unknown." * Added support for configurable deployment retention. * Fixed organization-level SSH key creation and deletion. * Added permanent redirects from legacy URLs to new Forge URLs. * Expanded allowed character sets for database passwords. * Fixed `/storage` shared paths not being configured during Envoyer migration. * Fixed Laravel Octane configuration files being written to the incorrect folder. * Fixed discounted Laravel VPS prices not appearing in the "Resize" dropdown. * Improved support for self-hosted GitLab and custom Git repositories with zero-downtime deployments. * Added links to breadcrumb dropdown items so Cmd/Ctrl+Click works as expected. * Added missing pagination to potentially long lists (databases, SSH keys, etc.). * Fixed `.env` file reads and writes using the incorrect location for Nuxt.js sites. * Improved tax ID verification reliability when editing billing information. * Fixed team-scoped servers being inaccessible. * Fixed the repository picker not loading more than 100 repositories when using Bitbucket. * Fixed repeated tab navigation failures on smaller viewports. * Fixed an issue in the support widget that prevented customers from contacting support. # Laravel Forge CLI Source: https://forge.laravel.com/docs/cli Laravel Forge CLI is a command-line tool that you may use to manage your Forge resources from the command-line. View the Laravel Forge CLI on GitHub View the Laravel Forge API documentation ## Introduction Laravel Forge provides a command-line tool that you may use to manage your Forge servers, sites, and resources from the command-line. ## Installation > **Requires [PHP 8.2+](https://php.net/releases/)** You may install the **[Laravel Forge CLI](https://github.com/laravel/forge-cli)** as a global [Composer](https://getcomposer.org) dependency: ```bash theme={null} composer global require laravel/forge-cli ``` ## Get started To view a list of all available Laravel Forge CLI commands and view the current version of your installation, you may run the `forge` command from the command-line: ```bash theme={null} forge ``` ## Authenticating You will need to generate an API token to interact with the Laravel Forge CLI. Tokens are used to authenticate your account without providing personal details. API tokens can be created from [Forge's API dashboard](https://forge.laravel.com/profile/api). After you have generated an API token, you should authenticate with your Laravel Forge account using the login command: ```bash theme={null} forge login forge login --token="your-api-token" ``` To remove your stored credentials and log out, use the `logout` command: ```bash theme={null} forge logout ``` Alternatively, if you plan to authenticate with Laravel Forge from your CI platform, you may set a `FORGE_API_TOKEN` environment variable in your CI build environment. ## Current organization & switching organizations Laravel Forge groups your servers and resources within organizations. CLI commands run against your currently active organization, so you should ensure the correct organization is selected before managing servers or sites. When you log in, if your account belongs to a single organization it is selected automatically. Otherwise, you should select one using the `organization:switch` command. You may view your current organization using the `organization:current` command: ```bash theme={null} forge organization:current # org:current is available as a shorter alias ``` To view a list of all organizations your account belongs to, use the `organization:list` command: ```bash theme={null} forge organization:list # org:list is available as a shorter alias ``` To change your active organization, use the `organization:switch` command: ```bash theme={null} forge organization:switch # org:switch is available as a shorter alias forge organization:switch acme ``` Switching organizations resets your active server, since each server belongs to a specific organization. After switching, select a server using the `server:switch` command. ## Current server & switching servers When managing Laravel Forge servers, sites, and resources via the CLI, you will need to be aware of your currently active server. You may view your current server using the `server:current` command. Typically, most of the commands you execute using the Forge CLI will be executed against the active server. ```bash theme={null} forge server:current ``` Of course, you may switch your active server at any time. To change your active server, use the `server:switch` command: ```bash theme={null} forge server:switch forge server:switch staging ``` To view a list of all available servers, you may use the `server:list` command: ```bash theme={null} forge server:list ``` ## SSH key authentication Before performing any tasks using the Laravel Forge CLI, you should ensure that you have added an SSH key for the `forge` user to your servers so that you can securely connect to them. You may have already done this via the Forge UI. You may test that SSH is configured correctly by running the `ssh:test` command: ```bash theme={null} forge ssh:test ``` To configure SSH key authentication, you may use the `ssh:configure` command. The `ssh:configure` command accepts a `--key` option which instructs the CLI which public key to add to the server. In addition, you may provide a `--name` option to specify the name that should be assigned to the key: ```bash theme={null} forge ssh:configure forge ssh:configure --key=/path/to/public/key.pub --name=sallys-macbook ``` After you have configured SSH key authentication, you may use the `ssh` command to create a secure connection to your server: ```bash theme={null} forge ssh forge ssh server-name ``` ## Sites To view the list of all available sites, you may use the `site:list` command: ```bash theme={null} forge site:list ``` ### Initiating deployments One of the primary features of Laravel Forge is deployments. Deployments may be initiated via the Forge CLI using the `deploy` command: ```bash theme={null} forge deploy forge deploy example.com ``` ### Updating environment variables You may update a site's environment variables using the `env:pull` and `env:push` commands. The `env:pull` command may be used to pull down an environment file for a given site: ```bash theme={null} forge env:pull forge env:pull pestphp.com forge env:pull pestphp.com .env ``` Once this command has been executed, the site's environment file will be placed in your current directory. To update the site's environment variables, open and edit this file. When you are done editing the variables, use the `env:push` command to push the variables back to your site: ```bash theme={null} forge env:push forge env:push pestphp.com forge env:push pestphp.com .env ``` If your site is utilizing Laravel's "configuration caching" feature or has queue workers, the new variables will not be used until the site is deployed again. ### Viewing application logs You may also view a site's logs directly from the command-line. To do so, use the `site:logs` command: ```bash theme={null} forge site:logs forge site:logs --follow # View logs in realtime forge site:logs example.com forge site:logs example.com --follow # View logs in realtime ``` ### Reviewing deployment output / logs When a deployment fails, you may review the output / logs via the Laravel Forge UI's deployment history screen. You may also review the output at any time on the command-line using the `deploy:logs` command, which displays the logs for the site's latest deployment: ```bash theme={null} forge deploy:logs forge deploy:logs example.com ``` ### Running commands Sometimes you may wish to run an arbitrary shell command against a site. The `command` command will prompt you for the command you would like to run. The command will be run relative to the site's root directory. ```bash theme={null} forge command forge command example.com forge command example.com --command="php artisan inspire" ``` ### Tinker As you may know, all Laravel applications include "Tinker" by default. To enter a Tinker environment on a remote server using the Laravel Forge CLI, run the `tinker` command: ```bash theme={null} forge tinker forge tinker example.com ``` ### Opening a site in the dashboard To quickly open a site within the Forge dashboard in your browser, use the `open` command: ```bash theme={null} forge open forge open example.com ``` ## Resources Laravel Forge provisions servers with a variety of resources and additional software, such as Nginx, MySQL, etc. You may use the Forge CLI to perform common actions on those resources. ### Checking resource status To check the current status of a resource, you may use the `{resource}:status` command: ```bash theme={null} forge background-process:status # daemon:status is available as a legacy alias forge database:status forge nginx:status forge php:status # View PHP status (default PHP version) forge php:status 8.5 # View PHP 8.5 status ``` ### Viewing resources logs You may also view logs directly from the command-line. To do so, use the `{resource}:logs` command: ```bash theme={null} forge background-process:logs # daemon:logs is available as a legacy alias forge background-process:logs --follow # View logs in realtime forge database:logs forge nginx:logs # View error logs forge nginx:logs access # View access logs forge php:logs # View PHP logs (default PHP version) forge php:logs 8.5 # View PHP 8.5 logs ``` ### Restarting resources Resources may be restarted using the `{resource}:restart` command: ```bash theme={null} forge background-process:restart # daemon:restart is available as a legacy alias forge database:restart forge nginx:restart forge php:restart # Restarts PHP (default PHP version) forge php:restart 8.5 # Restarts PHP 8.5 ``` ### Connecting to resources locally You may use the `{resource}:shell` command to quickly access a command line shell that lets you interact with a given resource: ```bash theme={null} forge database:shell forge database:shell my-database-name forge database:shell my-database-name --user=my-user ``` # Aikido Source: https://forge.laravel.com/docs/integrations/aikido Aikido provides security scanning with Laravel Forge integration. ## Introduction [Aikido](https://aikido.dev?utm_source=laravel\&utm_medium=referral) provides security scanning for repositories. Laravel Forge has partnered with Aikido to allow for a seamless integration with your Forge sites, enabling you to identify and resolve security vulnerabilities directly from the Forge dashboard. ## Connecting with Aikido To begin using Aikido with Laravel Forge, you'll need to enable the integration at the organization level. Navigate to your organization's settings, select the "Integrations" tab, and toggle the Aikido integration on. Follow the prompts to connect your Forge organization to an Aikido workspace. After creating your Aikido workspace, you may easily check the security findings for any of your Forge-powered sites. You can connect multiple Aikido workspaces to a single Forge organization, each representing a different organization or group in your source control provider. ## Enabling Aikido for sites Once your organization is connected to Aikido, you can enable Aikido security scanning for individual sites. Navigate to your site's "Settings / Integrations" panel and toggle the Aikido integration on. Click "Enable Aikido" to activate security scanning for the site. Laravel Forge will automatically match the site's repository and source control provider to enable Aikido scanning. ## Viewing security findings Once Aikido is enabled for a site, security findings will be displayed directly in the site's "Integrations" panel. If Aikido has not found any security issues for your repository, you will see a confirmation message. You can click "View on Aikido" to see more detailed information on the Aikido platform. You may disable Aikido for a site at any time by toggling the integration off. This will deactivate Aikido from the repository, and scanning will be stopped. The Aikido integration is only supported for GitHub, GitLab, GitLab Self-Hosted, and Bitbucket. # Envoyer Source: https://forge.laravel.com/docs/integrations/envoyer Zero-downtime deployments with Laravel Forge and Envoyer. ## Introduction Laravel Forge now offers zero-downtime deployments for all new sites. While Laravel Forge now offers [zero-downtime deployments](/docs/sites/deployments), you may choose to use the first-party integration with [Envoyer](https://envoyer.io) to simultaneously deploy projects across multiple servers. Zero-downtime deployments ensure you avoid those brief milliseconds of downtime while the server updates your code. ## Creating an Envoyer API token To kick things off, you'll need active subscriptions for both [Laravel Forge](https://forge.laravel.com/sign-up) and [Envoyer](https://envoyer.io/auth/register). Once you’re set up, navigate to your Envoyer dashboard and [create a new API token](https://envoyer.io/user/profile?name=Laravel%20Forge\&scopes=projects:create,deployments:create,servers:create#/api). At a minimum, Laravel Forge requires the following scopes: ``` deployments:create projects:create servers:create ``` To future-proof the integration, consider providing Laravel Forge with additional access permissions. You can update your Envoyer’s API token in Forge at any point. ## Linking your Envoyer account to Laravel Forge To link Laravel Forge with your Envoyer API token, navigate to your organization's settings and toggle on the "Envoyer" option. You'll be prompted to enter your Envoyer API token. After submitting the token, Forge will first verify it and then enable the integration. ## Envoyer sites in Laravel Forge It is no longer possible to link newly created Laravel Forge sites to Envoyer projects. Instead, you should create a new Envoyer project and then import your Laravel Forge server and site into that project. For more information, see the "Migrating an existing site to Envoyer" section below. To deploy your Envoyer project within Laravel Forge, click the “Deploy” button, as you would with any other site in Forge. The “Deployment Trigger URL” is also available for use in a CI environment. Additionally, Laravel Forge has been updated to align perfectly with Envoyer projects: * Commands are executed from the `/current` directory. * The site's "Environment" panel will display a read-only version of the `.env` file. Continue to use Envoyer to manage your environment file, especially since it may need to be synchronized across multiple servers. * The site's "Packages" panel is disabled to ensure the `auth.json` file remains intact through future deployments. ## Migrating existing sites to Forge Sites previously connected to Envoyer can be migrated to Laravel Forge's native zero-downtime deployment system. To do so, navigate to the site's "Overview" panel and click "Migrate to Forge". The Envoyer project will first be checked for compatibility. If compatible, the migration can be completed. To complete the migration, you will need to provide your environment key for the Envoyer project. This allows Laravel Forge to access the `.env` file for the project. If the Envoyer project is configured to use Heartbeats, Laravel Forge will also provide you with a list of new heartbeat URLs. You will need to update your application to use these new URLs. ### Requirements There are a few requirements that must be met before migrating an existing Envoyer site to Laravel Forge: 1. Your Envoyer project must be connected to a single server. 2. Must not be using GitLab Self-Hosted as the Git repository. 3. Your organization must be connected to the Envoyer integration. 4. Forge deployments are limited to [10 minutes](/docs/sites/deployments#introduction), compared to Envoyer's 15-minute limit. Ensure your deployment process completes within this timeframe. # OpenClaw Source: https://forge.laravel.com/docs/integrations/openclaw Deploy OpenClaw AI agent servers on Laravel Forge. ## Introduction [OpenClaw](https://openclaw.ai) is an open-source AI agent platform that allows you to run AI assistants on your own infrastructure while integrating with popular messaging applications such as WhatsApp, Telegram, Discord, Slack, Microsoft Teams, Twitch, and Google Chat. By hosting OpenClaw on your own server, you maintain complete control over your data, API keys, and infrastructure. Laravel Forge makes it simple to provision and manage OpenClaw servers, allowing you to deploy your own private AI assistant in minutes. ## Creating an OpenClaw Server To create an OpenClaw server, navigate to your organization's overview or "Servers" tab and click "New server". When selecting your server type, choose "OpenClaw" from the available options. Next, configure your server by selecting the region closest to you and choosing an appropriate server size based on your expected usage. OpenClaw servers are powered by Laravel VPS infrastructure, ensuring reliable performance and quick provisioning times. OpenClaw servers created in the "Laravel managed" private network are available for instant provisioning. Servers in Small, Medium, Large, and X Large sizes provision instantly, while other sizes may take longer. ## Server Requirements OpenClaw servers are provisioned with all the necessary dependencies to run the OpenClaw platform. ## Configuring OpenClaw After your server is provisioned, you will be dropped into the OpenClaw configuration wizard terminal interface. Laravel VPS servers include a built-in web-based terminal for convenient management of your OpenClaw installation. ## Managing Your OpenClaw Server ### Resizing Your Server If your OpenClaw deployment requires more resources, you can resize your server from the Settings tab. Select a new server size from the "Size" dropdown and confirm the change. When resizing an OpenClaw server, the server will be temporarily unavailable during the resize process. You cannot downsize to a smaller specification. ### Backups We recommend enabling regular backups for your OpenClaw server to protect your configuration and conversation data. Navigate to the Backups tab to configure automated backup schedules. ## Deleting an OpenClaw Server To delete an OpenClaw server, navigate to the server's Settings tab, locate the Danger zone, and click "Delete server". Enter the server name to confirm. Deleting a server will permanently destroy all data, including your OpenClaw configuration and any stored conversation history. This action cannot be undone. # Sentry Source: https://forge.laravel.com/docs/integrations/sentry Sentry provides error monitoring and tracing for your apps with Laravel Forge integration for creating Sentry organizations. ## Introduction [Sentry](https://sentry.io) delivers comprehensive error monitoring and application tracing for your applications. Through Laravel Forge's partnership with Sentry, you can seamlessly create new Sentry organizations and projects directly from the Forge dashboard, eliminating the need to switch between platforms. This integration streamlines error tracking implementation for applications hosted on Forge-managed servers while maintaining a unified development workflow. ## Connecting with Sentry To begin using Sentry with Laravel Forge, you'll need to enable the integration at the organization level. Navigate to your organization's settings, select the **Integrations** tab, and toggle the Sentry integration on. Complete the setup by providing the required information and clicking Save to create your new Sentry organization. The Laravel Forge integration requires creating a new Sentry organization. Existing Sentry organizations cannot be connected to this integration—all Forge-created projects will be added to your new organization. ## Creating Sentry projects Once your organization is connected to Sentry, you can create projects for individual sites. Navigate to your site's **Settings / Integrations** panel and toggle the Sentry integration on. Select your target platform from the available options and follow the provided configuration instructions. Click Enable Sentry to create the project, then follow the additional setup instructions to properly configure error monitoring for your specific application requirements. Laravel Forge doesn't automatically install Sentry into your application. You must manually install the [Sentry SDK for Laravel](https://github.com/getsentry/sentry-laravel) via Composer and configure the `SENTRY_DSN` environment variable with your provided DSN key. # Welcome to Laravel Forge Source: https://forge.laravel.com/docs/introduction A server management and application deployment service for your Laravel applications and beyond. Create your Laravel Forge account today Watch the free Laravel Forge series on Laracasts ## What is Laravel Forge? Laravel Forge is a server management and application deployment service. Forge takes the pain and hassle out of deploying servers and can be used to launch your next website. Whether your app is built with a framework such as [Laravel](https://github.com/laravel/laravel), [Symfony](https://github.com/symfony/symfony), [Statamic](https://github.com/statamic/cms), [WordPress](https://github.com/WordPress/WordPress), or is a vanilla PHP application - Forge is the solution for you. We live and breathe PHP here at Laravel Forge, but Forge is also ready to handle other tech stacks too, such as Node.js. Laravel Forge can provision new servers for you in seconds. We also offer you the ability to provision [multiple server types](/docs/servers/types) (e.g., web servers, database servers, load balancers) with the option of having a variety of services configured for you to hit the ground running, including: * Nginx web server * [PHP](/docs/servers/php) (multiple version support) * [Database](/docs/resources/databases) (MySQL, Postgres, or MariaDB) * Logrotate * [Memcached](/docs/resources/caches) * [Redis](/docs/resources/caches) * Meilisearch * [OPcache](/docs/servers/php#opcache) * [UFW firewall](/docs/resources/network#firewalls) * [Automatic security updates](/docs/servers/security#automated-security-updates) * And much more! In addition, Laravel Forge can assist you in managing [scheduled jobs](/docs/resources/scheduler), [queue workers](/docs/sites/queues), [TLS/SSL certificates](/docs/sites/domains#certificates), and more. After your server has provisioned, you can manage and deploy your web applications using the Forge UI dashboard. ## Laravel Forge IP addresses In order to provision and communicate with your servers, Laravel Forge requires SSH access to them. If you have set up your servers to restrict SSH access using IP allow lists, you must allow the following Forge IP addresses: * `159.203.150.232` * `159.203.150.216` * `45.55.124.124` * `165.227.248.218` You can also access the IP addresses via the following URL: [https://forge.laravel.com/ips-v4.txt](https://forge.laravel.com/ips-v4.txt). This is particularly useful if you intend on automating your network or firewall infrastructure. If you are restricting HTTP traffic, your server must also allow incoming and outgoing traffic from `forge.laravel.com`. The Laravel Forge IP addresses may change from time to time; however, we will always email you several weeks prior to an IP address change. #### Forge Terminal Laravel VPS customers benefit from an [integrated terminal](/docs/servers/laravel-vps#forge-terminal) within the Forge Control Panel. To ensure this is functional, you must allow the following IP: * `142.93.78.212` ### Laravel Forge support jumpbox To enable the Laravel Forge Support team to provide more efficient technical assistance, you can optionally allow our support jumpbox IP address to access your server in your firewall settings: * `129.212.144.126` ## Laravel Forge API Laravel Forge provides a powerful API that allows you to manage your servers programmatically, providing access to the vast majority of Forge features. To learn more about the Forge API, check out our [API documentation](https://forge.laravel.com/api-documentation). ## Legal and compliance Our [Legal](https://laravel.com/legal) and [Trust Centers](https://trust.laravel.com/?product=forge) provide details on the terms, conditions, and privacy practices for using Laravel Forge. # Copy Fail security advisory (CVE-2026-31431) Source: https://forge.laravel.com/docs/knowledge-base/cve-2026-31431 Security advisory for the Copy Fail Linux kernel privilege escalation vulnerability affecting Laravel Forge servers. ## Overview A critical Linux kernel vulnerability, CVE-2026-31431 ("Copy Fail"), was publicly disclosed in April 2026. The flaw is a logic error in the kernel's `authencesn` component that allows an unprivileged local user to escalate their privileges to full root (administrator) access. Ubuntu released a kernel patch for this issue on April 2, 2026. The vulnerability chains two kernel subsystems — the `AF_ALG` crypto API socket interface and the `splice()` system call — to perform a 4-byte write to the page cache. This can be used to modify the behavior of a setuid binary without requiring a race condition or kernel-specific offsets, making it highly reliable. This vulnerability only allows privilege escalation by a user who already has local access to your server. It does not permit remote code execution on its own. However, we strongly recommend applying the patch and rebooting your servers at your earliest convenience. ## What Forge has already done Because Laravel Forge enables automatic security updates by default, the patched `kmod` package has already been downloaded and installed on servers where this feature is enabled. However, **the fix does not take effect until the server is rebooted**, and Forge does not reboot servers automatically. ## Affected Ubuntu versions | Ubuntu Version | Status | | -------------- | --------------------------------------------------------------------------------- | | 24.04 LTS | Patched — fix available via `kmod` package | | 22.04 LTS | Patched — fix has been backported | | 20.04 LTS | Patched — fix has been backported | | 18.04 LTS | **Not patched** — this version has reached end of life and will not receive a fix | ## What you need to do ### Step 1: Check your current kmod version Before applying the fix, we recommend SSHing into your server and confirming the currently installed `kmod` version: ```bash theme={null} dpkg -l kmod ``` Make a note of the version displayed so that you can verify the upgrade afterward. ### Step 2: Apply the fix If automatic security updates are enabled, the patched package is already on your server and you only need to reboot. You can reboot directly from the Forge dashboard by navigating to your server and selecting **Reboot Server** from the server management panel. If your servers are hosted on AWS, rebooting will allocate a new IP address to the server. You will need to update the IP address in the Forge dashboard after the reboot completes. If automatic security updates are disabled, apply the fix manually via SSH before rebooting: ```bash theme={null} sudo apt update && sudo apt install --only-upgrade kmod sudo reboot ``` ### Step 3: Verify the fix is active After the server has rebooted, SSH back in and run `dpkg -l kmod` again to confirm that the installed version is newer than the one recorded in Step 1: ```bash theme={null} dpkg -l kmod ``` ## Temporary mitigation (without rebooting) If you are unable to reboot immediately, you can disable the vulnerable `algif_aead` kernel module as a temporary measure. This does not affect services such as dm-crypt, LUKS, kTLS, IPsec, or standard OpenSSL/GnuTLS builds. ```bash theme={null} echo "install algif_aead /bin/false" | sudo tee /etc/modprobe.d/disable-algif.conf sudo rmmod algif_aead ``` This is a temporary workaround only. You should still apply the full patch and reboot your server as soon as possible. To remove the temporary mitigation after rebooting with the patched kernel: ```bash theme={null} sudo rm /etc/modprobe.d/disable-algif.conf ``` ## More information For Ubuntu's official guidance and a complete walkthrough of the fix, see Canonical's announcement at [https://ubuntu.com/blog/copy-fail-vulnerability-fixes-available](https://ubuntu.com/blog/copy-fail-vulnerability-fixes-available). For full technical details about the vulnerability itself, visit [https://copy.fail](https://copy.fail). # Networks Source: https://forge.laravel.com/docs/knowledge-base/networks Common issues and solutions for Laravel Forge. ## Deleted SSH firewall rule If you have deleted the firewall rule (typically port 22) from the Laravel Forge UI or directly on the server, Forge will be unable to connect to the server and will be unable to re-create this rule for you. To fix this, you will need to access the server directly via your provider and manually add the SSH port again. DigitalOcean allows you to connect remotely through their dashboard. Laravel Forge uses `ufw` for the firewall, so once you've connected to the server you need to run the following as `root`: ```bash theme={null} ufw allow 22 ``` # Cookbook Source: https://forge.laravel.com/docs/knowledge-base/scheduled-jobs Common issues and solutions for Laravel Forge. ## Scheduled jobs not running It's important to be aware that one single misconfigured scheduled job will break **all jobs** in the scheduler. You should verify that your frequency and commands are correct using a tool such as [Crontab.guru](https://crontab.guru). # Servers Source: https://forge.laravel.com/docs/knowledge-base/servers Common tasks and solutions for managing your Laravel Forge server. ## AWS provisioned servers are disappearing To ensure Laravel Forge works correctly with AWS, please review [these requirements](/docs/server-providers#aws). ## DigitalOcean droplet limit exceeded This error is returned by [DigitalOcean](https://digitalocean.com) when you have reached a limit on how many droplets you can create. You can ask DigitalOcean to increase your droplet limit by contacting their support. Once they have increased your limit, you may create servers in Laravel Forge. ## Expanding server disk space When you increase your server's disk size through your VPS provider, the additional space is not automatically available to your Ubuntu filesystem. You will need to expand the operating system's filesystem to use the newly allocated space. We strongly recommend creating a backup or snapshot of your server through your VPS provider before proceeding with disk expansion operations. While these commands are generally safe, disk operations carry inherent risks. #### Checking current disk usage First, check your current disk usage to identify which partition needs expansion: ```bash theme={null} df -h ``` This command will show you all mounted filesystems and their usage. Look for the partition that's running low on space (typically `/`). #### Expanding the filesystem Most Laravel Forge servers use standard partitions without LVM (Logical Volume Manager). If your system uses LVM, the disk expansion process is different and requires additional steps using the `pvresize` and `lvextend` commands. For standard, non-LVM systems, follow these steps: 1. First, check your partition table: ```bash theme={null} sudo fdisk -l ``` 2. If the partition needs to be expanded, use the `growpart` command: ```bash theme={null} # Install growpart if it is not available... sudo apt-get update && sudo apt-get install -y cloud-guest-utils # Grow the partition... sudo growpart /dev/vda1 # Replace with your actual device and partition number (e.g., /dev/sda1, /dev/xvda1) ``` 3. Resize the filesystem: ```bash theme={null} # For ext4 filesystems... sudo resize2fs /dev/vda1 # Replace with your actual device (e.g., /dev/sda1, /dev/xvda1) # For XFS filesystems... sudo xfs_growfs / ``` #### Verifying the expansion After completing the expansion, verify that the additional space is available: ```bash theme={null} df -h ``` The filesystem should now show the increased capacity. #### Troubleshooting **"No space left on device" Error** If you encounter an error like `mkdir: cannot create directory '/tmp/growpart.xxxx': No space left on device`, your root filesystem is completely full, preventing even basic commands from running. You will need to free up some temporary space first: ```bash theme={null} # Clear apt cache... sudo apt-get clean # Clear journal logs (keep only last 50M)... sudo journalctl --vacuum-size=50M # Remove old snap versions... sudo sh -c 'snap list --all | grep disabled | awk "{print \$1, \$3}" | while read name rev; do snap remove "$name" --revision="$rev"; done' # Check if you now have space... df -h / ``` Once you created free space on the disk, you can proceed with the disk expansion steps above. Consider setting up [disk usage monitoring](/docs/servers/monitoring) to receive alerts before your disk space runs critically low, giving you time to expand the disk proactively. ## Operating system release upgrades When connecting to your server via SSH, you may encounter messages like `New release '24.04.1 LTS' available` or be instructed to run `do-release-upgrade`. However, we strongly advise against performing operating system release upgrades on Laravel Forge-managed servers. Upgrading your server's operating system version can break Laravel Forge's ability to manage your server and may cause application downtime. During initial provisioning, Laravel Forge configures your Ubuntu server with specific settings, services, and applications that are tailored to work seamlessly together. A release upgrade can: * Overwrite critical configuration files * Change system service behaviors * Break compatibility with installed PHP versions, databases, and other services * Prevent Laravel Forge from properly managing your server * Cause unexpected application errors or downtime #### Recommended approach Instead of upgrading, we recommend provisioning a new server with your desired Ubuntu version through Laravel Forge, then migrating your sites to the new server. This approach ensures full Forge compatibility and reduces the risk of unexpected issues that can arise from in-place upgrades. For teams that prefer a fully managed solution, [Laravel Cloud](https://cloud.laravel.com) eliminates operating system concerns entirely. While Laravel Forge provides maximum control and flexibility over your infrastructure, Laravel Cloud's fully-managed approach means you never need to think about server maintenance or OS versions. ## Restarting PHP FPM When configuring your server, Laravel Forge configures FPM so that it can be restarted without using your server's "sudo" password. To do so, you should issue the following command. Of course, you should adjust the PHP version to match the version of PHP installed on your machine: ```bash theme={null} touch /tmp/fpmlock 2>/dev/null || true ( flock -w 10 9 || exit 1 echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9 `flock` is used to prevent concurrent php-fpm reloads. Without a lock, simultaneous restart attempts could lead to race conditions, brief service interruptions, or inconsistent process states. ## Resetting the Forge user sudo password Laravel Forge does not store your server's `forge` user sudo password and is therefore unable to reset it for you. To reset the `forge` user sudo password, you'll need to contact your server provider and regain SSH access to your server as the `root` user. Once you are connected to your server as the `root` user, you should run the `passwd forge` command to redefine the `forge` user sudo password. #### DigitalOcean If your servers are managed by DigitalOcean, the following steps should assist you in resetting the `forge` user's sudo password using Digital Ocean's dashboard. 1. First, on DigitalOcean's dashboard, click on the server name. Then, within the "Access" tab, click on "Reset Root Password". Usually, this operation restarts the server and sends the new `root` user's sudo password to your DigitalOcean account's associated email address. 2. Next, still on the "Access" tab, click on "Launch Droplet Console" to gain access to your server terminal as the `root` user. During this step, you will be asked to redefine the `root` user's sudo password. 3. Finally, execute the `passwd forge` terminal command as the `root` user to redefine the `forge` user's sudo password. ## Server disconnected There are several reasons why your server may have a "disconnected" status. We encourage you to check these common solutions before contacting support: * Verify that the server is powered on via your server provider's dashboard. If the server is powered off, you should restart it using your **provider's dashboard**. * Verify that the public IP address of the server is known to Laravel Forge (the public IP address may change between reboots of the actual VPS). * Verify that the Laravel Forge generated public key for the server is included in the `/root/.ssh/authorized_keys` and `/home/forge/.ssh/authorized_keys` files. This key is available via the "Settings" tab of your server's Forge management panel. * If your server is behind a firewall, make sure you have [allowed Laravel Forge's IP addresses to access the server](/docs/introduction#forge-ip-addresses). * If you removed Port 22 from the server's firewall rules, you will need to contact your server provider and ask them to restore the rule. Removing this rule prevents Laravel Forge from accessing your server via SSH. * Remove any private keys or other lines that do not contain a valid public key from the `/root/.ssh/authorized_keys` and `/home/forge/.ssh/authorized_keys` files. If you are still experiencing connectivity issues, you should also verify that the permissions and ownership of the following directories and files are correct: ```bash theme={null} # Fixes the "root" user (run as root) chown root:root /root chown -R root:root /root/.ssh chmod 700 /root/.ssh chmod 600 /root/.ssh/authorized_keys # Fixes the "forge" user chown forge:forge /home/forge chown -R forge:forge /home/forge/.ssh chmod 700 /home/forge/.ssh chmod 600 /home/forge/.ssh/authorized_keys ``` If, after trying all of the above solutions, Laravel Forge is still unable to connect to your server but you can still SSH to the server, please run the following command as the `root` user and share the output with Forge support: ```bash theme={null} grep 'sshd' /var/log/auth.log | tail -n 10 ``` If Laravel Forge is not able to connect to your server, you will not be able to manage it through the Forge dashboard until connectivity is restored. ## "Too many open files" error If you are receiving an error stating that your server has "too many open files", you likely need to increase the maximum amount of file descriptors that your operating system is configured to allow at a given time. This may be particularly true if your server will be handling a very large number of incoming web requests. First, ensure the maximum number of "open files" is correctly configured based on the size of your server. Usually, the maximum number of open files allowed by the operating system should be about 100 files for every 1MB of RAM. For example, if your server has 4GB memory, the maximum number of open files can safely be set to `409600`. You can determine how many files your operating system currently allows to be opened at once by running the `sysctl fs.file-max` command. You can configure the existing setting by adding or modifying the following line in `/etc/sysctl.conf`: ``` fs.file-max = LIMIT_HERE ``` While the instructions above set the maximum number of "open files" system-wide, you also need to specify these limits for each server user by editing the `/etc/security/limits.conf` file and adding the following lines: ``` root soft nofile LIMIT_HERE root hard nofile LIMIT_HERE forge soft nofile LIMIT_HERE forge hard nofile LIMIT_HERE ``` Of course, if your server contains additional users due to the use of "site isolation", those users also need to be added to the `/etc/security/limits.conf` file: ``` isolated-user soft nofile LIMIT_HERE isolated-user hard nofile LIMIT_HERE ``` Additionally, if the "too many open files" error was triggered by an Nginx process (very common on load balancers at scale), you will need to also add the `nginx` user to `/etc/security/limits.conf`: ``` nginx soft nofile LIMIT_HERE nginx hard nofile LIMIT_HERE ``` And, add the following directive to your server's `/etc/nginx/nginx.conf` file: ``` worker_rlimit_nofile LIMIT_HERE; ``` You should restart the Nginx service once this directive has been added to your Nginx configuration file: ``` service nginx restart ``` ## Upgrading Composer The latest version of Composer is installed by Laravel Forge when a new server is provisioned. However, as your server ages, you may wish to upgrade the installed version of Composer. You may do so using the following command: ```bash theme={null} composer self-update --2 ``` This will instruct Composer to update itself and specifically select version 2. If your application is not compatible with Composer 2, you can roll back to Composer 1 at any time: ```bash theme={null} composer self-update --1 ``` Servers are provisioned with a Scheduled job that updates Composer. You should delete and recreate the existing job via the server's "Scheduled Jobs" tab after upgrading Composer. ## Upgrading Meilisearch If you would like to install the latest Meilisearch binaries on your server, please follow [the official Meilisearch upgrade guide](https://www.meilisearch.com/docs/learn/update_and_migration/updating). On most Laravel Forge servers, the Meilisearch binary is installed at `/usr/local/bin/meilisearch` and the database is stored at `/var/lib/meilisearch`. ## Upgrading Nginx The latest version of Nginx is installed by Laravel Forge when a new server is provisioned. However, as your server ages, you may wish to upgrade the installed version of Nginx. You may do so using the following commands: ```bash theme={null} sudo apt-get install -y --only-upgrade nginx sudo nginx -v sudo service nginx restart ``` You should upgrade the Nginx version on your server at your own risk. Upgrading the version of Nginx installed on your server may cause downtime or conflict with other installed software. ## Upgrading Node.js The latest LTS version of Node.js is installed by Laravel Forge when it is provisioning a new server. However, as your server ages, you may wish to upgrade the version of Node.js: ```bash theme={null} sudo apt-get update --allow-releaseinfo-change && sudo apt-get install -y ca-certificates curl gnupg sudo mkdir -p /etc/apt/keyrings curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg NODE_MAJOR=22 echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list sudo apt-get update --allow-releaseinfo-change && sudo apt-get install nodejs -y ``` [Node.js version information](https://nodejs.org/en/about/previous-releases/) ## Upgrading npm The latest version of npm is installed by Laravel Forge when provisioning new servers. However, you may upgrade the installed version of npm using the following commands: ```bash theme={null} sudo npm install npm@latest -g ``` # Sites Source: https://forge.laravel.com/docs/knowledge-base/sites Common tasks and solutions for managing your Laravel Forge sites. ## Nginx ### HTTP 403: Forbidden after installing a site If you receive a HTTP 403: Forbidden response after installing a site, this typically indicates that there is no `index.php` or `index.html` file present in the web directory. Nginx is configured to not display directory listings by default for security reasons. Forge no longer deploys sites with a default `index.html` file. To resolve this issue, you should: 1. Deploy your application code to the site. 2. Ensure your application has an `index.php` file in the web directory (typically `/public` for Laravel applications). 3. Verify that your site's web directory is correctly configured in the site settings. If you have deployed your application and still see this error, verify that: * Your deployment script completed successfully. * The web directory path matches where your application's entry point is located. * File permissions are correct (Forge sets these automatically during deployment). ## Site is stuck deploying Rarely, your application may get stuck in a "deploying" state. When this occurs, you can reset the deployment state at the top right of the site management panel using the **Self Help** drop-down menu. ## Using user isolation with existing sites It is not currently possible to use isolated users to manage existing sites that have already been created without user isolation. Instead, you will need to create a new site with the user isolation option enabled. ## Uncommitted commits during deployment This error may occur when files under source control within the site directory have been changed by the application and will be overwritten by the fresh deployment. You may discard these changes by accessing the **Self Help** drop-down menu at the top right of the site management panel and triggering the **Reset Git State** action. Please note that the changes made will be lost when this action is run. You should also review your application and correct any parts of the applications that may be writing to a source controlled directory on your server. Otherwise, you may continue to encounter this error on further deployments. ### Adding Composer credentials during site creation Composer credentials (for example, for private packages) can be added during site creation from **Advanced settings** under **Composer Authentication**. You can also add them after the site is created from your site's **Settings** tab under **Composer**. If you do not add credentials during site creation and the site requires private packages, you must disable **Install Composer Dependencies** during site creation—otherwise the installation will fail. After the site is created, add your credentials in **Settings** → **Composer**, then run a deployment to install the dependencies. See more at [Packages - Composer credentials](/docs/resources/packages#composer-credentials). # Source Control Source: https://forge.laravel.com/docs/knowledge-base/source-control ## Laravel Forge is unable to access Git repository There are several reasons Laravel Forge may not be able to access your GitHub, GitLab, or Bitbucket repository. First, you should try refreshing the source control API token that is linked to Forge via your account profile's "Source Control" tab. Laravel Forge attempts to access your repository using your source control provider's API. The API credentials that will be used are the credentials tied to the account of the person who **owns** the Forge server. If a Forge server is shared with you via a team, it will use the team **owner's** API credentials. You should ensure this person has full access to the repository on GitHub. ### GitHub organization repositories Sometimes, if the repository is an organization repository, you will need to grant Laravel Forge access to that organization. You may do that using the following link: [https://github.com/settings/connections/applications/fdb28071bd05daebc122](https://github.com/settings/connections/applications/fdb28071bd05daebc122) # Notifications Source: https://forge.laravel.com/docs/notifications Control which Laravel Forge notifications you receive, and on which channel. ## Introduction Laravel Forge sends notifications for server and site events, including completed server provisioning, failed deployments, and monitor alerts. * **Personal notification preferences.** These apply to your own account and control which notifications Laravel Forge sends you, and whether they arrive by email, in the notification center, or both. * **Resource notification channels.** These are configured for individual sites, monitors, and backup configurations and are sent to their configured recipients. This page covers personal notification preferences. To configure resource notifications, see [deployment notifications](/docs/sites/deployments#deployment-notifications), [backup notifications](/docs/resources/database-backups#notifications-for-failed-backups), and [server monitoring](/docs/servers/monitoring). ## Notification channels Laravel Forge delivers personal notifications on two channels: | Channel | Delivery | | ------- | -------------------------------------------------------------------- | | Email | Sent to the email address on your Laravel Forge account. | | In-app | Shown in the notification center within the Laravel Forge dashboard. | You can enable or disable email and in-app notifications independently. When a channel is disabled, its individual notification preferences are hidden. Preferences are per user. Changing yours does not affect what your organization's other members receive. ## Managing your preferences To manage your notification preferences, click your avatar in the top right corner of the dashboard, click "Account", then click "Notifications" in the sidebar. Use the "Enable email notifications" and "Enable in-app notifications" switches to control each channel as a whole, then check or uncheck individual notifications in the "Email" and "In-app" columns. Once done, click "Save". A checkbox is disabled when the notification cannot be delivered on that channel. Hovering over it explains why. ## Available notifications The tables below list every notification covered by personal preferences, along with its **default state** on each channel. ### Server notifications | Notification | What it covers | Email | In-app | | -------------------------- | ----------------------------------------------------------------------- | ----------- | ------ | | Server provisioned | A new server has finished provisioning and is ready. | On | On | | Server provisioning failed | Something went wrong while provisioning a server. | Off | On | | Server deletion failed | A server could not be deleted from your provider. | Off | On | | Server marked as stale | A server has not been used for a while and may be worth reviewing. | Unavailable | On | | Server monitor alert | A resource monitor crossed its alert threshold, or recovered afterward. | On | On | | Heartbeat check-in missed | A heartbeat monitor missed its expected check-in. | On | On | | Backup failed | A scheduled database backup failed to complete. | On | On | | Recipe execution report | A summary report after a recipe finishes running on a server. | On | On | ### Site notifications | Notification | What it covers | Email | In-app | | ------------------------------ | ------------------------------------------------------------------------- | ----------- | ------ | | Deployment succeeded | A deployment finished successfully. | Unavailable | On | | Deployment failed | A deployment failed to complete. | On | On | | SSL certificate renewal failed | A certificate could not be renewed. Includes the error log for diagnosis. | On | On | | Site health check failed | A site failed its health check and may need attention. | Off | On | ## Muting servers Mute a server to stop personal notifications for it and its sites without changing your preferences for other servers. To mute a server, open the notifications page, click the "Muted servers" dropdown, and check each server you want to silence. Servers are grouped by organization, and the search field filters the list. Click "Save" to apply your changes. Muting does not affect notifications configured in a site's own settings. If your email address appears on a site's failure notification recipient list, you will continue to receive those emails for a muted server, because that list delivers to raw addresses rather than to Laravel Forge accounts. Remove your address from the site's recipients to stop them. Archived servers and servers you can no longer access are removed from the muted servers list the next time you save the page. If you restore the server or regain access, mute it again if needed. # Organizations Source: https://forge.laravel.com/docs/organizations Learn how to create and manage organizations in Laravel Forge. ## Introduction After registering with Laravel Forge, you will be assigned to an organization. For new registrations, this will be a brand-new organization created for you; however, if you are invited by another Laravel Forge user, you will be added to the existing organization you were invited to. In Laravel Forge, the organization is the top-level entity that owns all server provider credentials, servers, sites, and other resources. Each organization’s member and billing plan configuration is unique, so each organization may configure its own payment method details and preferred pricing plan. ## Organization members As an owner or admin of an organization on the Business plan, you are able to manage organization members via the Members tab in your organization's settings. Users can be assigned a default role, or you may create a custom role with specific permissions. Organization members will always be able to view resources. To limit access to resources you should add members to [teams](/docs/teams). ### Roles Laravel Forge offers five default roles for organization members: * **Owner** - Full access to all organization settings, servers, and team members. * **Admin** - Full access to the organization, except managing or assigning owner roles. * **Manager** - Manages servers and teams but not billing or organization settings. * **Developer** - Full access to servers and sites, but can't create new servers. * **Viewer** - View all servers, sites, and sensitive data without making changes. You may also create custom roles with specific permissions tailored to your organization's needs. Roles can be assigned to members on an organization or team level. ### Inviting new members To invite someone to an organization, navigate to the organization's dashboard and click Settings > Members. Then, enter the email of the new user, select their role, and click “Send invite”. The invited user will receive an email and notification that will allow them to accept the invitation to join the organization. ### Canceling invitations To cancel an invitation, an admin can navigate to your Organization dashboard and click Settings > Members. Pending invitations are listed under “Invited members”. Click the three dots next to the pending invitation you wish to cancel, then click “Cancel invite”. ### Removing members To remove a member from an organization, an admin can navigate to your Organization dashboard and click Settings > Members. Current members are listed under “Organization members”. Click the three dots next to the member you wish to remove, then click “Remove from organization”. ## Organization billing Each organization's billing plan configuration is unique, so each organization may configure its own payment method details and preferred pricing plan. ### Changing plans Every Laravel Forge organization must have an active subscription. To upgrade or downgrade your plan, an admin can navigate to your Organization dashboard and click Settings > Billing. From the billing page, you can view your current plan, change your plan, and update your payment method. For upgrades, you will be billed pro rata for the higher plan immediately. For downgrades, your plan will be changed at the end of your current billing cycle. Downgrading plans will result in the loss of access to some features like teams, database backups and monitoring. Make sure your applications do not depend on these features before downgrading. ### Canceling subscriptions If you wish to stop using Laravel Forge, you can cancel an organization's subscription at any time. To cancel an organization's subscription, an admin can navigate to your Organization dashboard and click Settings > Billing. From the billing page, click the "Cancel plan" button. ## Organization settings ### Renaming organizations To rename an organization, navigate to the organization’s dashboard and click Settings. On the General tab, edit the Organization Name field. After updating the name, click Save. ### Deleting organizations To delete an organization, navigate to the organization’s dashboard and click Settings. Then, on the General tab, click the Delete Organization button. Deleting an organization is permanently destructive and cannot be undone. All organization member, server, and resource data will be terminated immediately. # Recipes Source: https://forge.laravel.com/docs/recipes Save and run common Bash scripts across your servers. ## Introduction Recipes allow you to save common Bash scripts and run them across any of your servers. For example, you could save a recipe to install MongoDB so you can conveniently run it on future servers. ## Managing recipes ### Creating recipes To create a recipe, navigate to the "Recipes" page. Then, click the "New recipe" button. After providing a name, user and script, click the "Create recipe" button. When your organization is using [teams](/docs/teams), you will also be able to choose who to share the recipe with. By default, this is everyone in your organization, but you may also share recipes with teams. ### Editing recipes To edit a recipe, navigate to the "Recipes" page. Then, click on the dropdown next to the recipe you want to edit. Click the "Edit" dropdown item and modify the recipe as required. ### Deleting recipes To delete a recipe, navigate to the "Recipes" page. Then, click on the dropdown next to the recipe you want to delete. Click the "Delete" dropdown item and confirm that you do want to delete the recipe. ### Running recipes To run a recipe, navigate to the "Recipes" page. Then, click on the dropdown next to the recipe you want to run. Click the "Run" dropdown item and select the servers you want to run the recipe on. You may also choose to send the recipe output via email. Recipes will also create run logs which you can access by clicking on the recipe item. From here you may click on a run to see the full output. ## Variables Laravel Forge provides a few variables that can be used to make your recipe more dynamic. You are free to use any of these variables within your recipe's script: * `{{server_id}}` - The ID of the server that the recipe is running on * `{{server_name}}` - The name of the server that the recipe is running on * `{{ip_address}}` - The public IP address of the server * `{{private_ip_address}}` - The private IP address of the server * `{{username}}` - The server user who is running the script * `{{db_password}}` - The database password for the server the script is running on * `{{server_type}}` - The type of the server that the recipe is running on, i.e. one of the following... * `"app"` * `"cache"` * `"database"` * `"loadbalancer"` * `"meilisearch"` * `"web"` * `"worker"` When using these variables, you should ensure that they exactly match the syntax shown above. ## Laravel Forge recipes Occasionally, Laravel Forge may provide recipes to perform adhoc fixes to your servers. These recipes may not be modified, but can be ran in the same way as typical recipes. # Background Processes Source: https://forge.laravel.com/docs/resources/background-processes Learn how to configure and manage background processes on your Laravel Forge server. ## Introduction Laravel Forge uses [Supervisor](http://supervisord.org) to manage background processes, ensuring your long-running scripts stay active. This is particularly useful for maintaining daemons like [ReactPHP](http://reactphp.org/) applications. When a process stops unexpectedly, Supervisor automatically restarts it to maintain continuous operation. ## Configuring background processes Background processes can be configured on both a server and site level. To create a background process, navigate to the "Processes" tab on the server or site. Then, click the "Add background process" button. After providing the required fields, click the "Create background process" button. When creating a new background process, you'll need to configure the following settings: * **Name:** Provide a descriptive name for the background process to help identify it. * **Command:** Specify the command that the background process should execute. For example: `php artisan reverb:start`. * **Working Directory:** Set the working directory for your command. This field is optional and can be left empty. * **User:** Choose the operating system user to run the command. The `forge` user is used by default. * **Processes:** Define how many instances of the process should run simultaneously. * **Start Seconds:** Set the minimum runtime (in seconds) required to consider the process startup successful. * **Stop Seconds:** Specify how long Supervisor waits for a graceful shutdown before forcing termination. * **Stop Signal:** Choose the signal used to terminate the program during shutdown. ### Creating Laravel queue workers For sites using Laravel and Statamic, creating a new background process will display two tabs: **Queue worker** or **Custom**. The Queue worker tab is designed to make configuring Laravel queue workers easier. Instead of manually writing the `php artisan queue:work` command, you can use the form to configure the following options: * **PHP Version:** The PHP version to use for the queue worker. * **Queue Connection:** The name of the queue connection (e.g., `redis`, `database`, `sqs`) in your `config/queue.php` file. * **Number of Processes:** How many instances of the queue worker should run simultaneously. * **Queue:** Which queue(s) the worker should process. * **Backoff:** The number of seconds to wait before retrying a failed job. * **Sleep:** The number of seconds the worker should sleep when no jobs are available. * **Rest:** The number of seconds to rest between jobs. * **Timeout:** The maximum number of seconds a job is allowed to run. * **Tries:** The maximum number of times a job may be attempted. * **Memory:** The memory limit (in megabytes) for the queue worker. * **Environment:** The application environment. * **Force:** Force the worker to run even in maintenance mode. Laravel Forge will generate a preview of the queue worker command based on your selections, showing you the exact command that will be configured as a background process. This preview updates in real-time as you adjust the settings, allowing you to verify the configuration before creating the background process. ### Manually restarting background processes You can manually restart any background process using the command `sudo -S supervisorctl restart daemon-{id}:*`, where `{id}` represents the background process's unique identifier. For instance, to restart a background process with ID `65654`, you would run `sudo -S supervisorctl restart daemon-65654:*`. This command can also be integrated into your deployment scripts to restart background processes automatically during deployments. ## Log files Laravel Forge automatically configures each background process to maintain its own log file within the `/home/forge/.forge/` directory. Log files follow the naming convention `daemon-*.log`. When using Laravel Forge's user isolation features, daemon log files are located in the `.forge` directory within `/home/{username}`, where `{username}` corresponds to the user assigned to run the process. # Caches Source: https://forge.laravel.com/docs/resources/caches Learn how to connect to Redis™ and Memcached on your Laravel Forge server. ## Introduction Laravel Forge automatically installs both [Memcached](https://www.memcached.org/) and [Redis™](https://redis.io/) when provisioning [App Servers](/docs/servers/types#app-servers) or [Cache Servers](/docs/servers/types#cache-servers). Both services are secured by default, remaining inaccessible from external networks and only available for local server connections. ## Connecting to Redis and Memcached Both caching services are accessible via localhost using their standard ports: ```bash theme={null} MEMCACHED_HOST=127.0.0.1 MEMCACHED_PORT=11211 REDIS_HOST=127.0.0.1 REDIS_PASSWORD=null REDIS_PORT=6379 ``` ## Managing cache services Both Redis and Memcached run as system services and can be managed through standard service commands if needed. Laravel Forge handles the initial configuration and setup automatically, ensuring optimal performance for your applications. ### Configuring Redis password To configure the Redis password, navigate to the server's settings page. Then, click "Recipes" in the sidebar. Click the "Set password" button under the Redis section. After entering and confirming your desired password, click the "Add password" button to apply the changes. ## Network connectivity When connecting your applications to Redis or Memcached from another server within your infrastructure, you can utilize [Laravel Forge's server network feature](/docs/resources/network#server-network) to establish secure internal connections between servers. ### External connections Laravel Forge servers require SSH key authentication and don't support password-based access. When connecting to Redis through external clients, ensure you use your **private SSH key** for authentication. For example, when connecting via [TablePlus](https://tableplus.com/): Connecting to Redis with TablePlus # Database Backups Source: https://forge.laravel.com/docs/resources/database-backups Learn how to configure and manage automated database backups. ## Introduction Laravel Forge supports automated database backups that can be scheduled directly from your server's dashboard. You can choose to backup one or more databases at a specified frequency and also restore any of your recent backups. The backup script used by Forge is open source and can be [found on GitHub](https://github.com/laravel/forge-database-backups). Database backups are only available on the Business plan. ## Creating backup configurations Before creating a backup configuration, you must configure at least one [storage provider](/docs/storage-providers). When creating a backup configuration, you will select which storage provider to use. You may optionally override the bucket and directory settings for a specific backup configuration. This allows you to use the same storage provider but store backups in different locations. ### Frequency options Within the Laravel Forge database backup dashboard, you can select the frequency at which your database should be backed up: * Hourly * Daily (at a given time) * Weekly (on a given day and time) * Custom When using the API to create a **Daily** or **Weekly** backup, you may provide any valid time (e.g., `13:37`) to your schedule; however, for the sake of simplicity, the Laravel Forge UI allows you to select a time in 30 minute intervals. The time you select should be in your local time as reported by your web browser. The **Custom** option allows you to provide a custom cron expression. You may wish to use a service such as [crontab.guru](https://crontab.guru) to help you generate this. ### Backup retention Laravel Forge will automatically prune old backups for you. For example, if you have configured a backup retention rate of "five", only the last five backups will be stored within your storage provider. ### Notifications for failed backups You may provide an email address to be notified when a backup fails. If you need to notify multiple people, you should create a distribution list such as `team@example.com`. Laravel Forge will also display failed backups within the "Backups" panel of the Forge server's management dashboard. ## Managing backups ### Editing backups Existing backup configurations may be edited via the Laravel Forge UI. By default, the configuration details are locked to prevent accidental edits. You may click the "Edit" button to unlock editing. When changing the databases that should be backed up, Laravel Forge will ask for confirmation that it was an intended change. This is to prevent any future data loss in the event that a database is no longer part of a backup configuration. ### Deleting backup configurations You can delete a backup configuration by clicking the "Delete" button next to your chosen backup configuration under the "Backup Configurations" section of the server's "Backups" dashboard. When deleting a backup configuration, your backup archives **will not be removed from cloud storage**. You may remove these manually if you wish. ### Restoring backups You can restore backups to your database via the "Recent Backups" section. Click the "Restore" button next to your chosen backup. Backups will be restored to the database they were created from. If the backup configuration contains more than one database, you will be asked to select which database to restore. If you need to restore a backup to another server or database you may download the backup archive from your cloud storage provider and restore it using a database management tool such as [TablePlus](https://tableplus.com). ### Deleting backups If you need to delete an individual backup, you can do this by clicking the "Delete" button next to the backup. When deleting a backup, your backup archives **will be removed** from your cloud storage provider. Please take caution when removing backups. ### Backup output Each backup process will create its own log so that you can inspect the database backup process's output in the event of a failure. You can view the output of a backup by clicking the "Eye" icon next to your backup. ## Team permissions The ability to manage database backups is split into two permissions. * `server:create-backups` * `server:delete-backups` # Databases Source: https://forge.laravel.com/docs/resources/databases Learn how to manage databases on your Laravel Forge server. ## Introduction When provisioning a new Laravel Forge server that requires a database, you can choose between installing an [app server](/docs/servers/types#app-servers) or a dedicated [database server](/docs/servers/types#database-servers). The Forge dashboard provides comprehensive tools for managing databases, users, and permissions across your infrastructure. ## Creating servers with databases During server creation, you can select from several supported database servers: * MySQL (8.0, 8.4, 9.x) * MariaDB (10.11, 11.4) * PostgreSQL (13, 14, 15, 16, 17, 18) Laravel Forge automatically handles the installation process, creating a default `forge` database and user with a securely generated password. Both the database and root passwords are displayed upon server creation for your reference. MySQL 9.x is an [Innovation](https://dev.mysql.com/doc/refman/en/mysql-releases.html) release, designed for developers and teams who want access to the latest MySQL features and improvements. Innovation releases are production-ready, but each version is only supported until the next Innovation release ships. Laravel VPS servers are limited to the latest MySQL LTS and PostgreSQL versions only. ### Installing databases later If you need to add database functionality to an existing server, you can install one through the server's "Databases" management tab. Once installed, you'll have full database management capabilities through the Laravel Forge interface. If the server already has a database installed (MySQL, MariaDB, or PostgreSQL), Forge will not allow installing a different database type on the same server. If you created a "Web Server", database installation is not supported. Web servers include only the essential software needed for PHP applications. For combined web and database functionality, provision an "App Server" instead. ## Managing database passwords You can reset both `root` and `forge` database user passwords using the password reset feature in Laravel Forge's "Databases" management tab. Never change `root` or `forge` database passwords manually or outside the Laravel Forge dashboard. This will break Forge's ability to connect to and manage your database. ## Connecting to databases via database clients Database connections require SSH key authentication by default and don't support password-only access. When using GUI database clients to connect to your Laravel Forge database, you'll need SSH authentication with your **private SSH key**. For example, when configuring [TablePlus](https://tableplus.com): Connecting to a database with TablePlus ### Using database connection URLs Some clients like TablePlus support connection URLs for simplified setup. Laravel Forge automatically generates these URLs for you, though you'll need to enter your password manually since it's not included in the URL for security purposes. Forge also provides a convenient button to launch your preferred database client directly. ## Connecting to external databases You can connect your application to a database hosted on another Laravel Forge server using [Laravel Forge's server network feature](/docs/resources/network#server-network). When both servers [meet the network requirements](/docs/resources/network#server-network), follow these steps: 1. **Configure server network access:** * Navigate to your application server's "Network" settings * Enable the connection to your database server under the "Server Network" section 2. **Update application configuration:** * Access your site's environment page * Set the database host to the external server's private IP address * Update database credentials to match the external database ## Managing databases Laravel Forge provides advanced database management capabilities for MySQL, MariaDB, and PostgreSQL servers. ### Creating databases Create new databases through the server's "Storage" > "Database" tab. You only need to provide the database name—the `forge` user automatically receives access permissions. ### Syncing databases While we recommend managing databases through Laravel Forge for consistency, you can sync externally created databases using the "Sync Databases" button. Note that system-reserved database names are excluded from syncing: * `mysql`, `information_schema`, `performance_schema`, `sys` * `postgres`, `template0`, `template1` ### Creating database users The database panel allows you to create additional users by specifying the username, password, and accessible databases. You can also designate users as read-only, restricting them to select operations while preventing insert, update, or delete actions. ## Database upgrades Laravel Forge doesn't provide automatic database server upgrades. If you need to upgrade your database software, you'll need to handle this process manually. # Managed Cache Source: https://forge.laravel.com/docs/resources/managed-cache Learn how to create and manage fully managed cache clusters with Laravel Forge. ## Introduction Laravel Forge managed cache clusters let you provision fully managed Valkey clusters without worrying about server administration, patches, or infrastructure. Each cluster includes high availability options and real-time monitoring, all managed directly from the Forge dashboard. Managed cache clusters are offered through our infrastructure partnership with DigitalOcean and billed hourly through Forge, so there is no need to manage a separate provider account. ## Creating a cache cluster To create a new managed cache cluster, navigate to your organization's "Resources" section, select the "Cache" page, and click "Create cache cluster." You will be prompted to configure the following options: * **Cluster name**: A unique name for your cluster. This cannot be changed after creation. * **Region**: The datacenter region where your cluster will be provisioned. * **Private network**: Choose "Laravel managed" for automatic networking, or select an existing VPC in the chosen region. * **Compute size**: The CPU and memory allocation for your cluster. Sizes are grouped into categories such as Standard and Memory Optimized. * **High availability**: When enabled, a standby node is automatically maintained and will replace the primary node in case of failure. Enabling high availability doubles the monthly cost. The estimated monthly cost is displayed at the bottom of the creation modal and updates dynamically as you adjust options. After creating a cluster, it may take a few minutes for initialization to finish. The cluster's overview page will display a loading state until the cluster is ready. ## Cluster overview Once your cluster is ready, the overview page displays the cluster's connection credentials. ### Connection credentials The credentials panel provides the connection details needed to connect to your cache cluster. Credentials are organized into tabs: * **Primary**: The main read/write endpoint for your cluster. * **Standby**: The standby endpoint, available when high availability is enabled. Each tab displays the host, port, default username, and password. Connection URLs are also provided for quick setup with clients such as [TablePlus](https://tableplus.com). By default, managed cache clusters only accept connections from resources within the same VPC. This means you must connect from a [Laravel VPS](/docs/servers/laravel-vps) server within the same Forge organization to use private connectivity. Servers provisioned through other providers (e.g., DigitalOcean, Hetzner, or AWS) do not share the same private network and cannot connect privately, even if they are in the same region. To allow connections from servers outside the VPC, you must enable [public access](#public-access) in the cluster's settings. ## Monitoring The "Observe" page provides real-time monitoring charts for your cache cluster: * **CPU usage**: Percentage of CPU utilization over time. * **Memory usage**: Percentage of memory utilization over time. * **Disk usage**: Percentage of disk utilization over time. You can view metrics for the last 1 day, 7 days, or 30 days using the timeframe selector. ## Settings The cluster's "Settings" page allows you to manage the following: ### Configuration You can update the compute size and high availability status of your cluster by clicking "Update configuration". The cluster will enter a "Resizing" state during the update and will be temporarily unavailable. Downscaling compute is currently not supported. You may only increase the compute size of your cluster. ### Upgrade window Required upgrades, such as Valkey patches, are applied automatically during the configured maintenance window. You can set the preferred day of the week and hour (UTC) for these upgrades. ### Public access By default, managed cache clusters only accept connections from resources within the same private network. Only [Laravel VPS](/docs/servers/laravel-vps) servers within the same Forge organization share this private network. Servers from other providers cannot connect privately, even if they are located in the same region. Enabling public access allows connections from any IP address. A confirmation prompt is displayed when enabling this setting. ### Deleting a cluster You can permanently delete a cache cluster from the "Danger" section of the settings page. This action is irreversible. All data within the cluster will be permanently destroyed. ## Pricing Usage for managed cache clusters is billed hourly, similar to [Laravel VPS servers](/docs/servers/laravel-vps#pricing). The total monthly cost is determined by: * **Compute size**: Each size tier has a base monthly cost. * **High availability**: When enabled, the monthly cost is doubled to account for the standby node. The following table outlines the base monthly pricing for each compute size, per Forge subscription plan. These prices do not include high availability costs. You can view your current usage and billing history on the organization's "Usage" page. # Managed Databases Source: https://forge.laravel.com/docs/resources/managed-databases Learn how to create and manage fully managed database clusters with Laravel Forge. ## Introduction Laravel Forge managed databases let you provision fully managed MySQL and PostgreSQL database clusters without worrying about server administration, patches, or infrastructure. Each cluster includes high availability options, automated daily backups, point-in-time recovery, and real-time monitoring, all managed directly from the Forge dashboard. Managed databases are offered through our infrastructure partnership with DigitalOcean and billed hourly through Forge, so there is no need to manage a separate provider account. ### Supported engines * MySQL 8.4 * PostgreSQL (17, 18) ## Creating a database cluster To create a new managed database cluster, navigate to your organization's "Resources" page and click "Create database cluster." You will be prompted to configure the following options: * **Cluster name**: A unique name for your cluster. This cannot be changed after creation. * **Engine**: The database engine and version to use. * **Region**: The datacenter region where your cluster will be provisioned. * **Private network**: Choose "Laravel managed" for automatic networking, or select an existing VPC in the chosen region. * **Compute size**: The CPU and memory allocation for your cluster. Sizes are grouped into categories such as Standard, General Purpose, and Storage Optimized. * **Storage**: The disk storage for your cluster. The available range depends on the selected compute size and can be adjusted in increments of 10 GB. * **High availability**: When enabled, a standby node is automatically maintained and will replace the primary node in case of failure. Enabling high availability doubles the monthly cost. The estimated monthly cost is displayed at the bottom of the creation modal and updates dynamically as you adjust options. After creating a cluster, it may take a few minutes for the cluster to finish initializing. The cluster's overview page will display a loading state until the cluster is ready. ## Cluster overview Once your cluster is ready, the overview page displays the cluster's connection credentials, databases, users, and read replicas. ### Connection credentials The credentials panel provides the connection details needed to connect to your database cluster. Credentials are organized into tabs: * **Primary**: The main read/write endpoint for your cluster. * **Standby**: The standby endpoint, available when high availability is enabled. * **Replicas**: Individual connection details for each read replica. Each tab displays the host, port, default username, and password. Connection URLs are also provided for quick setup with database clients such as [TablePlus](https://tableplus.com). By default, managed database clusters only accept connections from resources within the same VPC. This means you must connect from a [Laravel VPS](/docs/servers/laravel-vps) server within the same Forge organization to use private connectivity. Servers provisioned through other providers (e.g., DigitalOcean, Hetzner, or AWS) do not share the same private network and cannot connect privately, even if they are in the same region. To allow connections from servers outside the VPC, you must enable [public access](#public-access) in the cluster's settings. ## Managing databases You can create multiple database schemas within a single cluster. To create a new database, navigate to the cluster's overview page, click "Add database" in the "Databases" section, and provide a database name. To delete a database, click the action menu next to the database and select "Delete". ## Managing users Database users control who can connect to your cluster. To create a new user, click "Add user" in the "Users" section of the cluster's overview page, enter a username, and select which databases you would like to give the user access to. A secure password is automatically generated for each user. To delete a user, click the action menu next to the user and select "Delete". ## Read replicas Read replicas allow you to distribute read query load across multiple nodes, improving performance for read-heavy applications. Each replica has its own connection endpoint displayed in the credentials panel. To create a read replica, click "Add replica" in the "Replicas" section of the cluster's overview page and provide a name. The replica is then initialized, and its status updates in real time. To delete a replica, click the action menu next to the replica and select "Delete". ## Backups and restoration Managed database clusters include automated daily backups at no additional cost. ### Configuring backup time By default, backups are taken daily at 5:30 AM UTC. You can change the backup time by navigating to the cluster's "Backups" page and clicking the current backup time to open the configuration modal. The time is configured in UTC. ### Point-in-time recovery You can restore your database to any point in time within the last 7 days. This is useful for recovering from accidental data loss or corruption. To perform a point-in-time restore, navigate to the "Backups" page and click "Restore" in the "Restore from point in time" section. You will need to select a date and time, then provide a name for the new cluster. ### Restoring from a backup You can also restore from a specific daily backup listed on the "Backups" page. Click the action menu next to the backup and select "Restore". You will need to provide a name for the new cluster. Both restoration methods create a new database cluster with the restored data. Your existing cluster remains unchanged. ## Monitoring The "Observe" page provides real-time monitoring charts for your database cluster: * **CPU usage**: Percentage of CPU utilization over time. * **Memory usage**: Percentage of memory utilization over time. * **Disk usage**: Percentage of disk utilization over time. You can view metrics for the last 1 day, 7 days, or 30 days using the timeframe selector. ## Settings The cluster's "Settings" page allows you to manage the following: ### Configuration You can update the compute size, storage allocation, and high availability status of your cluster by clicking "Update configuration". The cluster will enter a "Resizing" state during the update and will be temporarily unavailable. Downscaling compute is currently not supported. You may only increase the compute size of your cluster. ### Upgrade window Required upgrades, such as database engine patches, are applied automatically during the configured maintenance window. You can set the preferred day of the week and hour (UTC) for these upgrades. ### Public access By default, managed database clusters only accept connections from resources within the same private network. Only [Laravel VPS](/docs/servers/laravel-vps) servers within the same Forge organization share this private network. Servers from other providers cannot connect privately, even if they are located in the same region. Enabling public access allows connections from any IP address. A confirmation prompt is displayed when enabling this setting. ### Deleting a cluster You can permanently delete a database cluster from the "Danger" section of the settings page. This action is irreversible. All data, databases, users, and replicas within the cluster will be permanently destroyed. ## Pricing Usage for managed database clusters is billed hourly, similar to [Laravel VPS servers](/docs/servers/laravel-vps#pricing). The total monthly cost is determined by: * **Compute size**: Each size tier has a base monthly cost. * **Additional storage**: Storage beyond the base allocation included with your compute size is charged per 10 GB block. * **High availability**: When enabled, the monthly cost is doubled to account for the standby node. The following table outlines the base monthly pricing for each compute size, per Forge subscription plan. These prices do not include additional storage or high availability costs. You can view your current usage and billing history on the organization's "Usage" page. # Network Source: https://forge.laravel.com/docs/resources/network Learn how to manage your server network and firewall. ## Introduction Laravel Forge provides comprehensive network management capabilities. This includes firewall configuration and server-to-server connectivity management, allowing you to control traffic flow and establish secure connections between your infrastructure components. Manually created `ufw` rules on your server won't appear in the Laravel Forge dashboard. Forge only displays and manages rules created through its interface. ## Managing server networks and firewalls ### Server networks Server networks simplify the process of connecting servers for dedicated database, cache, or queue functionality. To establish internal network connections, servers must meet these requirements: * Created by the same server provider * Using identical server provider credentials * Owned by the same user account * Located within the same geographical region and VPC Once network access is granted between servers, you can connect using private IP addresses for secure, high-performance internal communication. Laravel VPS servers created within the same organization are automatically placed on a shared VPC that is private to that organisation, so traffic between them is routed internally even when using public IP addresses. No private IP is provided in the Forge UI as a result. ## Firewall management Laravel Forge provides complete firewall control, allowing you to open specific ports to internet traffic. Common use cases include opening port `21` for FTP services or custom application ports. ### Creating firewall rules To create a firewall rule, navigate to your server's settings page and click the "Network" tab. Then, click the "Add rule" button. Configure the rule by specifying the port or port range, type, and optionally restrict access to specific IP addresses. Click the "Create rule" button to apply the new firewall configuration. When creating rules, you can specify port ranges using the format `8000:8010` to open multiple consecutive ports, or provide multiple IP addresses as a comma-separated list for enhanced security. ### Deleting firewall rules To delete a firewall rule, navigate to your server's "Network" tab. Then, click on the dropdown next to the rule you want to remove. Click the "Delete" dropdown item and confirm the deletion. **Warning:** Never delete the SSH rule (typically port 22) as this will prevent Laravel Forge from connecting to and managing your server. ### Enhanced security options You can restrict port access to specific IP addresses for additional security. The "From IP Address" field accepts multiple addresses as a comma-separated list: `192.168.1.1,192.168.1.2,192.168.1.3`. ### Allow and deny rules Configure traffic permissions by selecting allow or deny actions for each rule. Deny rules prevent matching traffic from reaching services and are automatically prioritized above allow rules for proper security enforcement. New IPv4 deny rules are positioned above existing deny rules for optimal priority handling. IPv6 rules currently don't support first-priority positioning in UFW. ## Default firewall configuration Laravel Forge automatically configures essential firewall rules during server provisioning: * **SSH:** Port 22 access from any IP address * **HTTP:** Port 80 access from any IP address * **HTTPS:** Port 443 access from any IP address While port 22 remains open for SSH connections, only SSH key-based authentication is accepted, preventing brute force attacks. **Never delete the SSH rule—doing so will break Forge's ability to connect to and manage your server.** Mail ports (25, 465, 587) are blocked by default on Laravel VPS servers to prevent abuse. If you need to send email from your server, use an HTTP / API based service like [Resend](https://resend.com), or contact [Laravel Forge support](/docs/support) to request these ports be unblocked. ### Health check service IP addresses If you have enabled [deployment health checks](/docs/sites/deployments#deployment-health-checks) for your sites, you should ensure that the following IP addresses are allowed through your HTTP and HTTPS firewall rules. Health check requests are made from these addresses to verify your application is accessible after deployments. These IPs will **not make** SSH connections to the server. * 209.38.170.132 * 206.189.255.228 * 139.59.222.70 Alternatively, you can allow the health check service by its `User-Agent` header value: `Laravel-Healthcheck/1.0`. ### Recovering from deleted SSH rules If you accidentally delete the SSH firewall rule (typically port 22), Forge loses server connectivity and cannot restore the rule automatically. To resolve this issue: 1. Access your server directly through your cloud provider's console (such as DigitalOcean's remote access feature) 2. Connect as the `root` user 3. Restore SSH access by running: `ufw allow 22` This will re-establish Forge's connection capability to your server. # Object Storage Source: https://forge.laravel.com/docs/resources/object-storage Learn how to create and manage S3-compatible object storage buckets with Laravel Forge. Powered by [Cloudflare R2](https://www.cloudflare.com/developer-platform/products/r2/) ## Introduction Laravel Forge allows you to create S3-compatible object storage buckets as organization-level resources from the Forge dashboard. Object storage is offered in partnership with Cloudflare R2. Buckets are managed independently at the organization level. To use a bucket with a site, retrieve the bucket credentials from the Forge dashboard and configure them as [environment variables](/docs/sites/environment-variables) on the site. Object storage may be used as your Laravel application's [file storage backend](https://laravel.com/docs/filesystem), allowing you to interact with the bucket via Laravel's `Storage` facade. ## Prerequisites Before using object storage, you should ensure your application includes the `league/flysystem-aws-s3-v3` package in its `composer.json` dependencies: ```shell theme={null} composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies ``` ## Creating buckets To create a new object storage bucket, navigate to your organization's "Resources" page, open the "Object storage" tab, and click "New bucket." You can view your current usage and billing history on the organization's "Usage" page. ### Public access When creating or editing a bucket, you may configure **Public access** by toggling the setting on or off. When public access is disabled, all files within the bucket are private and are not publicly accessible via the internet. However, temporary public URLs may be generated for files within the bucket using the `Storage::temporaryUrl` method [offered by Laravel](https://laravel.com/docs/filesystem#temporary-urls). This is typically used for private assets like personal documents uploaded by your application's users. When public access is enabled, all files within the bucket are publicly accessible via the internet through a Forge-provided URL. This is typically used for publicly viewable assets like user avatars. ## Using buckets with your sites To use a bucket with a Laravel site, retrieve the bucket credentials from the Forge dashboard and add them to the site's environment variables. ### Retrieving bucket credentials Navigate to your organization's "Resources" page, open the "Object storage" tab, click the "..." icon next to the bucket, and select "View credentials." The credentials modal provides the name, endpoint, access key ID, and access key secret needed to connect to the bucket. ### Configuring environment variables Navigate to your site's "Settings" panel and open the [Environment](/docs/sites/environment-variables) tab. Add the bucket credentials as environment variables using the values from the credentials modal: ```env theme={null} AWS_ACCESS_KEY_ID=your-access-key-id AWS_SECRET_ACCESS_KEY=your-access-key-secret AWS_DEFAULT_REGION=auto AWS_BUCKET=your-bucket-name AWS_ENDPOINT=your-bucket-endpoint AWS_USE_PATH_STYLE_ENDPOINT=false FILESYSTEM_DISK=s3 ``` Set `FILESYSTEM_DISK` to the disk name defined in your application's `config/filesystems.php` file. If you are using Laravel's default `s3` disk configuration, set `FILESYSTEM_DISK=s3`. After saving your environment variables, redeploy the site or run `php artisan config:cache` so your application picks up the new configuration. ### Accessing the bucket in your application Once configured, you may interact with the bucket via Laravel's `Storage` facade using the disk name defined in your filesystem configuration: ```php theme={null} return Storage::disk('s3')->get('photo.jpg'); ``` If the bucket is configured as your application's default disk, you do not need to provide the disk name: ```php theme={null} return Storage::get('photo.jpg'); ``` ## CORS policy Laravel Forge automatically manages CORS (Cross-Origin Resource Sharing) policies for your object storage buckets to ensure browsers will permit cross-origin requests. ### Allowed origins If your application uploads files directly from the browser, you should add your site's domains to the bucket's allowed origins. This includes any custom domains and `on-forge.com` vanity domains associated with the site. You may also specify additional origins that should be allowed to access your bucket. This is particularly useful for: * Local development environments, such as `http://example.test` * External domains that need access to your bucket * Testing from non-production environments To add allowed origins: 1. Navigate to your organization's "Resources" page and open the "Object storage" tab. 2. Click the "**...**" menu next to the bucket you want to configure. 3. Select "**Edit settings**". 4. In the "**Allowed origins**" field, enter each origin on a separate line. This field is only visible when public access is enabled. 5. Each origin must be prefixed with the protocol (`https://` or `http://`). ### Local development To connect to your object storage buckets from your local Laravel application, add your local development domain, such as `http://example.test`, to the bucket's allowed origins. This makes it easy to test file uploads and storage operations during development. ### Technical details The CORS policy applied to your buckets allows the following: * **Methods:** GET, POST, PUT, DELETE, HEAD * **Headers:** All headers (`*`) are permitted * **Origins:** Any origins you have configured for the bucket ## Connecting from your local machine To connect to your bucket from your local machine using a Cloudflare R2-compatible bucket management client like [Cyberduck](https://cyberduck.io/): 1. Navigate to your organization's "Resources" page and open the "Object storage" tab. Then, click the "..." icon next to the bucket and click "View credentials". 2. The credentials modal provides the name, endpoint, access key ID, and access key secret needed to connect to your bucket. 3. Open Cyberduck, select "+" in the bottom-left corner to create a new bookmark, and select "Cloudflare R2 Storage (S3)" as the connection type. If this is your first time using the Cloudflare R2 Storage connection, you may need to add it from `Settings > Profiles`. For more information, review Cyberduck's [Cloudflare R2 documentation](https://docs.cyberduck.io/protocols/s3/cloudflare/). 4. Enter the `AWS_ENDPOINT` bucket credentials value into the Cyberduck "Server" field. 5. Enter the `AWS_ACCESS_KEY_ID` bucket credentials value into the Cyberduck "Access Key ID" field. 6. Enter the `AWS_SECRET_ACCESS_KEY` bucket credentials value into the Cyberduck "Access Key Secret" field. 7. Enter the `AWS_BUCKET` value into the Cyberduck "Path" field under "More Options". If you do not see "More Options," you likely clicked "Open Connection" instead of creating a new bookmark. 8. Optionally, give your bookmark a nickname. 9. Close the "Open Connection" modal and connect to your bucket. ## Editing buckets You may edit object storage buckets via your organization's "Resources" page. From the "Resources" page, navigate to the "Object storage" tab and click the "..." icon for the bucket you would like to edit. Then, click "Edit settings". ## Deleting buckets You may delete an object storage bucket via your organization's "Resources" page. From the "Resources" page, navigate to the "Object storage" tab and click the "..." icon for the bucket you would like to delete. Then, click "Delete bucket". # Packages Source: https://forge.laravel.com/docs/resources/packages Learn how Laravel Forge manages Composer and npm credentials for your servers and sites. ## Introduction Laravel Forge provides seamless management of authentication credentials for both Composer and npm package registries. Credentials can be configured at the server level or site level, depending on your needs. ## Composer credentials Laravel Forge manages Composer authentication through the "http-basic" configuration in your server's or site's `auth.json` file. These credentials are securely stored and automatically applied to your Composer operations. ### Credential levels #### Server-level credentials Server-level Composer credentials are shared across all sites running under the same Ubuntu user account. For instance, if you have multiple sites deployed under the `forge` user, they all have access to the same globally stored credentials located at `~/.config/composer/auth.json`. To manage server-level credentials, navigate to your server's dashboard, select the "PHP" tab, then click the "Composer" sidebar item. #### Site-level credentials Site-level credentials apply exclusively to individual sites, providing granular control when different sites require unique authentication for the same packages. This is particularly useful when multiple sites under the same user need different access permissions or licensing. To manage site-level credentials, navigate to your site's dashboard, select the "Settings" tab, then click the "Composer" sidebar item. ### Managing credentials #### Adding credentials To add new Composer credentials, navigate to the appropriate Composer management page and click the "Add credential" button. Complete the required fields and click "Add credential" to save: * **Repository URL**: The URL Composer uses to match credentials with the corresponding package provider. * **Username**: Typically an email address or unique identifier required by the package provider. * **Password**: The associated password or license key for authentication. #### Updating credentials To modify existing credentials, navigate to the appropriate Composer page, locate the credential you want to update, open its dropdown menu, and select "Edit." Make your changes and save the updated information. #### Removing credentials To delete credentials, navigate to the appropriate Composer dashboard, locate the credential you want to remove, open its dropdown menu, select "Delete", and confirm the removal when prompted. ## npm credentials Laravel Forge manages npm registry authentication through `.npmrc` files. This allows you to install packages from private registries such as GitHub Packages, npm organizations, or any registry that supports token-based authentication. Each credential consists of three parts: * **Registry**: The hostname of the private registry (e.g., `npm.pkg.github.com`). * **Token**: The authentication token provided by your registry. * **Scopes**: One or more npm scopes (e.g., `@myorg`) that should be routed to this registry. ### Credential levels #### Server-level credentials Server-level npm credentials are stored in the `~/.npmrc` file of the selected Ubuntu user. These credentials are shared across all sites running under that user account. To manage server-level credentials, navigate to your server's dashboard, select the "Node" tab, then click the "npm" sidebar item. If your server has multiple Ubuntu users with sites, you can select which user's credentials to manage from the user dropdown. #### Site-level credentials Site-level npm credentials provide granular control over registry authentication for individual sites. Forge stores site-level credentials in a separate `.npmrc.forge` file to avoid conflicts with any `.npmrc` file that may already be committed to your repository. During deployments, Forge automatically merges the credentials from `.npmrc.forge` into the site's `.npmrc` file. If both files contain credentials for the same registry, the Forge-managed credentials take precedence. To manage site-level credentials, navigate to your site's dashboard, select the "Settings" tab, then click the "npm" sidebar item. If Forge detects credentials committed to your repository's `.npmrc` file, a warning banner will be displayed on the npm credentials page. We recommend migrating these credentials to Forge for centralized management. ### Managing credentials #### Adding credentials To add new npm credentials, navigate to the appropriate npm management page and click the "Add credential" button. Complete the required fields and click "Add credential" to save: * **Registry**: The hostname of the private registry (e.g., `npm.pkg.github.com`). Forge automatically normalizes the URL by stripping the protocol and trailing slashes. * **Token**: The authentication token for the registry (e.g., a GitHub personal access token). * **Scopes**: Optional npm scopes to route to this registry. Each scope should start with `@` (e.g., `@myorg`). A scope can only be assigned to one registry. #### Updating credentials To modify existing credentials, navigate to the appropriate npm page, locate the credential you want to update, open its dropdown menu, and select "Edit." Make your changes and save the updated information. #### Removing credentials To delete credentials, navigate to the appropriate npm dashboard, locate the credential you want to remove, open its dropdown menu, select "Delete", and confirm the removal when prompted. ### Zero-downtime deployments npm credentials are fully compatible with zero-downtime deployments. When creating a new release, Forge automatically merges the Forge-managed credentials into the release's `.npmrc` file before installing dependencies. No additional configuration is required. # Scheduler Source: https://forge.laravel.com/docs/resources/scheduler Learn how to configure and manage scheduled jobs on your Laravel Forge server. ## Scheduled jobs Laravel Forge enables you to configure scheduled jobs that run commands at specified intervals on either a server or site level. You can choose from predefined frequencies or create custom Cron schedules tailored to your specific needs. If your scheduled job fails to run, verify that the command path is correct and accessible. ### Laravel application scheduling For Laravel applications using the built-in [scheduler feature](https://laravel.com/docs/scheduling), you can use the [Laravel integration](/docs/sites/laravel#laravel-scheduler) to quickly configure the scheduled job. ### Default scheduled jobs Laravel Forge automatically configures essential maintenance jobs during server provisioning: * **Update Composer:** Runs `composer self-update` nightly to keep Composer current * **Remove unused packages:** Performs Ubuntu package cleanup weekly to maintain system efficiency These default jobs help ensure your server remains updated and optimized without manual intervention. ## Managing scheduled jobs ### Creating scheduled jobs To create a scheduled job, navigate to "Server / Processes / Scheduler" or "Site / Processes / Scheduler" depending on your requirements. Then, click the "Add scheduled job" button. Configure the command, user, and frequency settings, then click the "Create scheduled job" button to activate it. Server-level jobs are ideal for system maintenance tasks, while site-level jobs are perfect for application-specific commands like Laravel's scheduler or custom deployment scripts. ### Editing scheduled jobs To edit a scheduled job, navigate to the appropriate "Processes / Scheduler" section. Then, click on the dropdown next to the job you want to modify. Click the "Edit" dropdown item and update the job configuration as needed. ### Running scheduled jobs manually You can manually execute a scheduled job by clicking on the dropdown next to the job and selecting "Run". This is useful for testing jobs or running them outside their normal schedule. Jobs executed via the "Run" dropdown option have a 60 second maximum execution length timeout. Regular scheduled jobs executed via cron do not have this timeout limitation. ### Deleting scheduled jobs To delete a scheduled job, navigate to the "Processes / Scheduler" section. Then, click on the dropdown next to the job you want to remove. Click the "Delete" dropdown item and confirm that you want to delete the scheduled job. ## Heartbeats Heartbeats provide proactive monitoring for your scheduled jobs, ensuring they execute successfully and on time. This feature helps you identify failed or stuck jobs before they impact your application. ### Configuring heartbeat monitoring When creating or editing a scheduled job, enable monitoring by toggling the "Monitor with heartbeats" option. Once enabled, specify the notification threshold by setting the "Notify me after" value in minutes. Laravel Forge generates a unique endpoint URL that your scheduled job must ping upon successful completion. If Forge doesn't receive a heartbeat ping within the specified timeframe, you'll be notified that the job is missing or has failed to execute. ### Using heartbeat endpoints Your scheduled job should include a request to the provided heartbeat endpoint as its final step. This confirms successful execution and resets the monitoring timer. You can implement the ping using curl, HTTP libraries, or Laravel's HTTP client depending on your job's requirements. This monitoring system is particularly valuable for critical maintenance tasks, data processing jobs, and backup operations where timely execution is essential for your application's health. Applications running Laravel can use the `pingBefore` and `thenPing` methods to automatically send heartbeats when using the Laravel scheduler. [Read the Laravel documentation](https://laravel.com/docs/scheduling#pinging-urls). # Laravel Forge SDK Source: https://forge.laravel.com/docs/sdk A PHP SDK for interacting with the Laravel Forge API. View the Laravel Forge SDK on GitHub View the Laravel Forge API documentation ## Introduction The [Laravel Forge SDK](https://github.com/laravel/forge-sdk) provides an expressive PHP interface for interacting with the Laravel Forge API and managing your servers, sites, and other resources programmatically. The SDK targets the Forge API and provides access to platform resources such as servers, sites, databases, scheduled jobs, background processes, integrations, teams, roles, and more. ## Installation To install the SDK in your project, you should require the package via Composer: ```bash theme={null} composer require laravel/forge-sdk ``` ## Upgrading From v3.x Forge SDK v4.0 targets the Forge API v2 and contains significant breaking changes. Every resource endpoint now requires an organization slug as the first argument. Several action traits have been renamed, and a handful of legacy features have been removed. When upgrading from v3.x, we recommend carefully reviewing the [v4.0 upgrade guide](https://github.com/laravel/forge-sdk/blob/4.x/UPGRADE-4.0.md) on GitHub. The upgrade guide details every method signature change, the renamed action traits, and the migration strategy you should follow. ## Basic Usage You may create an instance of the SDK by passing an API token generated from [Forge's API dashboard](https://forge.laravel.com/profile/api): ```php theme={null} $forge = new Laravel\Forge\Forge($token); ``` ### The Organization Slug Starting in v4.0, every resource endpoint is scoped to an [organization](/docs/organizations). Before making most calls, you must determine the slug of the organization you want to interact with by listing the authenticated user's organizations: ```php theme={null} $organizations = $forge->organizations(); $organizationSlug = $organizations[0]->slug; ``` The following endpoints are examples of methods that do not require an organization slug: * `$forge->user()` / `$forge->me()` * `$forge->organizations()` * `$forge->providers()` * `$forge->permissions()` * `$forge->predefinedRoles()` We recommend caching the organization slug in your application configuration rather than resolving it on every request. ### Retrieving Resources Once you have an organization slug, you may retrieve resources scoped to that organization: ```php theme={null} $servers = $forge->servers($organizationSlug); $server = $forge->server($organizationSlug, $serverId); ``` Each resource is represented by a class such as `Laravel\Forge\Resources\Server`. Resource instances expose public properties such as `$name`, `$id`, `$size`, and `$region`. ### Paginated Collections Collection methods such as `servers()`, `serverSites()`, and `recipes()` return a `Laravel\Forge\CursorPaginator` rather than a plain array. The paginator may be iterated directly for the current page, iterated lazily to fetch additional pages on demand, or converted to an array: ```php theme={null} // Iterate the current page foreach ($forge->servers($organizationSlug) as $server) { echo $server->name; } // Lazily iterate across every page — the next cursor is fetched on demand foreach ($forge->servers($organizationSlug)->lazy() as $server) { echo $server->name; } // Snapshot the current page as a plain array $page = $forge->servers($organizationSlug)->toArray(); ``` ### Creating Resources When creating resources, you should pass the organization slug as the first argument and the request payload as the second: ```php theme={null} use Laravel\Forge\ServerProviders; use Laravel\Forge\InstallableServices; $server = $forge->createServer($organizationSlug, [ 'provider' => ServerProviders::DIGITAL_OCEAN, 'credential_id' => 1, 'name' => 'test-via-api', 'type' => 'app', 'size' => '01', 'database' => 'test123', 'database_type' => InstallableServices::POSTGRES, 'php_version' => InstallableServices::PHP_84, 'region' => 'ams2', ]); ``` For a full list of parameters accepted by each endpoint, consult the [official Forge API documentation](https://forge.laravel.com/api-documentation). ### Waiting for Asynchronous Operations Some operations, such as creating a server or a site, are processed asynchronously by Forge. By default, the SDK will poll the API every few seconds until the resource has finished provisioning, up to a maximum of 30 seconds: ```php theme={null} $site = $forge->createSite($organizationSlug, $serverId, [ 'domain' => 'example.com', 'type' => 'php', ]); ``` If you do not wish to wait, you may pass `false` as the final argument: ```php theme={null} $site = $forge->createSite($organizationSlug, $serverId, $data, false); ``` You may customize the timeout in seconds using the `setTimeout` method: ```php theme={null} $site = $forge->setTimeout(120)->createSite($organizationSlug, $serverId, $data); ``` If the timeout is exceeded, a `Laravel\Forge\Exceptions\TimeoutException` will be thrown. ## Managing Organizations ```php theme={null} $organizations = $forge->organizations(); $organization = $forge->organization($organizationSlug); // Server credentials $credentials = $forge->serverCredentials($organizationSlug); $credential = $forge->serverCredential($organizationSlug, $credentialId); ``` ## Managing Servers ```php theme={null} $servers = $forge->servers($organizationSlug); $server = $forge->server($organizationSlug, $serverId); $server = $forge->createServer($organizationSlug, $data); $forge->deleteServer($organizationSlug, $serverId); // Server actions, such as reboot $forge->createServerAction($organizationSlug, $serverId, [ 'action' => 'reboot', ]); // Archived servers $archivedServers = $forge->archivedServers($organizationSlug); ``` ### Server Service Actions ```php theme={null} $forge->performNginxAction($organizationSlug, $serverId, ['action' => 'restart']); $forge->performMySQLAction($organizationSlug, $serverId, ['action' => 'restart']); $forge->performPostgresAction($organizationSlug, $serverId, ['action' => 'restart']); $forge->performRedisAction($organizationSlug, $serverId, ['action' => 'restart']); $forge->performPHPAction($organizationSlug, $serverId, ['action' => 'restart']); $forge->performSupervisorAction($organizationSlug, $serverId, ['action' => 'restart']); ``` ## Managing Sites ```php theme={null} $sites = $forge->serverSites($organizationSlug, $serverId); $site = $forge->organizationSite($organizationSlug, $siteId); $site = $forge->createSite($organizationSlug, $serverId, $data); $site = $forge->updateSite($organizationSlug, $serverId, $siteId, $data); $forge->deleteSite($organizationSlug, $serverId, $siteId); ``` ### Site Domains and Certificates ```php theme={null} $domains = $forge->domains($organizationSlug, $serverId, $siteId); $domain = $forge->createDomain($organizationSlug, $serverId, $siteId, $data); $forge->deleteDomain($organizationSlug, $serverId, $siteId, $domainId); $certificates = $forge->domainCertificates($organizationSlug, $serverId, $siteId, $domainId); $active = $forge->activeDomainCertificate($organizationSlug, $serverId, $siteId, $domainId); $certificate = $forge->certificate($organizationSlug, $serverId, $siteId, $domainId, $certificateId); $forge->createCertificate($organizationSlug, $serverId, $siteId, $domainId, $data); $forge->deleteCertificate($organizationSlug, $serverId, $siteId, $domainId, $certificateId); ``` ### Site Deployments ```php theme={null} $webhooks = $forge->webhooks($organizationSlug, $serverId, $siteId); $forge->createWebhook($organizationSlug, $serverId, $siteId, $data); $script = $forge->deploymentScript($organizationSlug, $serverId, $siteId); $forge->updateDeploymentScript($organizationSlug, $serverId, $siteId, $content); $deployment = $forge->createDeployment($organizationSlug, $serverId, $siteId); $forge->createPushToDeploy($organizationSlug, $serverId, $siteId, $data); $forge->deletePushToDeploy($organizationSlug, $serverId, $siteId); ``` ### Laravel Integrations The SDK exposes first-class support for managing Laravel ecosystem integrations on each site, including Horizon, Octane, Reverb, Pulse, Inertia, Laravel Maintenance Mode, and the Laravel Scheduler: ```php theme={null} $forge->getHorizon($organizationSlug, $serverId, $siteId); $forge->createHorizon($organizationSlug, $serverId, $siteId, $data); $forge->deleteHorizon($organizationSlug, $serverId, $siteId); $forge->getOctane($organizationSlug, $serverId, $siteId); $forge->createOctane($organizationSlug, $serverId, $siteId, $data); $forge->getReverb($organizationSlug, $serverId, $siteId); $forge->createReverb($organizationSlug, $serverId, $siteId, $data); $forge->getPulse($organizationSlug, $serverId, $siteId); $forge->createPulse($organizationSlug, $serverId, $siteId, $data); ``` ### Site Workers ```php theme={null} $workers = $forge->workers($organizationSlug, $serverId, $siteId); $worker = $forge->createWorker($organizationSlug, $serverId, $siteId, $data); $forge->createWorkerAction($organizationSlug, $serverId, $siteId, $workerId, [ 'action' => 'restart', ]); ``` ### Site Configuration ```php theme={null} // Environment file $forge->siteEnvironment($organizationSlug, $serverId, $siteId); $forge->updateSiteEnvironment($organizationSlug, $serverId, $siteId, $content); // Nginx configuration $forge->siteNginx($organizationSlug, $serverId, $siteId); $forge->updateSiteNginx($organizationSlug, $serverId, $siteId, $content); // PHP version $forge->sitePhp($organizationSlug, $serverId, $siteId); $forge->updateSitePhp($organizationSlug, $serverId, $siteId, ['version' => 'php84']); ``` ## Managing Databases ```php theme={null} $databases = $forge->databases($organizationSlug, $serverId); $database = $forge->database($organizationSlug, $serverId, $databaseId); $database = $forge->createDatabase($organizationSlug, $serverId, $data); $forge->deleteDatabase($organizationSlug, $serverId, $databaseId); // Database users $users = $forge->databaseUsers($organizationSlug, $serverId); $user = $forge->createDatabaseUser($organizationSlug, $serverId, $data); $forge->deleteDatabaseUser($organizationSlug, $serverId, $userId); ``` ## Background Processes Background processes were referred to as "daemons" in v3.x of the SDK. The `ManagesDaemons` trait has been renamed to `ManagesBackgroundProcesses` and every method has been renamed accordingly. ```php theme={null} $processes = $forge->backgroundProcesses($organizationSlug, $serverId); $process = $forge->createBackgroundProcess($organizationSlug, $serverId, $data); $forge->deleteBackgroundProcess($organizationSlug, $serverId, $processId); ``` ## Scheduled Jobs ```php theme={null} $jobs = $forge->scheduledJobs($organizationSlug, $serverId); $job = $forge->createScheduledJob($organizationSlug, $serverId, $data); $forge->deleteScheduledJob($organizationSlug, $serverId, $jobId); ``` ## PHP Version Management ```php theme={null} $versions = $forge->phpVersions($organizationSlug, $serverId); $forge->installPhpVersion($organizationSlug, $serverId, ['version' => 'php84']); $forge->phpFpmConfig($organizationSlug, $serverId, $phpVersion); $forge->updatePhpFpmConfig($organizationSlug, $serverId, $phpVersion, $content); ``` ## Teams, Roles, and Permissions ```php theme={null} // Teams $teams = $forge->teams($organizationSlug); $team = $forge->createTeam($organizationSlug, $data); $members = $forge->teamMembers($organizationSlug, $teamId); $invitations = $forge->teamInvitations($organizationSlug, $teamId); // Roles $roles = $forge->roles($organizationSlug); $role = $forge->createRole($organizationSlug, $data); // Permissions $permissions = $forge->permissions(); $predefinedRoles = $forge->predefinedRoles(); ``` ## Recipes ```php theme={null} // Organization recipes $recipes = $forge->recipes($organizationSlug); $recipe = $forge->createRecipe($organizationSlug, $data); $run = $forge->createRecipeRun($organizationSlug, $recipeId, $data); // Forge-provided recipes $forgeRecipes = $forge->forgeRecipes(); ``` ## Providers ```php theme={null} $providers = $forge->providers(); $provider = $forge->provider($providerId); $sizes = $forge->providerSizes($providerId); $regions = $forge->providerRegions($providerId); ``` ## Error Handling The SDK throws dedicated exception classes that you may catch to handle specific error states: * `Laravel\Forge\Exceptions\ValidationException` * `Laravel\Forge\Exceptions\NotFoundException` * `Laravel\Forge\Exceptions\ForbiddenException` * `Laravel\Forge\Exceptions\FailedActionException` * `Laravel\Forge\Exceptions\RateLimitExceededException` * `Laravel\Forge\Exceptions\TimeoutException` If you are looking for application performance monitoring for the Laravel applications you deploy with Forge, take a look at [Laravel Nightwatch](https://nightwatch.laravel.com). If you prefer fully managed Laravel hosting, consider [Laravel Cloud](https://cloud.laravel.com). # Server Providers Source: https://forge.laravel.com/docs/server-providers Learn about the server providers supported by Laravel Forge. ## Introduction All servers provisioned on Laravel Forge are powered by an underlying server provider. The fastest way to get started is by using Laravel VPS as your server provider, which are Laravel managed servers. After subscribing to a Forge plan, you can immediately start provisioning Laravel VPS servers with zero additional configuration. Forge also allows you to link external server providers such as AWS or Hetzner so that you may create servers on those platforms. Server providers are configured and managed within the [organization’s](/docs/organizations) settings. ## Supported providers Laravel Forge supports the following cloud server providers: * [Laravel VPS](/docs/servers/laravel-vps) * [DigitalOcean](https://www.digitalocean.com/) * [Akamai / Linode Cloud](https://www.linode.com/) * [Vultr](https://www.vultr.com/) * [Amazon AWS](https://aws.amazon.com/) (Non-Gov) * [Hetzner Cloud](https://www.hetzner.com/cloud) * [Bring your own server](#bring-your-own-server) If your preferred server provider is not supported by Laravel Forge, you may use Forge's "Custom VPS" option to create your server. Custom VPS servers receive all of the same functionality as first-party supported server providers. [Learn more](#bring-your-own-server) ## Managing server providers ### Connecting server providers To connect a server provider, navigate to the organization’s settings. Then, on the "Server providers" page, click "Add provider". Select the provider you wish to connect to and authenticate your chosen account. It is possible to link any number of supported server provider accounts, including multiple accounts for the same provider. ### DigitalOcean To connect your DigitalOcean account, navigate to the Server providers page under the organization’s settings. Then, click Add provider. Select DigitalOcean, click Add provider, then click Login with DigitalOcean. Authenticate your account by following instructions provided by DigitalOcean. Once approved, Laravel Forge will create an OAuth credential, allowing it to access the necessary permissions needed in provisioning and managing your servers on your behalf. ### AWS In order to provision servers on AWS, you need to create a new IAM role. To get started, navigate to the IAM service on your AWS dashboard. Once you are in the IAM dashboard, you may select "Roles" from the left-side navigation panel and click the "Create Role" button. The process for creating the role is outlined in these steps: 1. Choose "AWS account" as the trusted entity type, and select "Another AWS account". 2. Enter the "Laravel Forge AWS Account" from the Forge dashboard. 3. Under “Options”, enable the “Require external ID” checkbox, enter the “AWS External ID” shown in the Forge dashboard, and then click “Next”. 4. In the "Permissions policies" section, select the `AmazonEC2FullAccess` and `AmazonVPCFullAccess` policies. Then, click "Next". 5. In the "Name, review, and create" section, provide a name and description for the role. 6. Complete the process by creating the role. 7. Copy the role ARN displayed in the AWS dashboard and add it to your AWS credentials in Laravel Forge. There are a few requirements you should review to ensure Laravel Forge works correctly with your linked AWS account: * If you are using an existing VPC, the subnet must be configured to **auto-assign public IP addresses**. * If you are using an existing VPC, the default security group **must allow Laravel Forge to SSH into the server**. Here is an example: | Type | Protocol | Port Range | Source | | Description | | ----- | -------- | ---------- | ------ | -------------------- | ---------------------- | | HTTP | TCP | 80 | Custom | 0.0.0.0/0 | | | HTTP | TCP | 80 | Custom | ::/0 | | | SSH | TCP | 22 | Custom | YOUR\_IP\_ADDRESS/32 | SSH from your IP | | SSH | TCP | 22 | Custom | 159.203.150.232/32 | SSH from Laravel Forge | | SSH | TCP | 22 | Custom | 159.203.150.216/32 | SSH from Laravel Forge | | SSH | TCP | 22 | Custom | 45.55.124.124/32 | SSH from Laravel Forge | | SSH | TCP | 22 | Custom | 165.227.248.218/32 | SSH from Laravel Forge | | HTTPS | TCP | 443 | Custom | 0.0.0.0/0 | | | HTTPS | TCP | 443 | Custom | ::/0 | | #### AWS service limits AWS Service Limits can be increased through the following options: 1. Open the Service Quotas console. 2. In the navigation pane, choose AWS services. 3. Select a service. 4. Select a quota. 5. Follow the directions to request a quota increase. * Use the [request-service-quota-increase](https://docs.aws.amazon.com/cli/latest/reference/service-quotas/request-service-quota-increase.html) AWS CLI command. * If a service is not yet available in Service Quotas, use the AWS Support Center Console to create a [service quota increase case](https://support.console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase). * If the service is available in Service Quotas, AWS recommends that you use the [Service Quotas console](https://console.aws.amazon.com/servicequotas/home) instead of creating a support case. For additional information, refer to the following AWS documentation: * [Requesting a quota increase](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html) in the *Service Quotas User Guide*. * [AWS Service Quotas reference](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html). ### Akamai To connect your Akamai account, navigate to the Server providers page under the organization’s settings. Then, click Add provider. Select Akamai, click Add provider. Once you have provided a Profile name and API key, click Add provider. Laravel Forge will verify that it is able to access your account. When creating a [new Akamai Cloud API token](https://cloud.linode.com/profile/tokens) for your Akamai account, Akamai will ask you to select which permissions are needed by the token. You will need to select the following permissions: * **Linodes** - Read/Write * **IPs** - Read/Write In addition, you may wish to set the token to never expire. ### Vultr API access The Vultr server provider requires you to add the [Laravel Forge IP addresses](/docs/introduction#forge-ip-addresses) to an [IP address allow list](https://docs.vultr.com/platform/other/api/manage-api-access-control) so that Forge can communicate with your servers. You should ensure that you do this before provisioning a Vultr server via Forge. ### Hetzner Cloud API access Hetzner API tokens are specific to a Hetzner Project. If you utilize Hetzner Projects, you should ensure that Laravel Forge has an API token for each Hetzner Project. ## Bring your own server Alongside supporting several first-party server providers, Laravel Forge also supports the ability to use your own custom server. To do so, select the **Custom VPS** option when creating a new server. In addition, you should review the following server requirements: * The server **must be** running a fresh installation of Ubuntu 24.04 or 26.04 x64. * The server **must be** accessible externally over the Internet. * The server **must have** `root` SSH access enabled. * The server requirements **should meet** the following criteria or more: 1 CPU Core with 1GHz, 1GB RAM, and 10GB Disk space. * The server **must have** curl installed. * Ensure that no firewall or security group is throttling requests to the server. Throttling SSH requests may cause provisioning to fail at the final stage. * Some server providers may modify the contents of `/root/.ssh/authorized_keys`. If this applies to your provider, ensure they allow Laravel Forge's public key to access the server. * If you restrict SSH access by IP address, consult the [Laravel Forge IP address documentation](/docs/introduction#forge-ip-addresses). * If you are protecting your internal network through Network Address Translation (NAT ) and you are mapping public SSH ports to different internal SSH ports, you may let Laravel Forge know about this by checking the **This server is behind a NAT** checkbox. This will show an extra input field, **NAT SSH Port**, that you can use to tell Forge about the SSH port to which SSH traffic is mapped. Forge will use this port to allow traffic into the server via `ufw`. If the internal SSH port is the same as the public SSH port, you **may** leave the **NAT SSH Port** field empty. * If you are protecting your server with an antivirus software, make sure it doesn't interfere with Laravel Forge's operations. Antivirus programs may sometimes cause unexpected behavior during provisioning of the server that might result in misconfigurations of database instances or other applications on the server. Provisioning an existing server with existing configurations or applications may cause serious data loss. # Laravel VPS Source: https://forge.laravel.com/docs/servers/laravel-vps Learn about Laravel VPS and instant provisioning. ## Introduction Laravel VPS cuts server provisioning from minutes to seconds. One click gets you a fully configured server optimized for modern applications. All Laravel VPS servers are Ubuntu powered servers that you receive full access to, and are offered through our infrastructure partnership with DigitalOcean. But Laravel VPS offers more than just speed. It's one of the most affordable cloud provider options in Forge, making it easier to experiment with new projects or scale existing ones. You'll also get simplified billing through Forge instead of managing separate charges from multiple providers. ## Benefits of Laravel VPS Using Laravel VPS servers offers several benefits: * No need to link Forge to external server providers like AWS. * Provision servers in seconds. External server providers can take over 10 minutes. * Utilize Laravel VPS integrated terminal, and instantly gain SSH access to your Laravel VPS servers directly from Forge. * Consolidate billing on Laravel Forge, instead of managing billing via an external server provider and Forge. * You are only billed for the number of hours your Laravel VPS is provisioned. ## Forge Terminal When using Laravel VPS, you can gain SSH access to the server with a fully-functional terminal directly from Forge. To get started, navigate to any of your servers or sites and click the context menu for the server or site, usually on the right side of the page and represented by three dots. Then, click "Launch terminal". Alternatively, you may launch the terminal from any server or site page using the Control+\` keyboard shortcut. ## Migrating to Laravel VPS You can migrate your DigitalOcean servers to Laravel VPS by opening the dropdown menu next to the "Create Site" button in the server's "Overview" page. Then, click the "Migrate to Laravel VPS" item. During the migration, Forge will take a snapshot of your DigitalOcean droplet, transfer it to Laravel VPS, and use it to create the new server. Your server's status will change to "Migrating". After the migration is complete, the server's IP address will be changed and the server network will be reset. Before updating your DNS records to point to the new IP address, make sure you update the server's network settings by adding other Laravel VPS servers to the server network and updating your firewall rules. After updating the DNS records and verifying that everything works as expected, you may delete your DigitalOcean droplet from DigitalOcean's control panel. Only servers running Ubuntu 24.04 are eligible for migration to Laravel VPS; earlier Ubuntu versions are not supported. ## Private networking When configuring networking between Laravel VPS servers, you should use the server's public IP address. You can find your server's public IP address on the server's "Overview" page in the sidebar, under the "Networking" section. Use this IP address when configuring connections between Laravel VPS servers, such as connecting to a dedicated database server or cache server. ## Mail ports Mail ports (25, 465, 587) are blocked by default on Laravel VPS servers to prevent abuse. If you need to send email from your server, use an HTTP / API based service like [Resend](https://resend.com), or contact [Laravel Forge support](/docs/support) to request these ports be unblocked. ## Sudo password reset To reset the `forge` sudo password for your Laravel VPS server, navigate to your server's dashboard and click "Settings". Within the "Danger Zone" section, click the "Reset password" button in the "Reset sudo password" section. ## Pricing Usage is charged in increments of 1 hour blocks. For example, running a server for 5 minutes will be billed as 1 hour of usage. Free bandwidth is included when using Laravel VPS servers. This is subject to fair usage, and abuse will be blocked. For more information, see our [trust center](https://trust.laravel.com/?product=forge). # Load Balancing Source: https://forge.laravel.com/docs/servers/load-balancing Learn how to horizontally scale your application using load balancers. ## Introduction Load balancers are used to distribute web traffic amongst two or more servers and are often used for websites which receive high volumes of traffic. ## Creating load balanced sites Load balanced sites can only be created on [load balancer servers](/docs/servers/types#load-balancers). To create a new load balanced site, navigate to the server’s dashboard, and click New site. Next, provide the name of the site, the balancing method and add the servers you want to balance the traffic to. The selected servers must have a site with a matching domain, otherwise traffic will not be routed correctly. Forge domains (`on-forge.com`) are not available for load balancers. ## Load balancer methods Laravel Forge allows you to select one of three load balancer methods: 1. **Round-robin** - the default method, where requests are distributed evenly across all servers. 2. **Least connections** - requests are sent to the server with the least connections. 3. **IP hash** - the server to which a request is sent is determined by the client IP address. This means that requests from the same address are always handled by the same server unless it is unavailable. You may switch load balancers method at any time. You can learn more about how Nginx load balancers work by [consulting the Nginx documentation](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#method). ## Server configurations ### Server weights Each server balanced by the load balancer can be configured with different weights, indicating that some servers should serve more traffic than others. For example, if you have two servers in your load balancer, one with a weight of 5 and the other with 1, then the first server would be sent five out of every six requests made to the load balancer. ### Backup servers Individual servers can be marked as a **backup**. Backup servers will receive no traffic unless all other servers managed by the load balancer are not responding. ### Pausing traffic You may pause traffic to a specific server being managed by the balancer. While paused, the selected server will no longer serve incoming traffic. You may unpause the server at any time. ## SSL Typically, SSL certificates are installed on the individual application servers. However, when using load balancing, the certificate should be configured on the load balancer itself. You should consult the [SSL documentation](/docs/sites/domains#certificates) for more information on managing SSL certificates for your servers, including load balancers. When using SSL on a load balancer, you will likely need to configure the "trusted proxies" for your application. For Laravel applications, consult the [trusted proxies documentation](https://laravel.com/docs/requests#configuring-trusted-proxies). # Monitoring Source: https://forge.laravel.com/docs/servers/monitoring Learn how to configure server monitoring in Laravel Forge. ## Introduction Laravel Forge can be configured to monitor the following metrics on your server and email you when their state changes: * **CPU Load Average** - tracks the server's load average. This is based on the average system load over a one-minute interval. * **Used Disk Space** - tracks the amount of disk space that has been used on the primary drive. * **Used Memory** - tracks how much of the RAM is in active use. Server monitoring is only available on the Business plan. ## Managing server monitors ### Creating monitors To create a server monitor, navigate to the server's dashboard, click the "Observe" tab, and click the "Add monitor" button. Select the metric type, configure the thresholds and provide an email address to notify. Once done, click "Create server monitor". Laravel Forge will only accept one email address to notify. If you need to notify multiple people, you should create a distribution list such as `team@example.com`. ### Deleting monitors To delete a server monitor, navigate to the server's dashboard and click the "Observe" tab. Locate the server monitor you wish to delete, click the action dropdown next to the server monitor, and select "Delete". ## Stat collection frequencies The CPU Load and Used Memory metric data will be collected every minute. The Disk Space metric will be collected hourly. # Nginx Templates Source: https://forge.laravel.com/docs/servers/nginx-templates Learn how to use Nginx templates to customize your site configurations. ## Introduction Nginx templates allow you to customize the Nginx site configuration that Laravel Forge uses when creating your new site. Nginx templates that are not valid will prevent Nginx from properly working and your existing sites may stop responding. You should proceed with caution when creating and deploying custom Nginx templates. ## Managing templates ### Create template You may create your own Nginx templates from within a server's management dashboard. When creating a new template, you need to provide a template name and the template's content. Laravel Forge will provide a default template that you may alter as required. Although the default template does not show support for TLSv1.3, Laravel Forge will automatically update a site to support it if the server is able to do so. ### Edit templates You may edit the name and content of your Nginx template at any time. Changes to a template will not affect existing sites that use the template. ### Delete templates Deleting a template will not remove any sites which were configured to use it. ## Template variables Laravel Forge provides several variables that can be used within your templates to dynamically alter their content for new sites: | Variable | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `{{DIRECTORY}}` | The site's configured web directory, e.g., `/public` | | `{{DOMAINS}}` | The site's configured domains to respond to, e.g., `laravel.com alias.laravel.com` | | `{{PATH}}` | The site's web accessible directory, e.g., `/home/forge/laravel.com/public` | | `{{PORT}}` | The IPv4 port the site should listen to (`:80`). If the site name is `default`, this variable will also contain `default_server` | | `{{PORT_V6}}` | The IPV6 port to listen to (`[::]:80`). If the site name is `default`, this variable will also contain `default_server` | | `{{PROXY_PASS}}` | The PHP socket to listen on, e.g., `unix:/var/run/php/php8.0-fpm.sock` | | `{{ROOT_PATH}}` | The root of the configured site, e.g., `/home/forge/laravel.com` | | `{{SERVER_PUBLIC_IP}}` | The public IP address of the server | | `{{SERVER_PRIVATE_IP}}` | The private IP address of the server, if available | | `{{SITE}}` | The site's name, e.g., `laravel.com`. This differs from `{{DOMAINS}}` in that it does not include site aliases. | | `{{SITE_ID}}` | The site's ID, e.g., `12345` | | `{{USER}}` | The site's user, e.g., `forge` | When using these variables, you should ensure that they exactly match the syntax shown above. ## Team permissions The ability to manage Nginx Templates is determined by the `site:manage-nginx` permission. This permission is also used to restrict the ability to edit an existing site's Nginx configuration file. # PHP Source: https://forge.laravel.com/docs/servers/php Learn how to manage PHP versions on your Laravel Forge server. ## Introduction Laravel Forge makes it easy to install and configure multiple versions of PHP on your server. Each installed PHP version runs its own FPM process. In addition, you may [update the PHP version used by specific sites at any time](/docs/sites/the-basics#php-version). Laravel Forge is only aware of PHP installations that are managed through the Forge dashboard and not manually installed on the server. ## Managing PHP versions When provisioning a server, you must decide which version of PHP you want to install by default. The `php` binary on your server will point to the installed version selected at the time of its creation. Once the server has been created, Laravel Forge makes it easy to install additional versions alongside the default version. ### Installing PHP versions To install a PHP version, navigate to the server’s dashboard and click the PHP tab. Then, click the Install version button, select the version to install and decide whether you want it to become the CLI default. Click Install to begin the installation process. When you install a new version of PHP onto your server, Laravel Forge will create and configure the PHP-FPM process for that version. This means that your server will be running multiple versions of PHP at once. ### Uninstalling PHP versions To uninstall a PHP version, navigate to the server’s dashboard and click the PHP tab. Locate the version of PHP you want to remove, open the dropdown menu and click Uninstall PHP X.X and confirm the removal. PHP versions may be removed so long as: * There are other versions installed * The version you wish to uninstall is not the server's default version for new sites * The version you wish to uninstall is not the server's default version on the CLI * The version you wish to uninstall is not used by any sites ### PHP on the CLI When an additional version of PHP has been installed, you may reference it on the CLI via `phpx.x`, replacing the `x.x` with the version number (e.g., `php8.5`). The `php` binary will always point to the active CLI version (if changed from the default). ### Default PHP installation The "default" PHP version is the version of PHP that will be used by default when creating a new site on the server. When selecting a new version of PHP as your server's "default" version, the PHP versions used by existing sites **will not be updated**. ### Patching PHP versions To patch a PHP version, navigate to the server’s dashboard and click the PHP tab. Identify the version of PHP you want to patch, open the dropdown menu and click Update. Typically, patch updates should not cause any breaking changes to your server, although a few seconds of downtime is possible. We recommend that you exercise caution when patching PHP. ## Common PHP configuration settings Changing the following settings will apply the changes to all versions of PHP installed on the server. ### Max file upload size You may configure the maximum file upload size through the PHP tab of the server management dashboard. This value should be provided in megabytes. For reference, `1024MB` is `1GB`. ### Max execution time You may configure the maximum execution time through the PHP tab of the server management dashboard. This value should be provided in seconds. Forge applies this value across your server by updating the following configurations: * `max_execution_time` in `php.ini`. * `request_terminate_timeout` in the PHP-FPM `www.conf` (for each installed PHP version). * `fastcgi_read_timeout` in your Nginx configuration. ### OPcache Optimizing the PHP OPcache for production will configure OPcache to store your compiled PHP code in memory to greatly improve performance. If you choose to optimize OPcache for production, you should verify that your deployment script [reloads the PHP-FPM service](/docs/knowledge-base/servers#restarting-php-fpm) at the end of each deployment unless you're using zero-downtime deployments. OPcache is enabled by default for all newly created servers. ### Editing PHP and FPM configuration settings You can customize the `php.ini` and FPM settings for individual PHP versions. To edit these settings, navigate to the server's dashboard and click the "PHP" tab. Locate the version of PHP you want to configure, open the dropdown menu next to that version, and select either: * **Edit PHP-FPM configuration** - Modify the PHP FPM (web) configuration for this specific PHP version * **Edit PHP CLI configuration** - Modify the PHP CLI (command-line interface) configuration for this specific PHP version These settings apply only to the individual version of PHP selected and will not affect other PHP versions installed on your server. ## Beta and release candidates PHP "beta" and "release candidate" releases are often available on Laravel Forge weeks before their final release. This allows you to experiment with upcoming major PHP versions on sites that are not in production. However, some Forge features, PHP features, and PHP extensions may not work as expected during that period. Once that PHP version becomes stable, you will need to fully uninstall and re-install the PHP version. # Real-Time Metrics Source: https://forge.laravel.com/docs/servers/real-time-metrics Learn how to view real-time server metrics in Laravel Forge. ## Introduction Laravel Forge provides real-time metrics for servers provisioned through supported providers. These interactive charts allow you to monitor your server's performance and resource utilization over various time periods, helping you identify trends and respond to issues quickly. Real-time metrics are only available for Laravel VPS, Hetzner, and DigitalOcean server providers. ## Available metrics The following real-time metrics are available for your servers: * **CPU** - displays the percentage of CPU resources being utilized by your server over time. * **Memory** - displays the percentage of RAM being used by your server. * **Disk Usage** - displays the percentage of storage space being consumed on your server's primary drive. * **Inbound Bandwidth** - displays the network traffic coming into your server, measured in Mbps. * **Outbound Bandwidth** - displays the network traffic leaving your server, measured in Mbps. ## Viewing metrics To view real-time metrics for your server, navigate to the server's "Observe" tab, and then click "Metrics". The metrics dashboard will display interactive charts for each available metric. ### Time scopes You can adjust the time range displayed in the charts to view metrics over different periods: * **1 hour** - view metrics for the last hour, ideal for monitoring immediate performance changes. * **6 hours** - review metrics over the last six hours to identify short-term trends. * **24 hours** - analyze a full day of metrics to understand daily usage patterns. * **7 days** - examine a week's worth of data to spot longer-term trends or recurring issues. * **1 month** - review a month of metrics for capacity planning and historical analysis. These time scopes allow you to quickly identify performance issues, correlate events across different metrics, and make informed decisions about server scaling and optimization. # Root Access / Security Source: https://forge.laravel.com/docs/servers/security Learn about the security measures Laravel Forge takes to protect your server. ## Overview During the initial provisioning of your server, Laravel Forge connects as the `root` user over SSH. This is so that Laravel Forge is able to add repositories, install dependencies and configure new services, firewalls, and more. The provisioning process can take anywhere from a few seconds to 10 minutes when using an external server provider, but will depend on a variety of factors including the speed of your server, the speed of your network connection, and the number of services that need to be installed. ### Post-provisioning After initially provisioning your server, Laravel Forge continues to use root access so that it can manage your server's software, services, and configuration. For example, root access is needed to manage: * Background processes * Firewalls * PHP configuration and management * Scheduled tasks * Website isolation * Other operating system dependencies ## Security We take security very seriously and ensure that we do everything we can to protect customer's data. Below is a brief overview of some of the steps we take to ensure your server's security: * Laravel Forge issues a unique SSH key for each server that it connects to * Password based server SSH connections are disabled during provisioning * Each server is issued a unique root password * All ports are blocked by default with UFW, a secure firewall for Ubuntu. We then explicitly open ports: `22` (SSH), `80` (HTTP) and `443` (HTTPS) * Automated security updates are installed using Ubuntu's automated security release program ### Automated security updates Security updates are automatically applied to your server on a weekly basis. Laravel Forge accomplishes this by enabling and configuring Ubuntu's automated security update service that is built in to the operating system. Laravel Forge does not automatically update w software such as PHP or MySQL, as doing so could cause your server to suffer downtime if your application's code is not compatible with the upgrade. However, it is possible to [install new versions](/docs/servers/php#multiple-php-versions) and [patch existing versions of PHP](/docs/servers/php#updating-php-between-patch-releases) manually via the Laravel Forge dashboard. # Creating and Managing Servers Source: https://forge.laravel.com/docs/servers/the-basics Learn how to create and manage your servers in Laravel Forge. ## Introduction Laravel Forge can provision new servers for you in seconds, allowing you to quickly deploy web applications built in PHP or other stacks. We also offer you the ability to provision multiple server types (e.g., web servers, database servers, load balancers) with the option of having a variety of services configured for you to hit the ground running. ## Creating servers To create a new server, navigate to your organization's overview or "Servers" tab and click "New server". Provide a name for your server and choose the provider to create the server with, then click "Continue". Next, you need to configure the [type of server](/docs/servers/types) you want to create, which region to create the server in, and the size of the server. When creating a custom VPS, you must provide additional information including the server's IP address and the SSH port to connect to. ### Laravel VPS There are a couple of important differences when creating a Laravel VPS server: 1. Only servers created in the "Laravel managed" private network are available for instant provisioning. Private networks can be created, but may take longer to provision. 2. Only servers in the Small, Medium, Large, and X Large sizes are available for instant provisioning. Other sizes can be selected, but may take longer to provision. ## Server settings The server's Settings tab can be used to update important details of a server, including its name, SSH connection details, timezone, and tags. ### IP addresses If your server's IP address changes, you should inform Laravel Forge so that it can remain connected and continue to manage your server. To update the IP address of a server, navigate to the Settings tab and update the IP Address field under the Server Settings section. When rebooting an AWS server, AWS will allocate a new IP address to the server. Therefore, you will need to update the IP address after a server reboot. ### Resizing Laravel VPS servers Laravel VPS servers can be resized to a different specification. To resize a Laravel VPS server, navigate to your server's settings page. Then, select a new server size from the "Size" dropdown. Click "Save" to save the new settings. When resizing a server, you will be prompted to confirm the action. Once confirmed, the server will be resized, which may take a few minutes to complete. You cannot downsize Laravel VPS servers to a smaller specification. You can only resize to a larger server size. When resizing a Laravel VPS server, the server will be temporarily unavailable during the resize process. ### Timezone By default, all Laravel Forge servers are provisioned and configured to use the UTC timezone. If you need to change the timezone used by the server, you can do so by selecting one of the timezones from the list. Forge uses the `timedatectl` command to modify the system's timezone. ## Managing servers ### Archiving servers Archiving a server will remove Laravel Forge's access to the server while retaining all sites, configurations, and resources. You will still be charged for the server by your provider. To archive a server, navigate to the server's overview and click the Settings tab. Locate the Danger zone and click Archive server. Enter the name of the server and click confirm. Archiving a server will not delete your server from the server provider and will not cause any data loss on your server. Laravel VPS servers cannot be archived. ### Unarchiving servers To archive a server, navigate to the server's overview. Click the Unarchive button to generate the unique reconnection script. Once you have executed the script on your server, click Unarchive. ### Transferring servers Servers may be transferred between organizations that you are part of. The receiving organization must also have a [server provider](/docs/server-providers) configured for the server you are transferring. You must have the `server:transfer` permission in both organizations to transfer a server. Laravel VPS servers cannot currently be transferred between organizations. To transfer a server, navigate to the server's overview and click the Settings tab. Locate the Danger zone and click Transfer server. Confirm the organization you wish to transfer the server to. Server transfers are immediate. You may only transfer servers to a Laravel Forge organization with an active subscription that have not reached their server quota. Laravel Forge will not transfer a server on a server-provider level. You must do this manually. ### Deleting servers To delete a server, navigate to the server and click the Settings tab. Locate the Danger zone and click Delete server. Enter the name of the server and click confirm. By default, deleting a server will permanently destroy the server from the connected provider, resulting in data loss that cannot be undone by the Laravel Forge team. #### Preserving servers at the provider When deleting a server, you can choose to preserve the server at your server provider by enabling the "Preserve this server at \[provider]" option in the deletion confirmation dialog. When this option is enabled, the server will only be removed from Laravel Forge and will not be deleted from your server provider's infrastructure. This is useful in scenarios where: * You no longer have access to the server provider credentials * You want to remove the server from Forge management but keep it running * You're transferring server management to another tool or team This option is not available for custom servers or Laravel VPS servers. Custom servers are not managed by Forge at the provider level, and Laravel VPS servers are always deleted from the underlying infrastructure when removed from Forge. # Server Types Source: https://forge.laravel.com/docs/servers/types Learn about the different types of servers you can provision with Laravel Forge. ## Introduction Laravel Forge supports provisioning several different types of servers: * Application Servers * Web Servers * Worker Servers * Load Balancers * Database Servers * Cache Servers Below, we will discuss each of these server types in more detail. ## Server Types For reference, here is a breakdown of what is offered by each server type:
Type Nginx PHP MySQL / Postgres / MariaDB Redis, Memcached Node.js Meilisearch
App Server ✅ ✅ ✅ ✅ ✅
Web Server ✅ ✅ ✅
Database Server ✅
Cache Server ✅
Worker Server ✅
MeiliSearch Server ✅
Load Balancer ✅
### App Servers Application servers are designed to include everything you need to deploy a typical Laravel / PHP application within a single server. Therefore, they are provisioned with the following software: * PHP * Nginx * MySQL / Postgres / MariaDB (if selected) * Redis * Memcached * Node.js * Supervisor Application servers are the most typical type of server provisioned on Laravel Forge. If you're unsure which server type you need, most likely you should provision an application server. As you need to scale your application, you may look at provisioning dedicated servers for services such as your database or caching, but starting with an App server is recommended. ### Web Servers Web servers contain the web server software you need to deploy a typical Laravel / PHP application, but they do not contain a database or cache. Therefore, these servers are meant to be [networked to](./../resources/network) other dedicated database and cache servers. Web servers are provisioned with the following software: * PHP * Nginx * Node.js * Supervisor ### Database Servers Database servers are intended to function as dedicated MySQL / Postgres / MariaDB servers for your application. These servers are meant to be accessed by a dedicated application or web server via Laravel Forge's [network management features](./../resources/network). Database servers are provisioned with the following software, based on your selections during the server's creation: * MySQL, MariaDB, or PostgreSQL Laravel VPS does not support installing MariaDB. ### Cache Servers Cache servers are intended to function as dedicated Redis / Memcached servers for your application. These servers are meant to be accessed by a dedicated application or web server via Laravel Forge's [network management features](./../resources/network). Cache servers are provisioned with the following software: * Redis * Memcached ### Worker Servers Worker servers are intended to function as dedicated PHP queue workers for your application. These servers are intended to be networked to your web servers, do not include Nginx, and are not accessible via HTTP. Worker servers are provisioned with the following software: * PHP * Supervisor ### Meilisearch Servers Meilisearch servers install [Meilisearch](https://meilisearch.com) to provide a blazingly fast search service to your application. They are intended to be connected to another server, and communicate via a [private network](./../resources/network#server-network). A Meilisearch server will only display and manage one [Site](/docs/sites/the-basics). You cannot create or delete other sites on this server. When connecting to the Meilisearch server from a web or application server, you should connect to it via its private IP address. ### Load Balancers Load balancers are meant to distribute incoming web traffic across your servers. To do so, load balancers use Nginx as a "reverse proxy" to evenly distribute the incoming traffic. Therefore, load balancers are only provisioned with Nginx. Once provisioned you may [configure your load balancer](/docs/servers/load-balancing) to meet your needs. ### OpenClaw Servers OpenClaw servers provide a minimal environment for running [OpenClaw](https://openclaw.ai) AI agents. These servers only install Homebrew and OpenClaw, and after provisioning, you are dropped straight into the shell to begin configuration. OpenClaw servers are only available on [Laravel VPS](/docs/servers/laravel-vps). For more information on configuring and managing OpenClaw servers, see the [OpenClaw integration](/docs/integrations/openclaw) documentation. # Commands Source: https://forge.laravel.com/docs/sites/commands Learn how to run arbitrary commands from the Commands panel. ## Introduction You may execute arbitrary Bash commands from the "Commands" panel. Commands are executed from within the site's root directory, e.g., `/home/forge/site.com`. If you need to run commands within another directory you may prefix the command with a `cd` operation: ```bash theme={null} cd bin && ./run-command.sh ``` ## Running commands Commands can be executed from the site's "Commands" panel. Sites that were created with the "General PHP / Laravel" project type will automatically suggest common Laravel Artisan commands. Commands are not executed within a TTY, which means that input / passwords cannot be provided. Additionally, commands cannot exceed 5 minutes of execution time. ### Command history * The user who initiated the command. This is particularly helpful when using Laravel Forge within [teams](/docs/teams) * The command that was executed * The date and time of execution * The status of the command ## Commands vs. recipes While [recipes](/docs/recipes) also allow you to run arbitrary Bash scripts on your servers, commands on a site differ in a few, but important ways: * Recipes run at a server level. In other words, they cannot dynamically change into a site's directory unless you already know the directory ahead of time * Recipes can run using the `root` user. Commands only run as the site's user, which in most cases will be `forge` unless the site is "isolated" * Recipes are better equipped for running larger Bash scripts. Commands focus on running short commands, such as `php artisan config:cache` * Recipes use the server's configured PHP CLI version. Commands use the PHP version configured for the site they are run on. # Deployments Source: https://forge.laravel.com/docs/sites/deployments Manage code deployments with scripts, queues, and CI tools ## Introduction Laravel Forge makes it easy to deploy your applications on demand, whether that be manually, automatically when pushing new code to your source control provider, or via a webhook from your CI platform of choice. You can see a list of your site's deployments by navigating to the "Deployments" tab within your site's management dashboard. Laravel Forge provides a paginated list of your site's deployments, including what was deployed, when it was deployed, how long it took to be deployed, and also the output of your deploy script. Deployments are limited to 10 minutes. If a deployment takes longer, it will fail automatically. If your site is integrated with [Envoyer](/docs/integrations/envoyer), Envoyer's deployment limits apply instead. ## Deployment strategies Laravel Forge supports two deployment strategies, letting you choose the one that best fits your workflow. ### Zero-downtime deployments Zero-downtime deployments use a strategy where your new code is cloned into a special `releases` directory, and then a symbolic link is used to "activate" the new code once deployment is completed. This strategy greatly reduces the risk of your site going down during deployments, as the new code is only activated once all deployment steps have completed successfully. If any step in the deployment process fails, your site will continue to use the previous release. Nuxt.js and Next.js sites always use zero-downtime deployments. This behavior is not configurable and cannot be disabled, since it ensures that JavaScript-based, server-rendered applications are deployed safely without interrupting active requests or causing visible downtime during builds and restarts. Zero-downtime deployments are exclusively available for new sites and must be configured at the time of creation — they cannot be added to existing sites later. Laravel Forge automatically enables zero-downtime deployments for all new sites by default. If you prefer not to use this feature, you can disable it by toggling the "Zero-downtime deployments" option in the "Advanced settings" modal during site creation. #### Release creation and activation If you create a new site with zero-downtime deployments enabled, Laravel Forge will configure your site's deployment script to include three special "macros": * `$CREATE_RELEASE()` – creates the new release directory and clones your site's code into it. * `$ACTIVATE_RELEASE()` – activates the new release by creating a symbolic link from the `current` directory to the new release directory. * `$RESTART_QUEUES()` - restarts any Laravel queues that are running for the site. Additionally, if your site is using Horizon, it will also restart the Horizon process. It's important that these commands are included in your deployment script as they are responsible for handling zero-downtime deployments. Failure to include these commands will result in your site not being deployed correctly. #### Running tasks during deployments Forge adds the `cd $FORGE_RELEASE_DIRECTORY` command after the `$CREATE_RELEASE()` macro in the deployment script to make sure all commands located after this code block will be executed in the context of the new release directory. This means that if you need to run any tasks that depend on your new code, you should place those commands after the `cd $FORGE_RELEASE_DIRECTORY` command. If you need to run any tasks after a new release has been activated, you should place those commands after the `$ACTIVATE_RELEASE()` macro. For zero-downtime deployments, it is unnecessary to reload the PHP-FPM service because every deployment is deployed to a new, uncached directory. #### Configuring deployment retention By default, Laravel Forge retains the last 4 deployments when using zero-downtime deployments. This allows you to quickly rollback to a previous release if needed. You can change the number of deployments to retain by navigating to your site's **Settings** tab and clicking **Deployments**. From there, you can adjust the number of deployments that Forge will keep on your server. #### Shared paths When using zero-downtime deployments, shared paths allow you to specify files or directories that should remain consistent across all releases. These paths are automatically symlinked from a shared storage location into each new release directory, ensuring that important data persists between deployments. Common use cases for shared paths include: * **Storage directories** – User uploads, generated files, and other application storage * **Cache directories** – Application caches that should persist between releases * **Log files** – Application logs that should be preserved across deployments * **Environment files** – The `.env` file (automatically shared by default) * **SQLite databases** – SQLite databases that should persist between releases For example, if you want to share the `storage` directory, you would add `storage` as a shared path. During each deployment, Laravel Forge will create a symbolic link from `/home/forge/example.com/current/storage` to the shared storage directory at `/home/forge/example.com/storage`. If your application uses an SQLite database, you should add a shared path from `database.sqlite` to `database/database.sqlite`. This ensures that your database persists between deployments, as Forge will symlink `/home/forge/example.com/current/database/database.sqlite` to `/home/forge/example.com/database.sqlite`. By default, Laravel Forge automatically configures the `.env` file as a shared path for all sites using zero-downtime deployments. #### Laravel Octane You should not use zero-downtime deployments when using Laravel Octane, as Octane already handles graceful, zero-downtime restarts internally. Enabling Forge’s zero-downtime feature alongside Octane will interfere with this process and cause deployments to behave incorrectly. ### Standard deployments The standard deployment strategy uses a simpler approach where your site's code is kept in a single directory and updated in place during deployment. This strategy *can* be faster than zero-downtime deployments, but it does come with the risk of your site going down if a deployment step fails midway through the deployment process. ## Push to deploy Laravel Forge's "Push to deploy" feature allows you to easily deploy your projects when you push new code to your source control provider. When code is pushed to your site's configured branch, Laravel Forge will automatically trigger a new deployment and run your site's deployment script. Push to deploy is **enabled by default for new sites** created with GitHub, GitLab, or Bitbucket. If you wish to disable this feature, you may do so by toggling the "Push to deploy" toggle inside of the ["Advanced settings" modal](/docs/sites/the-basics#advanced-settings). To enable push to deploy for existing sites, you may do so by enabling the "Push to deploy" toggle on the "Deployments" tab of your site's settings. For sites using a [custom source control provider](/docs/source-control#using-custom-git-providers) you will need to manually set up a ["Deployment hook"](/docs/sites/deployments#deploying-from-ci) to have your code deployed when you push to your source provider. ## Deploy script When a deployment is triggered, Laravel Forge will execute the commands defined in your site's deploy script. At a minimum, your deploy script should contain the commands needed to update your site's codebase (such as a `git pull` or `$CREATE_RELEASE()` macro), install any dependencies (such as `composer install` or `npm ci`), and perform any other tasks needed to get your application up and running (such as `php artisan migrate --force`). ### Environment variables Laravel Forge will automatically inject a number of environment variables into your deployment script at runtime. These variables are configured to provide information about the deployment itself, the site, and the server. | Key | Description | | ------------------------- | ------------------------------------------------------------------------------ | | `FORGE_COMPOSER` | The path to the Composer installation. | | `FORGE_CUSTOM_DEPLOY` | Whether the deployment was triggered with a custom deployment trigger request. | | `FORGE_DEPLOY_AUTHOR` | The author of the commit. | | `FORGE_DEPLOY_COMMIT` | The Git hash of the commit being deployed, used for display purposes. | | `FORGE_DEPLOY_MESSAGE` | The Git commit message. | | `FORGE_DEPLOYMENT_ID` | The Laravel Forge assigned ID of this deployment. | | `FORGE_MANUAL_DEPLOY` | Whether the deploy was triggered by clicking "Deploy Now". | | `FORGE_PHP_FPM` | The PHP-FPM process name that is being used by Laravel Forge. | | `FORGE_PHP` | The `php` binary that is being used by the Laravel Forge site or server. | | `FORGE_QUICK_DEPLOY` | Whether the deploy was triggered by a source control provider webhook. | | `FORGE_REDEPLOY` | Whether this is a re-deployed commit. | | `FORGE_RELEASE_DIRECTORY` | The path of the current release when zero-downtime deployment is enabled. | | `FORGE_SERVER_ID` | The ID of the Laravel Forge server that is being deployed to. | | `FORGE_SITE_BRANCH` | The name of the branch that is being deployed. | | `FORGE_SITE_ID` | The ID of the Laravel Forge site that is being deployed to. | | `FORGE_SITE_PATH` | The root of the deployment path, e.g., `/home/forge/mysite.com/current` | | `FORGE_SITE_ROOT` | The site's root directory, e.g., `/home/forge/mysite.com` | | `FORGE_SITE_USER` | The name of the user deploying the site. | You may use these variables as you would any other Bash variable: ```bash theme={null} if [[ $FORGE_MANUAL_DEPLOY -eq 1 ]]; then echo "This deploy was triggered manually." fi ``` For example, you may wish to prevent deployments if the commit message contains "wip": ```bash theme={null} if [[ $FORGE_DEPLOY_MESSAGE =~ "wip" ]]; then echo "WORK IN PROGRESS, DO NOT CONTINUE." exit 1 fi ``` Laravel Forge prefixes injected variables with `FORGE_`. We do not recommend using this "namespace" when defining your own variables to avoid potential conflicts. #### Making .env variables available Laravel Forge makes it easy to include your site's `.env` variables in your deploy script. You may enable this feature by navigating to the "Deployments" tab of your site's settings and checking the "Make .env variables available to deployment script" checkbox. When enabled, Laravel Forge will automatically inject the variables in your site's `.env` file into the deploy script, allowing them to be accessed like any normal Bash variable: ```bash theme={null} echo "${APP_NAME} is deploying..." ``` ### PHP versions Sites use the `$FORGE_PHP` environment variable when invoking PHP commands in the deployment script. This variable will always point to the configured PHP version for the site. If you need to use a specific version of PHP, you must use the `phpx.x` command where `x.x` reflects on the version required (e.g., `php8.5`). During a deployment, Forge also configures the `php` binary to be the PHP version configured on your site. This ensures that `composer` and `npm` scripts which invoke PHP will use the site’s PHP version. ### Restarting background processes When deploying applications that use [background processes](/docs/resources/background-processes) such as daemons, you may need to restart the process to ensure it picks up your code changes. You can do this by adding the restart command to your deployment script: ```bash theme={null} # Restart your daemon (replace 12345 with your daemon's ID)... sudo supervisorctl restart daemon-12345:* ``` If your site is using zero-downtime deployments, you should place the restart command after the `$ACTIVATE_RELEASE()` macro to ensure the new code is activated before the process is restarted. ## Deploying from CI If you wish to trigger deployments from CI, or from a source control provider that is not currently supported by Laravel Forge, you may do so by using "deployment hooks" or the [Forge CLI](/docs/cli). ### Deployment hooks Deployment hooks are special webhooks that Laravel Forge provides for each site. You may trigger a deployment by making a `GET` or `POST` request to the deployment trigger URI provided. To find your site's deployment hook URI, navigate to the "Deployments" tab of your site's settings. You will find a "Deploy hook" section with the URI that you can quickly copy to your clipboard. #### Refreshing the deployment token Each deploy hook contains a unique token that is used to authenticate the request. If you wish to regenerate this token, you may do so by clicking the "Refresh" icon button next to the deploy hook URI. Refreshing the deployment token will immediately invalidate the previous token. Any services that are using the previous token will need to be updated to use the new token. #### Using query parameters You may pass additional data when triggering a deployment using query parameters. Laravel Forge will detect the following "reserved" query parameters and use them to populate specific information about the deployment: | Parameter | Environment variable | Description | | ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `forge_deploy_branch` | – | The branch that contains the commit. The deployment is only triggered if the branch matches the site's configured deployment branch. | | `forge_deploy_commit` | `FORGE_DEPLOY_COMMIT` | The commit hash label displayed in the deployment history. This does not affect which commit is deployed. | | `forge_deploy_author` | `FORGE_DEPLOY_AUTHOR` | The author of the commit. | | `forge_deploy_message` | `FORGE_DEPLOY_MESSAGE` | The commit message. | In addition to the reserved parameters, you may also pass custom parameters that will be injected into your deployment script. For example, if you pass the query parameter `&env=staging` to the deployment hook URL, Laravel Forge will inject a `FORGE_VAR_ENV` variable into your deployment script that will evaluate to `"staging"`. ### Forge CLI If you need to have access to the deployment output or execute additional deployment actions such as restarting services, you should use the [Forge CLI](/docs/cli). Once you have installed and configured the Forge CLI on your CI platform, you may execute the `forge deploy` command. To authenticate with Laravel Forge from your CI platform, you will need to add a `FORGE_API_TOKEN` environment variable to your CI build environment. You may generate an API token from your Laravel Forge [API settings dashboard](https://forge.laravel.com/profile/api). Your CI platform will also require SSH access to your server. #### GitHub Actions example If your site uses [GitHub Actions](https://github.com/features/actions) as its CI platform, the following guidelines will assist you in configuring Laravel Forge deployments so that your application is automatically deployed when someone pushes a commit to the `main` branch: 1. First, add the `FORGE_API_TOKEN` environment variable to your "GitHub > Project Settings > Secrets" settings so that GitHub can authenticate with Laravel Forge while running actions. 2. Next, add the `SSH_PRIVATE_KEY` environment variable to your "GitHub > Project Settings > Secrets" settings so that GitHub can have SSH Access to your site's server. 3. Then, create a `deploy.yml` file within the `your-project/.github/workflows` directory. The file should have the following contents: ```yml .github/workflows/deploy.yml theme={null} name: Deploy on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup SSH uses: webfactory/ssh-agent@v0.7.0 with: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: 8.5 tools: composer:v2 coverage: none - name: Require Laravel Forge CLI run: composer global require laravel/forge-cli - name: Deploy Site run: | forge server:switch your-server-name forge deploy your-site-name.com env: FORGE_API_TOKEN: ${{ secrets.FORGE_API_TOKEN }} ``` 4. Finally, you can edit the `deploy.yml` file to fit your site's deployment needs, as it may require a different PHP version or a library like `npm`. Once you are done, commit and push the `deploy.yml` file to the `main` branch so GitHub Actions can run the first deployment job. ## Deployment branch It is possible to change which branch is deployed on the "General" tab of your site's settings. If your site uses the zero-downtime deployment strategy, Laravel Forge will automatically use the newly configured branch on the next deployment. For standard deployments, ensure that your deployment script uses the `$FORGE_SITE_BRANCH` environment variable when pulling new code, or update any manual references to the branch in your deployment script. ## Deployment health checks After enabling deployment health checks, Forge will ping your application from several regions around the world to make sure the application is still accessible and returns a successful HTTP status code. If the site is not accessible after a deployment, Forge will notify you. To enable health checks, navigate to your site's "Settings" tab, then click "Deployments". Then, enable the "Health check" toggle. After enabling health checks, you can optionally configure the URL that Forge will ping after each deployment. ### Health check service IP addresses Health check requests are made from the following IP addresses, which should be added to your HTTP and HTTPS firewall allow rules. These IPs will **not make** SSH connections to the server. * 209.38.170.132 * 206.189.255.228 * 139.59.222.70 Alternatively, you can allow the health check service by its `User-Agent` header value: `Laravel-Healthcheck/1.0`. ## Deployment notifications You can enable deployment notifications for your site from the site management dashboard's "Notifications" tab. Laravel Forge supports several notification channels: * Email * Slack * Telegram * Discord By default, Laravel Forge will automatically notify you by email for failed deployments. ### Slack To enable Slack notifications, first enter the Channel name that you wish to send messages to, and then click "Enable Slack Notifications". You will be redirected to the Slack application authorization page, where you need to click "Allow". If you wish to modify the channel that Laravel Forge messages, you should first disable Slack notifications and then re-enable them for your site. ### Telegram To enable Telegram notifications, open Telegram and create or select a group chat that you want Laravel Forge to send deployment notifications to. Next, you should add the Laravel Forge bot to the chat by searching for the user `laravel_forge_telegram_bot`. Finally, copy the `/start` command, provided by Forge under the Telegram Deployment Notifications section, and paste it into the chat. If you wish to change the group that Laravel Forge messages, you should disable Telegram notifications and then follow the above steps again to reactivate notifications. ### Discord To enable Discord notifications, you first need to create a new "Incoming Webhook" integration on your Discord server. Once Discord has generated a webhook, you need to copy the URL into the "Webhook URL" field, then click "Enable Discord Notifications". Laravel Forge will now notify the configured channel for both successful and failed deployments. If you wish to change the webhook URL, you first need to disable Discord notifications and then re-enable the notifications. ### Webhooks Laravel Forge can also send an HTTP POST request to arbitrary URLs after each deployment. The payload of the request will contain the server ID, site ID, deployment status, and the relevant commit information: ```json theme={null} { "status": "success", "server": { "id": 123, "name": "my-awesome-server" }, "site": { "id": 456, "name": "my-awesome-site.dev" }, "commit_hash": "382b0f5185773fa0f67a8ed8056c7759", "commit_url": "https://github.com/johndoe/my-awesome-site/commit/382b0f5185773fa0f67a8ed8056c7759", "commit_author": "John Doe", "commit_message": "deploying!" } ``` # Domains Source: https://forge.laravel.com/docs/sites/domains Configure and manage domains and SSL certificates for your sites. ## Introduction Domains let you manage how your site is reached on the web. All Forge sites are assigned a free `on-forge.com` domain for development. But, you can also configure your own custom domains for your sites. ## Forge domains Forge provides every site with a free `on-forge.com` domain. These vanity domains are automatically available as soon as a site is created and and receive free HTTPS encryption. We do not recommend using `on-forge.com` domains in production. They're best for quick previews, staging environments, or testing with zero DNS configuration. Forge domains are not available for load balancers. ## Custom domains You can attach your own domain names to site in Forge, such as `example.com` or `app.example.com`. Each custom domain is managed separately, allowing you to create domain-specific certificates, configure `www.` redirect behavior, and choose one domain to serve as the primary domain. Custom domains have their own Nginx configuration files and SSL certificates, so adding or removing a domain does not impact other domains on the same site. ### `www.` redirect types When adding a custom domain to a site, you can decide how Forge should handle the `www.` version of that domain. Options include: * Redirect from `www.` – traffic to `www.example.com` will permanently redirect to `example.com` (recommended). * Redirect to `www.` – traffic to `example.com` will permanently redirect to `www.example.com`. * No redirects – traffic will only be handled for the exact domain configured. ### Wildcard subdomains Forge also supports wildcard domains such as `*.example.com`, which cover all subdomains of a given domain (e.g., `api.example.com`, `blog.example.com`). Wildcards are useful when you need dynamic or catch-all subdomains without adding each one individually. Allowing wildcard subdomains will still serve traffic for the apex domain (e.g., `*.example.com` will still serve traffic for `example.com`). ### Primary domains Each site can designate one domain as the **primary domain**. Changing the primary domain does not impact your additional custom domains, it is used as the "name" of the site so that it's easily recognizable inside of Forge and on your server. Changing the primary domain updates the site's directory name on the server. This may affect third-party integrations and custom scripts that reference the site directory. Be sure to use Forge's pre-configured `$FORGE_SITE_PATH` and `$FORGE_RELEASE_DIRECTORY` variables inside of deploy scripts to mitigate these problems. ### Protecting against unconfigured domains When provisioning your server, Laravel Forge will automatically create a "catch-all" Nginx configuration for your server at `/etc/nginx/sites-available/000-catch-all`. This is a special configuration file that is used to stop domains that are not configured on your server from being served. It will respond with a special `444` status code for any request that does not match an already configured domain. ## Certificates Forge manages SSL/TLS certificates on a per-domain basis, allowing you to secure each domain individually without impacting existing domains. Certificates are required to serve traffic over HTTPS and are automatically renewed where possible. You can choose between free, automated certificates from Let's Encrypt or provide your own custom certificate. When an SSL certificate is installed on a domain, Forge automatically configures your server to redirect all HTTP traffic to HTTPS, ensuring your site is always accessed securely. ### Let's Encrypt [Let's Encrypt](https://letsencrypt.org) provides free SSL certificates that are recognized across all major browsers. Certificates will be configured to cover the `www.` subdomain and wildcard subdomains (if applicable) and will **automatically** renew within 21 days or less before expiration. Renewal will take place at a random day and time to avoid overwhelming the Let's Encrypt servers. If something goes wrong while renewing a certificate, Forge will notify the server owner via email. You must have an **active Forge subscription** in order for your Let's Encrypt certificates to automatically renew. #### DNS-01 verification The DNS-01 verification method validates domain ownership by creating a `TXT` record containing a temporary token. Let's Encrypt then queries your domain's DNS records to look for this token. Forge simplifies this system through the use of CNAME forwarding. Instead of manually creating `TXT` records or providing API tokens for your chosen DNS provider, you instead create a single `CNAME` record that points to a unique target such as `verify-abcdef.ssl.on-forge.com`. Let's Encrypt will follow this `CNAME` and forward requests to the unique `ssl.on-forge.com` subdomain, allowing Forge to automatically manage the underlying `TXT` records. This means you can use DNS-01 verification regardless of your chosen DNS provider. DNS-01 is our recommended choice because: * It works for all domain types, including wildcard subdomains (`*.example.com`). * It is more reliable than HTTP-01 if your site is behind a CDN, firewall, or proxy. * Long-term maintenance is minimal: once the `CNAME` is created, it remains valid for future renewals – no DNS changes needed. Removal of the `CNAME` verification record will cause future renewals to fail. This record must remain in place for as long as you wish to use Let's Encrypt certificates on the domain. #### HTTP-01 verification The HTTP-01 verification method validates domain ownership by serving a temporary file at `http://your-domain.com/.well-known/acme-challenge`. Let's Encrypt then requests this file to verify control. Your domain must resolve to your server and port 80 must be publicly accessible. HTTP-01 is usually the best choice when: * You don't have access to the domain's DNS records to configure additional records. * You have strict restrictions around DNS record targets. * The domain points directly to Forge and you know it won't be placed behind a CDN, proxy, or firewall later. While HTTP-01 can be more convenient to setup in limited cases, it is more fragile. **For most domains, we recommend using DNS-01 instead.** ### Custom certificates In addition to Let's Encrypt, Forge also lets you install your own SSL certificates. This is useful if you use a commercial certificate authority, have an organization-validation (OV) or extended-validation (EV) certificate, or need to reuse an existing certificate across multiple systems. To use a custom certificate, you'll need to provide: * The certificate file, including any intermediate certificates to form the full chain. * The corresponding private key. Custom certificates **are not renewed automatically** by Forge. You are responsible for monitoring their expiration and uploading a new version when they expire. The option does give you full control but generally requires more manual maintenance compared to Let's Encrypt. #### Cloudflare "Edge" certificates Cloudflare provides [free SSL certificates](https://developers.cloudflare.com/ssl/edge-certificates/universal-ssl/enable-universal-ssl/) to all connected domains and all their first-level subdomains. These certificates are automatically enabled on all domains and subdomains that have Cloudflare's proxy functionality enabled. However, if you have multiple nested subdomains (e.g., `staging.api.example.com`), this universal certificate will not cover those domains and may cause an `ERR_SSL_VERSION_OR_CIPHER_MISMATCH` error. If your application requires multiple nested subdomains, we recommend you disable Cloudflare proxying and use a traditional SSL certificate for your Laravel Forge site. ### Certificate Signing Requests (CSRs) Forge can generate a private key and Certificate Signing Request (CSR) directly on your server. You may then submit the CSR to the Certificate Authority (CA) of your choice to obtain a signed certificate. This is the right choice when your CA requires you to supply a CSR or when you need an organization-validation (OV) or extended-validation (EV) certificate that Let's Encrypt does not offer. #### Generating and retrieving the CSR To generate a CSR, open the Domains tab for your site and click **Add certificate > Certificate Signing Request**. You will be asked to provide information about your domain and organization. Once submitted, Forge generates an RSA private key and a `.csr` file on your server. Once the CSR is created, you can copy its contents by clicking the **three-dot button > View signing request** for the certificate. Submit this content to your CA to obtain your signed certificate. #### Installing the signed certificate After your CA issues the signed certificate, return to Forge and click the **three-dot button > Install certificate**. Paste the certificate your CA provided, including any intermediate certificates that are needed to form the full chain. No private key upload is required, as Forge already generated one during the CSR step. Forge will then install the certificate and activate HTTPS for the domain. CSR-based certificates are **not renewed automatically**. You are responsible for monitoring the certificate's expiration date and repeating the process before it expires. ### Cloning certificates Forge allows you to clone an existing SSL certificate from another site to your current site. This feature lets you reuse certificates across multiple sites, including sites on different servers within your Forge account. When adding a new SSL certificate to a domain, you can select the "Clone certificate" option and choose from a searchable list of certificates installed on your other sites. The certificate and its private key will be copied to the new site. Cloned certificates **will not renew automatically**. You are responsible for monitoring the certificate's expiration date and manually updating it when it expires. ## Legacy sites (created prior to Oct 2025) Sites that were created before October 2025 have a slightly different domain and SSL management system. While most of the concepts are similar, there are some key differences: * There is a single Nginx configuration file for the entire site. * All domains on a site share the same SSL certificate. Adding or removing a domain can impact other domains on the same site since the certificate must be manually reissued to cover all domains. * The `www.` redirect type cannot be configured. All domains will redirect from `www.` to the apex domain, unless the domain configured is a subdomain (including `www.`) itself. * Wildcard subdomains are configured at the site level, not per-domain. This means enabling wildcard subdomains will enable them for all apex domains on the site. Forge doesn't currently support migrating legacy sites to the new system. If you want to take full advantage of the new domain and SSL features, you will need to create a new site on your server and reconfigure your application. ### Let's Encrypt For sites created before October 2025, Let's Encrypt certificates are issued using the HTTP-01 verification method unless the site is using wildcard subdomains. All domains on the site must resolve to the server and port 80 must be publicly accessible for HTTP-01 verification to succeed. ### Wildcard subdomain Let's Encrypt certificates If wildcard subdomains are enabled, the DNS-01 verification method will be used instead and you must provide API credentials for your DNS provider. Forge supports the following Let's Encrypt wildcard DNS providers: * Cloudflare * DNSimple * DigitalOcean * Linode * OVH * Route53 #### Cloudflare API token If you are using [Cloudflare](https://cloudflare.com) to manage your DNS, your Cloudflare API token must have the `Zone.Zone.Read` and `Zone.DNS.Edit` permissions. In addition, the token must have permissions on **all** zones attached to your Cloudflare account. #### Route53 user policy If you are using [Route53](https://docs.aws.amazon.com/Route53/latest/APIReference/Welcome) to manage your DNS, your IAM user must have the `route53:ChangeResourceRecordSets` permission on your domain's hosted zone. In addition, the user must have the `route53:GetChange` and `route53:ListHostedZones` permissions. # Environment Variables Source: https://forge.laravel.com/docs/sites/environment-variables Learn how to manage environment variables for your sites. ## Introduction Laravel Forge makes it easy to manage environment variables for your sites. If your project contains a `.env` file, you can easily create and edit environment variables from the "Environment" tab of your site's settings. If Laravel Forge detects a `.env.example` file in your project, it will automatically copy this and replace some of the settings to match your server's database settings during site creation. An empty `.env.example` file could result in an empty environment file on the first deployment of your site. ## Modifying environment variables To modify your site's environment variables, navigate to your site's "Settings" panel and click on the "Environment" sidebar item. When you modify environment variables through Forge, the changes are written directly to the `.env` file within your application. If you're using [zero-downtime deployments](/docs/sites/deployments#zero-downtime-deployments), this file will be symlinked into the current release directory, ensuring your environment configuration is consistent across deployments. After modifying your environment variables, you can optionally choose to automatically run: * **php artisan config:cache** - Caches your configuration files for improved performance. * **php artisan queue:restart** - Gracefully restarts your queue workers to pick up the new environment values. These options help ensure your application immediately reflects the updated environment configuration without requiring manual intervention. ## Encrypted environment files Laravel Forge provides support for Laravel's [encrypted environment files](https://laravel.com/docs/configuration#encrypting-environment-files) without requiring you to include your encryption key within your deployment script. To leverage this feature, add your encryption key to the "Encrypted environment files" section of your site's "Environment" tab. Once added, Laravel Forge will inject the value into the `LARAVEL_ENV_ENCRYPTION_KEY` environment variable during deployments, allowing you to add the `env:decrypt` Artisan command to your deployment script without needing to specify the `--key` option manually. ```bash theme={null} php artisan env:decrypt --force ``` ## Laravel integrations The following Laravel-specific features are only available to sites using the Laravel or Statamic project type: * **php artisan config:cache** - Automatically cache configuration files after updating environment variables. * **php artisan queue:restart** - Automatically restart queue workers after updating environment variables. * **Encrypted environment files** - Support for Laravel's encrypted environment files feature. If your site is using a different project type, these features will not be available. # Laravel Source: https://forge.laravel.com/docs/sites/laravel Laravel Forge provides first-class support for Laravel applications. ## Introduction Laravel Forge provides first-class support for applications running [Laravel](https://laravel.com), allowing you to quickly toggle and configure: * Laravel's Task Scheduler * Laravel's Maintenance Mode * Laravel Horizon * Laravel Octane * Laravel Reverb * Laravel Nightwatch * Inertia.js Server Side Rendering (SSR) To accomplish this, Laravel Forge parses the `composer.lock` file from your application and inspects for the presence and version of the packages above. ### Requirements Laravel Forge will only show the application panel in the site's Overview tab for Laravel framework installations of version `5.0` or later. In addition, the panel's supported packages must meet the following version requirements: | Dependency | Minimum Version | | --------------------------- | --------------- | | `laravel/framework` | `5.0` | | `laravel/horizon` | `1.0` | | `laravel/octane` | `1.0` | | `laravel/pulse` | `1.0` | | `laravel/reverb` | `*` | | `inertiajs/inertia-laravel` | `0.6.6` | ## Laravel Scheduler You may quickly enable or disable the Laravel scheduler via the "Laravel Scheduler" toggle. Laravel Forge will create the required [Scheduler](/docs/resources/scheduler) for you. Laravel Forge will automatically configure the scheduler to run every minute using the site's configured PHP version. ## Maintenance mode If you have deployed a Laravel application, Laravel Forge allows you to make use of Laravel's maintenance mode feature. Clicking the "Laravel Maintenance Mode" toggle within the site's "Application" tab will run the `php artisan down` Artisan command within your application, which will make your site unavailable. When the site is in maintenance mode, you can then toggle it off to make your site available again. ### Maintenance mode "secret" Laravel 8.0+ applications can make use of the "secret" option to bypass maintenance mode. Using this option with older versions of Laravel is not supported. ## Laravel Horizon You may quickly enable or disable the Laravel Horizon daemon via the "Laravel Horizon" toggle. Laravel Forge will create the required Horizon daemon for you. If the site's deploy script does not contain the `horizon:terminate` command, Laravel Forge will automatically append it for you. ### Converting existing daemons If your server is already configured with a daemon that runs Laravel Horizon, Laravel Forge will offer to convert the daemon for you. This process links the site's ID and the daemon's ID together, allowing Forge to manage the daemon for you. ## Laravel Octane You may quickly enable or disable the Laravel Octane daemon via the "Laravel Octane" toggle. Laravel Forge will create the required Octane daemon and install Octane dependencies for you. When enabling the Octane daemon, Laravel Forge will ask you to provide the port number you would like to use for the Octane server as well as your Octane server of choice. If the site's deploy script does not contain the `octane:reload` command, Laravel Forge will automatically append it for you. Before enabling Laravel Octane, you must set the `OCTANE_SERVER` environment variable to the Octane server you choose. ### Converting existing daemons If your server is already configured with a daemon that runs Laravel Octane, Laravel Forge will offer to convert the daemon for you. This process links the site's ID and the daemon's ID together, allowing Forge to manage the daemon for you. ## Laravel Reverb Determining the correct server type for hosting Laravel Reverb depends on your configuration requirements. You may use the table below to help inform your decision: | Configuration | App Server | Web Server | | ---------------------------------------------------------------------- | :--------: | :--------: | | Reverb server alongside Laravel application | ⊙ | | | Dedicated Reverb server | | ⊙ | | Dedicated Reverb server with Pulse | ⊙ | | | Dedicated Reverb server with Pulse (separate ingest and / or database) | | ⊙ | Once your preferred server has been provisioned, you should [add a new site](/docs/sites/the-basics#creating-sites) and [install your Reverb-enabled Laravel application](/docs/sites/the-basics#apps-projects) from your version control provider of choice. Now, you may quickly enable or disable Laravel Reverb via the "Laravel Reverb" toggle within Laravel Forge's application panel in the site's Overview tab. When enabling Reverb, Forge will create the Reverb daemon, install the required dependencies, and configure the server for optimum performance. Additionally, Laravel Forge will prompt for additional information required to setup the server per your requirements. * **Public Hostname:** Used to update the Nginx configuration of the site, allowing Reverb connections to be accepted by the server on the given hostname. Laravel Forge will default to a subdomain of the site's current hostname, but you are free to customize this value. For example, if the site's hostname is `example.com`, Forge will default Reverb's hostname to `ws.example.com`. * **Port:** Used to instruct the Reverb daemon which server port it should run on. Laravel Forge will proxy requests for the given public hostname to this port. * **Maximum Concurrent Connections:** The number of connections your Reverb server can handle will depend on a combination of the resources available on the server and the amount of connections and messages being processed. You should enter the number of connections the server can manage before it should prevent new connections. This option will update the server's allowed open file limit, Nginx's allowed open file and connection limit, and install the `ev` event loop if required. Laravel Forge ensures the hostname provided during Reverb's installation process is publicly accessible by adding a new server block to your existing site's Nginx configuration. This server block is contained within a new file and is not available to edit from the Forge UI dashboard. If the site's deploy script does not contain the `reverb:restart` command, Laravel Forge will automatically append it for you. ### SSL If an SSL certificate exists for your site which protects Reverb's configured hostname, Laravel Forge will automatically install it when enabling Reverb, ensuring your Reverb server is accessible via secure WebSockets (`wss`). If Reverb is installed before a valid certificate is available, you may request a new certificate for Reverb's configured hostname from your site's "SSL" tab. Laravel Forge will automatically configure secure WebSockets for Reverb as soon as the certificate is activated. Forge will also pre-populate the "Domains" SSL form input with Reverb's hostname when requesting a certificate. After activating SSL on a Reverb-enabled site, you should ensure the following environment variables are properly defined before redeploying your site: ``` REVERB_PORT=443 REVERB_SCHEME=https VITE_REVERB_PORT="${REVERB_PORT}" VITE_REVERB_SCHEME="${REVERB_SCHEME}" MIX_REVERB_PORT="${REVERB_PORT}" MIX_REVERB_SCHEME="${REVERB_SCHEME}" ``` ### Converting existing daemons If your server is already configured with a daemon that runs Laravel Reverb, Laravel Forge will manage the daemon for you. This process links the site's ID and the daemon's ID together, allowing Forge to manage the daemon on your behalf. When disabling Reverb, Laravel Forge will remove the daemon and ensure the public hostname is no longer accessible. However, any settings Forge updated when enabling Reverb, such as open file and connection limits, will not be reset and any PHP extensions installed will not be removed. ## Inertia server-side rendering (SSR) You may quickly enable or disable the Inertia SSR daemon via the "Inertia SSR" toggle. Laravel Forge will create the required Inertia SSR daemon for you. When enabling the Inertia daemon, Laravel Forge will ask you to provide a few more details. You may also choose whether Forge should update your deploy script to append the Inertia SSR stop command. ### Converting existing daemons If your server is already configured with a daemon that runs Inertia SSR, Laravel Forge will offer to convert the daemon for you. This process links the site's ID and the daemon's ID together, allowing Forge to manage the daemon for you. # Logs Source: https://forge.laravel.com/docs/sites/logs Understand and manage logs for your sites in Laravel Forge ## Introduction Laravel Forge allows you to view a site's log files from within the dashboard. If your site is a Laravel application, Forge will automatically detect and display the log files located in the `storage/logs` directory. Both `daily` and `single` log formats are supported, and Forge will automatically read the last updated file. For performance reasons, Laravel Forge will only return the last 500 lines from a file. ## Logrotate When provisioning your server, Laravel Forge automatically installs and configures Logrotate on the server to ensure log files don't grow indefinitely and consume excessive disk space. The configuration files for Logrotate can be found in `/etc/logrotate.d/`. The primary configuration file is located at `/etc/logrotate.conf`. To view older "rotate" or "compressed" logs, you can use `cat` for non-compressed files or `zcat` for compressed files. # Network Source: https://forge.laravel.com/docs/sites/network Learn how Laravel Forge can manage your site’s redirect and security rules. ## Introduction Laravel Forge can manage your site’s redirect and security rules. ## Security rules Laravel Forge can configure password protection on your sites using [basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). You can choose whether to protect your entire site or a specific path. ### Managing security rules #### Creating security rules To create a security rule, navigate to your site's dashboard and click the "Network" tab. Then, click the "Add security rule" button. After providing a security rule name, path and a list of credentials click "Add security rule". #### Editing security rules To edit a security rule, navigate to your site's dashboard and click the "Network" tab. Locate the security rule that you want to update, open the dropdown menu, click "Edit". #### Deleting security rules To delete a security rule, navigate to your site's dashboard and click the "Network" tab. Locate the security rule that you want to delete, open the dropdown menu, click "Delete". ### Credentials Laravel Forge creates a unique `.htpasswd` file for each security rule, meaning each secured path may have its own set of credentials. This also means that you will need to re-enter the same credentials when securing multiple paths. If you need to modify the credentials, you can find the `.htpasswd` file at `/etc/nginx/forge-conf/.../server/.htpasswd-{ruleId}` on your servers. Laravel Forge does not store your security rule passwords on our servers. ### Customization Nginx allows you to add further access restrictions such as allowing and denying access to users by IP address. Laravel Forge does not provide the ability to configure this, but you are free to customize your own protected site configuration. Forge creates a `/etc/nginx/forge-conf/.../server/protected_site-{ruleId}.conf` configuration file for protected sites. You can read more about Nginx and basic access authentication [in the Nginx documentation](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/#). ## Redirect rules Laravel Forge allows you to configure redirects that can be configured to automatically redirect visitors from one page to another. These redirect rules can be created via the "Redirects" tab of the site's management dashboard. ### Managing redirect rules #### Creating redirect rules To create a redirect rule, navigate to your site's dashboard and click the "Network" tab, and then into the "Redirects" sidebar. Then, click the "Add redirect rule" button. After providing a redirect rule name, path and a list of credentials click "Add redirect rule". Redirects are wrappers around Nginx's [`rewrite` rules](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#rewrite) and can use the full redirect syntax supported by Nginx, including regular expressions. For example, you could use `^/$` to only match the root of the domain. #### Editing redirect rules To edit a redirect rule, navigate to your site's dashboard and click the "Network" tab, and then into the "Redirects" sidebar. Locate the redirect rule that you want to update, open the dropdown menu, click "Edit". #### Deleting redirect rules To delete a redirect rule, navigate to your site's dashboard and click the "Network" tab, and then into the "Redirects" sidebar. Locate the redirect rule that you want to delete, open the dropdown menu, click "Delete". ### Temporary vs. permanent redirects Laravel Forge supports two types of redirects: * Permanent (HTTP Status Code 301) * Temporary (HTTP Status Code 302) Although both of these redirect types are typically invisible to the user, the browser will treat them differently and it is important to know the difference. #### Temporary redirects When the browser encounters a temporary redirect, it will take you to the destination and forget that it was redirected from the original page. If you were to change the destination page and then visited the original page again, the browser would see the new redirect location and take you there. #### Permanent redirects With a permanent redirect, the browser will remember that it was redirected away from the original page. To save making another network request, the next time the browser visits the original page, it will see that it was redirected and immediately visit that page instead. Although you can change the destination of a permanent redirect, you will need to clear the browser cache before you visit the original page again. It's considered bad practice to change a permanent redirect, so be careful when doing so. # Queues Source: https://forge.laravel.com/docs/sites/queues Manage Laravel queue workers. ## Introduction Laravel Forge's site management dashboard allows you to easily create as many Laravel queue workers as you like. Queue workers will automatically be monitored by Supervisor, and will be restarted if they crash. All workers will start automatically if the server is restarted. ## Creating a queue worker You can create a new queue worker within the site's management dashboard. The "New Worker" form is a wrapper around the Laravel queue feature. You can read more about queues in the [full Laravel queue documentation](https://laravel.com/docs/queues). When creating a new queue worker, you may [select a version of PHP](/docs/servers/php) that is already installed on the server. The selected version of PHP will be used to execute the queue worker. ## Laravel Horizon If your Laravel application is using [Laravel Horizon](https://laravel.com/docs/horizon), you should not setup queue workers as described above. Instead, you may enable Horizon on Laravel Forge using Forge's "daemon" feature. First, enable the [Laravel Horizon](/docs/sites/laravel#laravel-horizon) integration. Forge will automatically add `php artisan horizon:terminate` Artisan command to your site's deployment script, as described in [Horizon's deployment](https://laravel.com/docs/master/horizon#deploying-horizon) documentation. When using Zero Downtime deployments, the `$RESTART_QUEUES()` macro will handle this automatically. Finally, if you wish to use Horizon's [metrics graphs](https://laravel.com/docs/master/horizon#metrics), you should configure the scheduled job for `horizon:snapshot` in your application code. In addition, you should define a [Scheduler task](/docs/resources/scheduler#scheduled-jobs) within Laravel Forge for the `php artisan schedule:run` Artisan command if you have not already done so. ## Restarting queue workers after deployment When deploying your application, it is important that your existing queue workers or Horizon processes reflect the latest changes to your application. This can be achieved by gracefully restarting these services from your deployment script: When using queue workers: ```bash theme={null} $FORGE_PHP artisan queue:restart ``` When using Horizon: ```bash theme={null} $FORGE_PHP artisan horizon:terminate ``` The `queue:restart` command requires a cache driver that persists data between requests. If your application's cache driver is set to `array`, the command will fail silently because the `array` driver stores data in memory that is lost between requests. ## Team permissions You may grant a team member authority to create and manage queue workers by granting the `site:manage-queues` permission. # Repository Access Source: https://forge.laravel.com/docs/sites/repository-access How Laravel Forge authenticates to your source control provider when cloning and deploying, and how to resolve access errors, especially with Bitbucket. ## Introduction When Forge installs or deploys a site, it clones your repository from your source control provider. This page explains **which credential Forge uses** for that clone, why the answer differs between zero-downtime and standard deployments, and how to fix the most common access error: ``` git@bitbucket.org: Permission denied (publickey). fatal: Could not read from remote repository. ``` ## How Forge authenticates Depending on how a site is configured, Forge clones using one of three identities: * **The connection's OAuth token**: used only by zero-downtime deployments, over HTTPS. No SSH key is involved. * **A deploy key**: an SSH key unique to a single site, which you add to that repository. See [deploy keys](/docs/ssh#deploy-keys). * **The server's SSH key**: a key registered on your source control account that allows the server to clone repositories the account can access. See [server keys](/docs/ssh#server-keys). Which one applies depends mostly on whether the site uses zero-downtime deployments. ## Deployment strategies The deployment strategy determines which credential Forge uses to clone the repository. Clones over **HTTPS using the connection's OAuth token**. No SSH key is required, and the site authenticates as the connected account. A GitHub, GitLab, or Bitbucket site with zero-downtime deployments enabled generally requires no additional SSH key configuration. Clones over **SSH**, which requires a key that is registered with your source control provider and can read the repository: a [deploy key](/docs/ssh#deploy-keys) on the repository, or the [server's SSH key](/docs/ssh#server-keys) on the account. Without a registered key, the clone fails with `Permission denied (publickey)`. The same repository can deploy successfully as a zero-downtime site (HTTPS token) while failing as a standard site (SSH) if no SSH key is registered. If you disable zero-downtime deployments on a Bitbucket site, make sure a deploy key or the server key is registered first. ## Bitbucket specifics Bitbucket behaves differently from GitHub and GitLab because **Bitbucket does not offer an API for managing SSH keys**. Forge can register the server's key on GitHub and GitLab automatically, but for Bitbucket you must add keys yourself. When you create a **standard** (non-zero-downtime) Bitbucket site in the Forge dashboard, Forge checks whether the server can already reach the repository and, if it cannot, shows you the exact SSH key to add to your Bitbucket account before the site can be installed. Add the displayed key to your Bitbucket account (or use a deploy key), click **Verify SSH connection**, and continue once it turns green. Because Bitbucket has no key-management API, Forge cannot register keys for you. For Bitbucket standard-deployment sites (and especially for sites created via the [API or SDK](#creating-sites-via-the-api), where there is no dashboard prompt), [deploy keys](/docs/ssh#deploy-keys) are the most reliable option. ## Isolated sites When [user isolation](/docs/sites/user-isolation) is enabled, a site's deployment runs as that site's dedicated system user, **not** the default `forge` user. That isolated user does not have the server's SSH key in its home directory, so it cannot rely on the server key to clone. Isolated standard-deployment sites therefore need their own credential: * A [deploy key](/docs/ssh#deploy-keys) generated for the site and added to the repository (recommended), or * Zero-downtime deployments enabled, so the clone uses the OAuth token instead of SSH. ## Creating sites via the API Unlike the Forge dashboard, the API and SDK cannot prompt you to add a key while creating a site. For **standard Bitbucket sites created via the API** (particularly [isolated](/docs/sites/user-isolation) ones), use a deploy key you register *before* creating the site: Generate an SSH keypair locally (for example, `ssh-keygen -t ed25519 -f ./deploy_key -N ""`). Add the **public** key to the repository's access keys in Bitbucket. Doing this first avoids a failed clone and the automatic site rollback that follows it. Include `generate_deploy_key: true` along with the `public_deploy_key` and `private_deploy_key` you generated. The clone will use the already-registered deploy key and succeed. If a site's initial clone fails, Forge automatically rolls the site back, removing the Nginx configuration, domain, and isolated user. Registering the deploy key before creating the site avoids this. Note that `generate_deploy_key: true` means "use the keypair I am supplying", not "generate one for me", so you must still pass `public_deploy_key` and `private_deploy_key`. ## Managing a site deploy key via the API You do not have to recreate a site to move it onto a deploy key. Once a site exists, you can generate, inspect, or remove its deploy key through the API, which is the cleanest way to convert an existing OAuth or server-key site to per-repository access. The endpoints live in the **Deployments** group of the [API reference](/docs/api-reference/introduction): * `GET` on `.../sites/{site}/deploy-key` returns the site's current public deploy key. * `POST` on `.../sites/{site}/deploy-key` generates a deploy key for the site. * `DELETE` on `.../sites/{site}/deploy-key` removes the site's deploy key. Unlike the create-time flow, where you supply your own keypair, the `POST` endpoint generates the keypair **on the server** and returns the public key in the response's `key` attribute. Add that key to the repository's deploy keys on your provider so the server can clone. Once a site has a deploy key, Forge deploys using it and stops managing account- or server-level keys for that site. If the site already has a deploy key, `POST` returns the existing key unchanged rather than rotating it; to replace a key, delete it first and then generate a new one. Forge never registers the key on your provider for you, so remember to add the returned public key to the repository yourself. ## Troubleshooting access errors Most repository access failures fall into one of two categories, and the error in the deployment output tells you which: * **`Permission denied (publickey)`** means an SSH clone could not authenticate. The site is deploying over SSH (a standard, non-zero-downtime deployment) and no SSH key that can read the repository is registered. This is a **key** problem. * **`Authentication failed`, `Repository not found`, or an HTTP `403`/`404`** means a zero-downtime clone could not use the connection's OAuth token. This is a **token or permission** problem, and no SSH key is involved. No SSH key that can read the repository is registered for this site. Add a [deploy key](/docs/ssh#deploy-keys) to the repository (recommended), or register the [server's key](/docs/ssh#server-keys) on your GitHub, GitLab, or Bitbucket account, then redeploy. Alternatively, enable zero-downtime deployments so the site clones over HTTPS with the OAuth token and skips SSH entirely. On GitHub and GitLab, Forge can register the server key for you; on Bitbucket you must add it manually, since Bitbucket has no key-management API. An existing site usually already has a registered deploy key, or was created while a working key was in place, whereas a brand-new site has no credential of its own until you add one. This is common after moving a project from a custom or deploy-key setup to an OAuth provider, because the new OAuth sites start without a registered key. Add a deploy key to the new site, or confirm the server key is registered on the account. The connection's OAuth token is expired, revoked, or was reset on the provider. Open the organization's [source control](/docs/source-control) settings, use **Verify connection** to confirm, then **Reconnect** to refresh the token. If an expired token is stored in an older site's Git remote, redeploying after reconnecting updates it. The provider may restrict visibility of a repository even when the token is valid. On GitHub, the Forge OAuth app may not be approved for the organization that owns the repository. On GitLab, group or project access may be restricted. On Bitbucket, a **workspace IP allowlist** or app-access policy can hide repositories even while deploys from an allowlisted server still succeed. **Reconnect** the connection and explicitly grant access to the organization or workspace, or adjust the provider's access controls, then try again. An SSH key can be registered on only **one** account per provider. If the same public key is already attached to a different account (most commonly on Bitbucket), the provider refuses to add it again. Use a per-site [deploy key](/docs/ssh#deploy-keys) on the repository instead of a shared account key, so each site has a unique key. ## Choosing an approach Use **zero-downtime deployments** when you want the simplest setup and do not need SSH key management. Forge clones over HTTPS using the connection's OAuth token, which authenticates as the connected account. Use a **deploy key** for standard deployments, [isolated sites](/docs/sites/user-isolation), or per-repository access. A deploy key is a dedicated SSH key that grants a site access to one repository. Use the **server key** when you want a server to clone every repository available to the associated source control account. This reduces per-site key management, but grants broader access than a deploy key. # Creating and Managing Sites Source: https://forge.laravel.com/docs/sites/the-basics Learn how to create sites and install applications. ## Introduction Laravel Forge provides a simple and intuitive interface for managing and deploying your web applications. ## Creating sites When you create a new site in Forge, you're presented with a variety of configuration options to tailor the site to your needs. These options vary depending on the type of site you're creating, but generally include settings for the Forge domain, web directory, PHP version, and more. ### Source control provider Laravel Forge allows you to install applications directly from your source control provider. If you're using a hosted Git service (GitHub, Bitbucket, GitLab) then Laravel Forge will provide you with a list of repositories that you have access to. You can choose one of these repositories, as well as the branch, that you wish to install. When using a custom Git repository, you will need to provide the full SSH URL of the repository and manually enter the branch you wish to install. If you create a site without a repository, you cannot add one later. You need to recreate it. Laravel Forge must be able to access your repository via SSH. You will be prompted to add your server's public SSH key to the source control provider during the site creation process. #### Deploy keys Sometimes you may wish to only grant Laravel Forge access to a specific Git repository. If that is the case, you can generate a unique SSH key during the site creation process and add it to your source control provider's "Deploy Keys" section in the GitHub, GitLab, or Bitbucket dashboard. ### Forge domain Every site created in Laravel Forge is provided with a free `on-forge.com` domain. These vanity domains are automatically available as soon as a site is created and proxied through Cloudflare which provides HTTPS encryption. You can customize the subdomain used for your site during the site creation process, or use the automatically generated one and configure a custom domain later. ### Installing Composer dependencies When creating a new PHP site (Laravel, Statamic, Symfony, vanilla PHP), you can choose to have Laravel Forge automatically install Composer dependencies for you. This is done after the site has been created, but will also update your site's default deploy script to include the `composer install` command for future deployments. Laravel Forge will run the following command to install your Composer dependencies: ```bash theme={null} composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader ``` If your project does not contain a `composer.lock` file, you should uncheck this option. ### Advanced settings If you need more control over how your site is created, you can open the "Advanced settings" modal during the site creation process. This allows you to: * **Customize the web directory** used by your site – this defaults to `/public` for the majority of site types. * **Choose the PHP version** used by your site – this defaults to the server's default PHP version. * **Configure [website isolation](/docs/sites/user-isolation)** – configures a dedicated PHP-FPM process for the site. * Enable or disable **push to deploy** – this is enabled by default and will automatically deploy your site when you push to the configured Git branch. * Enable or disable [**zero downtime deployments**](/docs/sites/deployments#zero-downtime-deployments) – this is enabled by default for new sites and can only be configured during site creation. Laravel Forge provides a set of sensible defaults for these settings based on the type of site you're creating, but you can customize them as needed. ## Pre-configured applications Laravel Forge makes it incredibly easy to install popular applications such as Statamic, WordPress, and phpMyAdmin. These applications are pre-configured with sensible defaults so you can get started quickly. ### Statamic Whilst it is possible to create a Statamic site from a Git repository, Laravel Forge also provides a simple way to create a new Statamic site from a ["starter kit"](https://statamic.com/starter-kits). When creating a new Statamic site, you will need to choose a starter kit and provide an email address for the created "super user". If the "Super user password" field is left blank, the default password of `password` will be used for the created user. We recommend using the "Generate password" action, entering a strong password for the super user, or changing it immediately after installation. Once Statamic has been installed, you can visit your site using the provided Forge domain and log in to the control panel using the email address you provided during installation. ### WordPress When creating a new WordPress site, Laravel Forge will automatically install the latest version of WordPress for you, as well as the WordPress CLI so that you can manage your installation with the `wp` command. You will need to choose an existing database for WordPress to use, or create a new one, to proceed. If you plan to use a custom domain with your WordPress site, you should configure your custom domain in Forge before you install WordPress, as WordPress will use the domain you provide during installation to generate URLs for your site. Once WordPress has been installed, you can visit your site using the provided Forge domain and complete the WordPress installation from your browser. You should continue installing WordPress as soon as Laravel Forge has installed it for you, so that it's made secure with your username and password. You could also choose to create a new ["security rule"](/docs/sites/network#security-rules) before you install WordPress so that your installation is password protected. #### Customizing `wp-config.php` If you need to customize your site's `wp-config.php` file, you can do so from the "WordPress" tab in your site's settings. You can use this to add authentication keys, define constants like `DISALLOW_FILE_EDIT`, or modify the database table prefix. Editing some variables such as `$table_prefix` will invoke the WordPress installer and you will need to reinstall your WordPress site after making this change. The following variables will trigger the WordPress installer if they are changed: * `$table_prefix` * `AUTH_KEY` * `AUTH_SALT` * `DB_HOST` * `DB_NAME` * `DB_PASSWORD` * `DB_USER` * `LOGGED_IN_SALT` * `NONCE_KEY` * `NONCE_SALT` * `SECURE_AUTH_KEY` * `SECURE_AUTH_SALT` ### phpMyAdmin Laravel Forge also supports installing [phpMyAdmin](https://phpmyadmin.net), allowing you to manage your server's databases from anywhere. You will need to choose an existing database, or create a new one, to proceed. This database is used by phpMyAdmin to store the configuration of your databases and users. Once Laravel Forge has installed phpMyAdmin, you can visit your site using the provided Forge domain and log in using any of your database username and password combinations. Some very small server sizes, such as `t2.nano` on AWS, do not have enough resources to run an application like phpMyAdmin. ## PHP versions If your server has [multiple versions of PHP](/docs/servers/php) installed, you can switch the version used by your site at any time by using the site's "Settings" tab in the Laravel Forge dashboard. When switching the version used by your site, you should ensure that your server has any additional PHP extensions / modules installed for that version. Failure to install additional modules may make your site unresponsive. Laravel Forge will automatically update your site's Nginx configuration files to use the correct PHP-FPM socket and reload the required services for you. ## Team permissions You may grant a team member authority to create and delete sites by granting the `site:create` and `site:delete` permissions. # User Isolation Source: https://forge.laravel.com/docs/sites/user-isolation Learn how to isolate your sites on Laravel Forge. ## Introduction By default, Laravel Forge uses the default `forge` user that is created as part of the server's initial provisioning process for all deployments, daemons, scheduled jobs, PHP-FPM, and other processes. Via Laravel Forge's "User Isolation" feature, Forge will create a separate user for a given site. This is particularly useful when combined with a project like WordPress in order to prevent plugins from maliciously accessing content in your `forge` user (or other isolated user) owned directories. The `forge` user is considered a "super user" and is therefore able to read all files within isolated user directories. ## Sudo access Like the `forge` user, newly created isolated users also have limited sudo access. They may reload the PHP-FPM services requiring a password: ```bash theme={null} sudo -S service php8.5-fpm reload ``` If you need further sudo access, you should log in as the `forge` user and switch to the `root` user using the `sudo su` or the `sudo -i` command. ## Connecting via SFTP You can connect to your server via SFTP as the isolated user. We recommend using an SFTP client such as [Transmit](https://panic.com/transmit/) or [Filezilla](https://filezilla-project.org/). However, before getting started, you should first [upload your SSH key to the server](/docs/ssh) for the isolated user. # Source Control Source: https://forge.laravel.com/docs/source-control Source control providers allow Laravel Forge to access your project's codebase and easily deploy your applications. ## Introduction Source control providers allow Laravel Forge to access your project's codebase and easily deploy your applications. Forge supports most popular Git providers as well as custom / self-hosted options. Source control providers are configured and managed within the [organization's](/docs/organizations) settings. Each account you authenticate is stored as an independent **connection**, and a single organization may hold many connections at once, including multiple connections for the same provider. ## Supported providers Laravel Forge supports the following source control providers: * [GitHub](https://github.com/) * [GitLab](https://about.gitlab.com/) (hosted and self-hosted) * [Bitbucket](https://bitbucket.org/) * Custom Git Repositories ## Managing source control providers ### Connecting to a source control provider To connect a source control provider, navigate to the organization's settings. Then, on the "Source control" page, click "Add provider". Select the provider you wish to connect to and authenticate your chosen account. You may connect the same provider more than once. For example, you can add a personal GitHub account alongside a work account, or connect GitLab accounts with access to different groups. Each authenticated account becomes its own connection and is managed independently. When you keep several connections for the same provider, use the "Rename" action to give each one a memorable label so you can tell them apart when creating a site. When you connect a source control provider via OAuth, the API token grants Forge access to all repositories accessible by your authenticated account. If a server is compromised, an attacker could potentially use this token to discover and access other repositories. For enhanced security, consider using [deploy keys](/docs/ssh#deploy-keys) instead, which limit access to only specific repositories. ### Managing a connection Each connection has a dropdown menu on the "Source control" page. The available actions depend on the provider, and may include: * **View sites**: list the sites that are currently deploying from this connection. * **Verify connection**: confirm the connection's token is still valid and can reach your repositories. * **Reconnect**: re-run the OAuth flow to refresh the token or grant access to additional organizations and repositories. * **Manage GitHub access**: open GitHub to adjust which repositories the Forge application can access. * **Rename**: give the connection a custom label. This is especially useful when you have several connections for the same provider. * **Edit**: update connection settings (available for connection types such as self-hosted GitLab). * **Copy ID**: copy the connection's ID. * **Delete**: remove the connection. ### Removing a connection To unlink a connection, navigate to the organization's settings. Then, on the "Source control" page, click the dropdown menu on the connection and click "Delete". A connection cannot be deleted while an active site is using it. Move or delete the affected sites first, or switch them to a different connection. ### Reconnecting and updating access To refresh a connection's token, or to grant Forge access to different organizations, repositories, or permission scopes, use the **Reconnect** action on the connection's dropdown menu. This re-runs the full OAuth authentication flow so you can explicitly authorize the access you need. If reconnecting does not surface the organizations or repositories you expect, the underlying provider authorization may need to be reset first: 1. Navigate to your source control provider's settings. 2. Locate and uninstall (or revoke access for) the Laravel Forge application. 3. Return to Laravel Forge. 4. Click **Reconnect** to initiate a fresh OAuth authentication flow, then authorize the desired organizations and repositories. ### Using custom Git providers If your Git Provider is not a first-party provider, then you may use the **Custom** option when creating a new site on your server. First, choose the `Custom` option when creating your Git based site. Next, add the generated SSH key to your source control provider and provide the full repository path (`git@provider.com:user/repository.git`). Custom Git sites cannot use [push to deploy](/docs/sites/deployments#push-to-deploy), because Forge cannot register a deployment webhook on an arbitrary Git host. If your repository is hosted on a first-party provider you later connect, you can switch the site over from its **Git** settings to enable push to deploy and the other provider-aware features. # SSH Keys Source: https://forge.laravel.com/docs/ssh SSH keys are used to authenticate with your server over the SSH protocol. ## Introduction SSH is a protocol that allows you to securely access your server via a command line terminal. SSH keys are used to authenticate with your server over the SSH protocol. If you are new to SSH keys, we recommend checking out the [GitHub documentation of generating SSH keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) to get started. As part of the provisioning process, Laravel Forge will add all active organization SSH keys to the `forge` account. This will allow you to SSH into the server as the `forge` user. After adding your SSH key to your server, you may SSH into the server without a password: ```bash theme={null} ssh forge@YOUR_SERVERS_PUBLIC_IP_ADDRESS ``` If you have provisioned a custom server that configures a different SSH port, you will need to provide the port in the command. ```bash theme={null} ssh forge@YOUR_SERVERS_PUBLIC_IP_ADDRESS -p YOUR_SERVERS_SSH_PORT_NUMBER ``` ## Managing organization SSH keys Laravel Forge will automatically add all organization-level SSH keys to any server that is created within the organization. ### Creating organization keys To create an organization SSH key, navigate to the organization’s dashboard and click Settings. Then, navigate to the Security page, click the Add SSH key button. After providing a key name and the **Public key** click Add key. ### Deleting organization keys To delete an organization SSH key, navigate to the organization’s dashboard and click Settings. Then, navigate to the Security tab and click the dropdown next to the key you want to delete. Click Delete and confirm that you want to delete the key. Laravel Forge will not automatically remove organization SSH keys from servers. You must do this manually. ## Managing account SSH keys Laravel Forge makes it easy to manage SSH keys on your own account, making it easy to quickly add your own keys to servers. ### Creating account keys To create an account SSH key, navigate to your account dashboard and click the "SSH" tab. Then, click the "Add key" button. After providing a key name and the **Public key**, click "Add key". ### Deleting account keys To delete an account SSH key, navigate to your account dashboard and click the "SSH" tab. Then, click the dropdown next to the key you want to delete. Click "Delete" and confirm that you want to delete the key. When deleting an account key, Laravel Forge will also attempt to remove the key from servers. ## Managing server SSH keys ### Creating server keys To create a server SSH key, navigate to the server and click "Settings". Then, navigate to the "SSH" tab and click the "Add key" button. After providing a key name and the **Public key** click Add key. If your server has any sites configured with website isolation, you will also be able to select the user to add the key to. By default, this will be the `forge` user. ### Deleting server keys To delete a server SSH key, navigate to the server and click "Settings". Then, navigate to the "SSH" tab and click the dropdown next to the key you want to delete. Click "Delete" and confirm that you want to delete the key. ### Adding account keys To add your account’s SSH keys, navigate to the server and click "Settings". Then, navigate to the "SSH" tab and click the "Add key" button. Click on the "Add from account" dropdown item, then select the key you want to add to the server and click "Add". ## Server keys ### Server public key During the provisioning process, Laravel Forge will generate its own keypair so that it may access the server. It will add the public key from this keypair to the `~/.ssh/authorized_keys` file of both the `root` and `forge` users. ### Laravel Forge public key During the provisioning process, Laravel Forge will generate a public key for the `forge` user. This is used by Git to clone the projects to your server. The key will be added to the source control provider. This key is located at `/home/forge/.ssh/id_rsa.pub`. When you add the server's SSH key to your source control provider, the server gains access to **all repositories** accessible by your source control account. If the server is compromised, an attacker could potentially access any repository your account can reach. For enhanced security, consider using [deploy keys](#deploy-keys) to limit access to only the specific repositories each site requires. Alternatively, you may opt out of having this key added to your source control providers by un-checking the **Add server's SSH key to source control providers** option when creating a server. When opting-out, you will need to use site-level [deploy keys](#deploy-keys) in order to grant your server access to specific repositories on a source control provider such as GitHub, GitLab, or Bitbucket. ### Deploy keys Sometimes you may wish to only grant the Laravel Forge user access to a specific repository. This is typically accomplished by adding an SSH key to that repository's "Deploy Keys" on the repository's GitHub, GitLab, or Bitbucket dashboard. When adding a new site to the server, you may choose to generate a Deploy Key for that application. Once the key has been generated, you can add it to the repository of your choice via your source control provider's dashboard - allowing the server to clone that specific repository. You may also add, retrieve, or remove a deploy key for an existing site through the API - see [managing a site deploy key via the API](/docs/sites/repository-access#managing-a-site-deploy-key-via-the-api). Deploy keys provide better security isolation than server-level SSH keys. Each deploy key only grants access to a single repository, so if a server is compromised, the attacker can only access the repositories explicitly configured with deploy keys on that server—not your entire source control account. Deploy keys can be used on servers that have their SSH key attached to your source control provider accounts, allowing you to grant the server access to clone a repository that the source control account connected to your Laravel Forge account does not have collaborator access to. # Storage Providers Source: https://forge.laravel.com/docs/storage-providers Learn about the storage providers supported by Laravel Forge for database backups. ## Introduction Storage providers allow Laravel Forge to store your database backups on external object storage services. Once configured, a storage provider can be reused across multiple servers and backup configurations within your organization. Storage providers are configured and managed within the [organization's](/docs/organizations) settings. ## Supported providers Laravel Forge supports the following storage providers: * [Amazon S3](https://aws.amazon.com/s3/) * [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces) * [Hetzner](https://www.hetzner.com/storage/object-storage/) * [Scaleway](https://www.scaleway.com/en/object-storage/) * [OVH Cloud](https://www.ovhcloud.com/en/public-cloud/object-storage/) * Custom (S3 Compatible) Not all providers are 100% compatible with Amazon S3's API. Some providers, such as OVH and Scaleway, require a custom configuration to work correctly, typically through the use of `awscli-plugin-endpoint`. ## Managing storage providers ### Adding a storage provider To add a storage provider, navigate to the organization's settings. Then, on the "Storage providers" page, click "Add provider". Select the provider you wish to configure and provide the required credentials. For Amazon S3, DigitalOcean Spaces, Hetzner, Scaleway, and OVH Cloud, you need to provide: * A name for the storage provider * The region your backups should be stored in (`eu-west-2`, `nyc3`, etc.) * The access and secret keys that should be used to connect to the storage service When using a custom, S3 compatible provider, you must supply: * The service endpoint or URL * The access and secret keys that should be used to connect to the storage service You may also provide a default bucket and storage directory. These values can be overridden when creating a [backup configuration](/docs/resources/database-backups). ### Using EC2 assumed roles When using Amazon S3 in combination with an EC2 server, you can choose to use the identity of the EC2 server to stream the backup to S3 without providing credentials. To use this option, enable the "Use EC2 Assumed Role" toggle when creating the storage provider. When using Amazon S3 to store your database backups, your AWS IAM user must have the following permissions for S3: * `s3:PutObject` * `s3:GetObject` * `s3:ListBucket` * `s3:DeleteObject` ### Editing storage providers To edit a storage provider, navigate to the organization's settings. Then, on the "Storage providers" page, click the dropdown menu on the provider and click "Edit". You can update any of the configuration options, including credentials. ### Deleting storage providers To delete a storage provider, navigate to the organization's settings. Then, on the "Storage providers" page, click the dropdown menu on the provider and click "Delete". Storage providers cannot be deleted while they are in use by one or more backup configurations. You must first update or delete those backup configurations before removing the storage provider. ## Team permissions The ability to manage storage providers is controlled by the `storage:manage` permission. # Support Source: https://forge.laravel.com/docs/support You can get in touch with our support team the following ways: * **Email**: [forge@laravel.com](mailto:forge@laravel.com) * **Chat**: Click "Help" within the Laravel Forge dashboard nav bar to leave a message for the support team. # Teams Source: https://forge.laravel.com/docs/teams Collaborate with team members and manage servers and sites on your behalf. ## Introduction Teams allow you to further manage members of an organization by only granting them access to certain servers or resources within that organization. You can create as many teams as you would like and add as many team members as needed to each team. ## Managing teams ### Creating teams To create a team, navigate to the organization's dashboard and click "Teams". Then, click the "New team" button. After providing a name, click "Create". ### Editing teams To edit a team, navigate to the team's dashboard. Then, on the "Teams" page, click on the team that you wish to edit. Navigate to the "Settings" tab to change the name, avatar or delete the team. ### Deleting teams To delete a team, navigate to the team's dashboard. Then, on the "Teams" page, click on the team that you wish to edit. Navigate to the "Settings" tab and click "Delete team". Confirm the team's name and press "Confirm". When deleting a team, members will no longer be able to access any shared resources. ## Organization members As an owner or admin of an organization on the Business plan, you are able to create and manage teams. ### Managing team members To invite a new member to the team, you need to provide their email address and at least one permission. If the email address provided doesn’t match an existing Laravel Forge account, the user will be invited to create an account. The invited user may accept the invite from the same email. ### Inviting new members To invite someone to an organization, navigate to the organization's dashboard and click "Settings" > "Members". Then, enter the email of the new user, select their role, and click "Send invite". The invited user will receive an email and notification that will allow them to accept the invitation to join the organization. ## Team members ### Joining teams After being invited to a team, you will receive an email with a link that you may use to accept an invitation. A notification will also be visible in the notification center. ### Leaving teams You can leave a team that you are a member of by visiting the team dashboard and clicking the "Leave" button next to the team's name.