diff --git a/sites/upsun/config/_default/params.yaml b/sites/upsun/config/_default/params.yaml index 10f7f78576..efb94ded87 100644 --- a/sites/upsun/config/_default/params.yaml +++ b/sites/upsun/config/_default/params.yaml @@ -35,6 +35,7 @@ vendor: services: .upsun/config.yaml app: .upsun/config.yaml apps: .upsun/config.yaml + env: .environment prefix: apps: applications services: services diff --git a/sites/upsun/src/get-started/stacks/laravel.md b/sites/upsun/src/get-started/stacks/laravel.md deleted file mode 100644 index 1601c1bcea..0000000000 --- a/sites/upsun/src/get-started/stacks/laravel.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Deploying Laravel on Upsun -sidebarTitle: Laravel -sectionBefore: PHP -weight: -70 -description: | - Welcome to the Upsun documentation specific to the Laravel framework on Upsun. - It includes common reference materials useful for deploying Laravel, but also external community and blog resources that cover more advanced topics relevant for the framework. ---- - -{{< note title="Hello, there!" theme="info" >}} - -{{% description %}} - -Before you proceed, be sure to checkout the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/get-started/here/_index.md). These two resources provide all of the core concepts and common commands you'll need to know before using the materials below. - -{{< /note >}} - -## Getting started - -- [Upsun demo application](https://console.upsun.com/projects/create-project) -- [Upsun Getting started guide](/get-started/here/_index.md) -- [What is Upsun?](/learn/overview) - -## Documentation - -- [PHP documentation](/languages/php/) -- [Extensions](/languages/php/extensions) -- [Performance tuning](/languages/php/tuning) -- [PHP-FPM sizing](/languages/php/fpm) -- [Swoole on Upsun](/languages/php/swoole) -- [Authenticated Composer](/languages/php/composer-auth) - -## Community content - -- [Laravel topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=laravel) -- [PHP topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=php) - -## Blogs - -- [Upsun: the missing PaaS to scale Laravel applications](https://upsun.com/blog/paas-to-scale-laravel-apps/) - - diff --git a/sites/upsun/src/get-started/stacks/laravel/_index.md b/sites/upsun/src/get-started/stacks/laravel/_index.md new file mode 100644 index 0000000000..7e55a06b10 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/_index.md @@ -0,0 +1,48 @@ +--- +title: Deploying Laravel on Upsun +sidebarTitle: Laravel +sectionBefore: PHP +layout: single +weight: -65 +description: | + Complete the last required steps to successfully deploy Laravel on {{% vendor/name %}}. +--- + +{{< note theme="info" >}} + +Before you start, check out the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project) and the main [Getting started guide](/get-started/here/_index.md). +They provide all of the core concepts and common commands you need to know before using the materials below. + +{{< /note >}} + +{{< get-started/steps >}} + +## Further resources + +### Documentation + +- [PHP documentation](/languages/php/) + +- [Extensions](/languages/php/extensions) + +- [Performance tuning](/languages/php/tuning) + +- [PHP-FPM sizing](/languages/php/fpm) + +- [Swoole on {{% vendor/name %}}](/languages/php/swoole) + +- [Authenticated Composer](/languages/php/composer-auth) + +### Community content + +- [Laravel topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=laravel) + +- [PHP topics](https://support.platform.sh/hc/en-us/search?utf8=%E2%9C%93&query=php) + +### Blogs + +- [_Upsun: the missing PaaS to scale Laravel applications_](https://upsun.com/blog/paas-to-scale-laravel-apps/) + + + +{{< guide-buttons next="Get started" nextLink="/get-started/stacks/laravel/get-started.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/blackfire.md b/sites/upsun/src/get-started/stacks/laravel/blackfire.md new file mode 100644 index 0000000000..20f6f43365 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/blackfire.md @@ -0,0 +1,23 @@ +--- +title: "Continous Observability with Blackfire" +sidebarTitle: "Blackfire" +weight: -90 +description: Set up a continuous observability strategy for your Laravel app with Blackfire. +--- + +[Blackfire.io](/increase-observability/application-metrics/blackfire.md) is the recommended solution +for monitoring and profiling web sites and apps. +Blackfire works seamlessly with any app built with Laravel. + +Blackfire PHP SDK provides the following [integrations with +Laravel](https://docs.blackfire.io/php/integrations/laravel/index): + +- [Laravel Artisan](https://docs.blackfire.io/php/integrations/laravel/artisan) +- [Laravel Horizon and queue services](https://docs.blackfire.io/php/integrations/laravel/horizon) +- [Laravel Tests](https://docs.blackfire.io/php/integrations/laravel/tests) +- [Laravel Octane](https://docs.blackfire.io/php/integrations/laravel/octane) + +Please refer to the [Blackfire documentation](https://docs.blackfire.io/testing-cookbooks/tests#the-code-blackfire-yaml-code-file) to set up a `.blackfire.yml` configuration to enable custom [performance tests](https://docs.blackfire.io/testing-cookbooks/index) +and automated [builds](https://docs.blackfire.io/builds-cookbooks/index). + +{{< guide-buttons previous="Back" next="Debug with Telescope" nextLink="/get-started/stacks/laravel/laravel-telescope.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/crons.md b/sites/upsun/src/get-started/stacks/laravel/crons.md new file mode 100644 index 0000000000..59eeadeda7 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/crons.md @@ -0,0 +1,76 @@ +--- +title: "Set up cron jobs" +weight: -105 +description: | + Understand how to configure Laravel cron jobs. +--- + +Cron jobs allow you to run scheduled tasks at specified times or intervals. + +While you can run your own custom tasks, Laravel provides a scheduler to simplify the implementation. +To implement it, see the Laravel [Task Scheduling documentation](https://laravel.com/docs/master/scheduling). + +## Set up a cron job + +To set up a cron job, update your {{% vendor/name %}} configuration as follows: + +```yaml {configFile="app"} +applications: + myapp: + [...] + crons: + snapshot: + spec: * * * * * + cmd: | + php artisan schedule:run >> /dev/null 2>&1 +``` + +## Run cron jobs based on environment type + +To run a command in a cron hook for specific environment types, +use the `PLATFORM_ENVIRONMENT_TYPE` environment variable: + +```yaml {configFile="app"} +applications: + myapp: + [...] + crons: + snapshot: + spec: 0 5 * * * + cmd: | + # only run for the production environment, aka main branch + if [ "$PLATFORM_ENVIRONMENT_TYPE" = "production" ]; then + php artisan schedule:run >> /dev/null 2>&1 + fi +``` + +## Run the Laravel scheduler every minute + +Cron job execution on the default {{< vendor/name >}} offering are limited to once every 5 minutes. +For more information, see the [documentation on crons](/create-apps/app-reference.html#crons). + +However, you can add a [worker](/create-apps/app-reference#workers) +and specify a start command that [runs the scheduler every minute](https://laravel.com/docs/11.x/scheduling#running-the-scheduler-locally). +To do so, use the following configuration: + +```yaml {configFile="app"} +applications: + [...] + {{< variable "APP_NAME" >}}: + [...] + workers: + scheduler: + commands: + start: | + php artisan schedule:work +``` + +{{< note title="Warning" theme="warning" >}} + +Web and worker containers don't share mount targets. +You can't share files between those containers using the filesystem. +To share data between containers, use [services](/add-services/_index.md). + +{{< /note >}} + +{{< guide-buttons previous="Back" next="Manage observability with Blackfire" nextLink="/get-started/stacks/laravel/blackfire.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/environment-variables.md b/sites/upsun/src/get-started/stacks/laravel/environment-variables.md new file mode 100644 index 0000000000..0de9ac3f82 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/environment-variables.md @@ -0,0 +1,251 @@ +--- +title: "Environment Variables" +weight: -120 +description: | + Learn about the environment variables added by the {{% vendor/name %}} CLI. +--- + +By default, {{% vendor/name %}} exposes some [environment variables](/development/variables/use-variables#use-provided-variables). + +Laravel relies heavily on environment variables to configure application services (such as the database or the mailer). +Therefore, the default configuration generated by `{{% vendor/cli %}} project:init` includes +the [environment variables for all the services](#service-environment-variables) connected to your app in the `.environment` file. + +{{< note title="Tip" theme="info" >}} + +You can tweak the `.environment` configuration to fit your needs and add specific project-level variables.
+You may need a variable to change per environment. If so, use the `{{% vendor/cli %}} variable` command to add all the needed per-environment variables. + +{{< /note >}} + +## Default environment variables + +{{% vendor/name %}} automatically exposes [environment variables](/development/variables/use-variables#use-provided-variables) +about the app and its infrastructure. + +Assuming that MySQL, PostgreSQL, and Redis services have been added to your environment, +and that the app has been granted access to those services via the following [relationships](/create-apps/app-reference.md#relationships): + +```yaml {location=".upsun/config.yaml"} +applications: + myapp: + ... + relationships: + mysql: ... + postgresql: ... + redis: ... +``` + +You can transpose these variables to set up Laravel's default configuration in a `.environment` file: + +```bash {configFile="env"} +# Set MySQL database environment variables +export DB_HOST="$MYSQL_HOST" +export DB_PORT="$MYSQL_PORT" +export DB_PATH="$MYSQL_PATH" +export DB_USERNAME="$MYSQL_USERNAME" +export DB_PASSWORD="$MYSQL_PASSWORD" +export DB_SCHEME="$MYSQL_SCHEME" +export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}" + +# Or for PostgreSQL +export DB_HOST="$POSTGRESQL_HOST" +export DB_PORT="$POSTGRESQL_PORT" +export DB_PATH="$POSTGRESQL_PATH" +export DB_USERNAME="$POSTGRESQL_USERNAME" +export DB_PASSWORD="$POSTGRESQL_PASSWORD" +export DB_SCHEME="$POSTGRESQL_SCHEME" +export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}" + +# Set Laravel-specific environment variables +export DB_CONNECTION="$DB_SCHEME" +export DB_DATABASE="$DB_PATH" + +# Set Cache environment variables +export CACHE_HOST="$REDIS_HOST" +export CACHE_PORT="$REDIS_PORT" +export CACHE_SCHEME="$REDIS_SCHEME" +export CACHE_URL="${CACHE_SCHEME}://${CACHE_HOST}:${CACHE_PORT}" + +# Set Redis environment variables +export REDIS_URL="$CACHE_URL" +``` + +## Service environment variables + +Each exposed environment variable is prefixed by the relationship name. +For example, if you have the following relationships in your configuration: + +```yaml {configFile="app"} +relationships: + database: "securitydb:postgresql" +``` + +The environment variables for the database service is prefixed by `DATABASE_`, +which is the upper-cased version of the key defined in the relationship. +For example, you could have a `DATABASE_URL` environment variable. + +{{< note theme="warning" >}} + +Environment variables aren't exposed when the build hook script is running, +as services aren't available during the [build process](/learn/overview/build-deploy.md#the-build).
+To add specific variables available during the build, run `{{% vendor/cli %}} variable:create`. + +{{< /note >}} + +### Emails + +{{% vendor/name %}} provides a SMTP service for sending emails. +To configure email in Laravel, add the following mapping to your `.environment` file: + +```bash {configFile="env"} +# Email +export MAIL_MAILER="smtp" +export MAIL_HOST="${PLATFORM_SMTP_HOST}" +export MAIL_PORT="25" +``` + +### HTTP + +If your project has multiple apps, +the configuration is exposed via the following environment variables +(where `SOME_SERVICE` is the upper-cased version of the key defined in the relationship): + +- `SOME_SERVICE_URL`: The full URL of the service +- `SOME_SERVICE_IP`: The HTTP service IP +- `SOME_SERVICE_PORT`: The HTTP service port +- `SOME_SERVICE_SCHEME`: The HTTP service scheme +- `SOME_SERVICE_HOST`: The HTTP service host + +### MySQL/MariaDB + +The [MySQL/MariaDB](/add-services/mysql) configuration is exposed via the following environment variables +(where `DATABASE` is the upper-cased version of the key defined in the relationship above): + +- `DATABASE_URL`: The database URL (in PHP or Go format depending on your app) +- `DATABASE_SERVER`: The database server +- `DATABASE_DRIVER`: The database driver +- `DATABASE_VERSION`: The database version +- `DATABASE_HOST`: The database host +- `DATABASE_PORT`: The database port +- `DATABASE_NAME`: The database name +- `DATABASE_DATABASE`: Alias for `DATABASE_NAME` +- `DATABASE_USERNAME`: The database username +- `DATABASE_PASSWORD`: The database password + +{{< note title="Tip">}} + +The database version and a default charset are included in the database URL. +To override them, use the `DATABASE_VERSION` and `DATABASE_CHARSET` environment variables respectively. + +{{< /note >}} + +### PostgreSQL + +The [PostgreSQL](/add-services/postgresql) configuration is exposed via the following environment variables +(where `DATABASE` is the upper-cased version of the key defined in the relationship): + +- `DATABASE_URL`: The database URL (in PHP or Go format depending on your app) +- `DATABASE_SERVER`: The database server +- `DATABASE_DRIVER`: The database driver +- `DATABASE_VERSION`: The database version +- `DATABASE_HOST`: The database host +- `DATABASE_PORT`: The database port +- `DATABASE_NAME`: The database name +- `DATABASE_DATABASE`: Alias for `DATABASE_NAME` +- `DATABASE_USERNAME`: The database username +- `DATABASE_PASSWORD`: The database password + +{{< note title="Tip">}} + +The database version and a default charset are included in the database URL. +To override them, use the `DATABASE_VERSION` and `DATABASE_CHARSET` environment variables respectively. + +{{< /note >}} + +### Redis + +The [Redis](/add-services/redis) configuration is exposed via the following environment variables +(where `REDIS` is the upper-cased version of the key defined in the relationship): + +- `REDIS_URL`: The Redis URL +- `REDIS_HOST`: The Redis host +- `REDIS_PORT`: The Redis port +- `REDIS_SCHEME`: The Redis scheme + +You can specify the Redis client in your `.environment` file: + +```bash {configFile="env"} +export REDIS_CLIENT="phpredis" +``` + +### Memcached + +The [Memcached](/add-services/memcached) configuration is exposed via the following environment variables +(where `CACHE` is the upper-cased version of the key defined in the relationship): + +- `CACHE_HOST` +- `CACHE_PORT` +- `CACHE_IP` + +### Elasticsearch + +The [Elasticsearch](/add-services/elasticsearch) configuration is exposed via the following environment variables +(where `ELASTICSEARCH` is the upper-cased version of the key defined in the relationship): + +- `ELASTICSEARCH_URL`: The full URL of the Elasticsearch service +- `ELASTICSEARCH_HOST`: The Elasticsearch host +- `ELASTICSEARCH_PORT`: The Elasticsearch port +- `ELASTICSEARCH_SCHEME`: The Elasticsearch protocol scheme (`http` or `https`) + +### RabbitMQ + +The [RabbitMQ](/add-services/rabbitmq) configuration is exposed via the following environment variables +(where `RABBITMQ` is the upper-cased version of the key defined in the relationship): + +- `RABBITMQ_URL`: The RabbitMQ standardized URL +- `RABBITMQ_SERVER`: The RabbitMQ server +- `RABBITMQ_HOST`: The RabbitMQ host +- `RABBITMQ_PORT`: The RabbitMQ port +- `RABBITMQ_SCHEME`: The RabbitMQ scheme +- `RABBITMQ_USER`: The RabbitMQ username +- `RABBITMQ_USERNAME`: The RabbitMQ username +- `RABBITMQ_PASSWORD`: The RabbitMQ password + +### MongoDB + +The [MongoDB](/add-services/mongodb) configuration is exposed via the following environment variables +(where `MONGODB` is the upper-cased version of the key defined in the relationship): + +- `MONGODB_SERVER` +- `MONGODB_HOST` +- `MONGODB_PORT` +- `MONGODB_SCHEME` +- `MONGODB_NAME` +- `MONGODB_DATABASE` +- `MONGODB_USER` +- `MONGODB_USERNAME` +- `MONGODB_PASSWORD` + +### InfluxDB + +The [InfluxDB](/add-services/influxdb) configuration is exposed via the following environment variables +(where `TIMEDB` is the upper-cased version of the key defined in the relationship): + +- `TIMEDB_SCHEME` +- `TIMEDB_HOST` +- `TIMEDB_PORT` +- `TIMEDB_IP` + +### Kafka + +The [Apache Kafka](/add-services/kafka) configuration is exposed via the following environment variables +(where `KAFKA` is the upper-cased version of the key defined in the relationship): + +- `KAFKA_URL` +- `KAFKA_SCHEME` +- `KAFKA_HOST` +- `KAFKA_PORT` +- `KAFKA_IP` + +{{< guide-buttons previous="Back" next="Set up Redis" nextLink="/get-started/stacks/laravel/setup-redis.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/faq.md b/sites/upsun/src/get-started/stacks/laravel/faq.md new file mode 100644 index 0000000000..58c48c2ffc --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/faq.md @@ -0,0 +1,97 @@ +--- +title: "FAQ" +weight: 200 +description: | + Troubleshoot issue you might encounter using [Laravel](https://laravel.com/), a PHP framework on {{% vendor/name %}}. +--- + +## How can I access my application logs? + +To display the application log file (`app` file), run the following command: + +```bash +{{% vendor/cli %}} log app --tail +``` + +All the log messages generated by your app are sent to this `app` file. +This includes language errors such as PHP errors, warnings, notices, +as well as uncaught exceptions. + +The file also contains your application logs if you log on `stderr`. +This log doesn't include the default `laravel.log` located in `/storage`. + +{{% note %}} + +{{% vendor/name %}} manages the `app` file for you. +This is to prevent disks from getting filled and using very fast local drives instead of slower network disks. +Make sure your apps always output their logs to `stderr`. + +{{% /note %}} + +With Laravel, you can change your logging configuration to use `memory` and stream `php://stderr`. +In your `config/logging.php` file, add or update the following configuration: + +```php {location="config/logging.php"} +'memory' => [ + 'driver' => 'monolog', + 'handler' => Monolog\Handler\StreamHandler::class, + 'with' => [ + 'stream' => 'php://stderr', + ], + 'processors' => [ + // Simple syntax... + Monolog\Processor\MemoryUsageProcessor::class, + + // With options... + [ + 'processor' => Monolog\Processor\PsrLogMessageProcessor::class, + 'with' => ['removeUsedContextFields' => true], + ], + ], +], +``` + +{{< note theme="warning" title="Warning">}} + +If you log deprecations, make sure you **also** log them on `stderr`. + +{{< /note >}} + +## What's this "`Oops! An Error Occurred`" message about? + +The `Oops! An Error Occurred` message comes from your app and is automatically generated based on the Laravel error template. + +### The server returned a "`500 Internal Server Error`" + +If your app's working as expected locally but you see the previous error message on {{% vendor/name %}}, +it usually means you have a configuration error or a missing dependency. + +To fix this issue, search your application logs. +They likely contain an error message describing the root cause: + +```bash +{{% vendor/cli %}} logs all + [app] [14-Aug-2020 10:52:27 UTC] [critical] Uncaught PHP Exception Exception: [...] + [app] + [php.access] 2020-08-14T10:52:27Z GET 500 2.386 ms 2048 kB 419.11% / + [access] 78.247.136.119 - - [14/Aug/2020:10:52:27 +0000] "GET / HTTP/1.1" 500 843 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36" +``` + +If the error occurs on a preview environment, +or on the main environment of a non-production project, +you can also enable Laravel's dev/debug mode to inspect the cause of the error +via the `APP_DEBUG` [environment variable](./environment-variables.md) in your +`.environment` file or via [{{% vendor/cli %}} console](/development/variables): + +```bash +# Enable debug mode +export APP_DEBUG=1 +# Disable debug mode +export APP_DEBUG=0 +``` + +## Other issues + +For other issues unrelated to Laravel, see [Troubleshoot development](/development/troubleshoot.html). + +{{< guide-buttons previous="Back" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/get-started.md b/sites/upsun/src/get-started/stacks/laravel/get-started.md new file mode 100644 index 0000000000..7f45387e60 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/get-started.md @@ -0,0 +1,198 @@ +--- +title: Get started +weight: -255 +description: | + See how to get started deploying Laravel on {{% vendor/name %}}. +--- + +This guide provides instructions for deploying and working with Laravel on {{% vendor/name %}}. + +{{% guides/requirements name="Laravel" %}} + +## 1. Create your Laravel app + +1. To create a new Laravel project, run the following commands: + + ```bash {location="Terminal"} + composer create-project laravel/laravel:^11.0 {{< variable "PROJECT_NAME" >}} + cd {{< variable "PROJECT_NAME" >}} + git init . + ``` + + Alternatively, you can deploy an **existing Laravel project**. To do so, `cd` into your Laravel repository root folder. + +2. To generate a sensible default {{% vendor/name %}} configuration, + run the following command from within the project's directory: + + ```bash {location="Terminal"} + {{% vendor/cli %}} project:init + ``` + + The {{% vendor/name %}} CLI detects a PHP & Laravel stack. + Follow the prompts to specify a name for your project and select the needed services. + While optional, it is recommended to add [Redis](/add-services/redis.md) to your project to handle Laravel cache, queues & sessions. + + The `{{< vendor/configfile "app" >}}` and `.environment` configuration files are generated. + +3. Enable the PHP extensions required by the services you selected.
+ For example, `pdo_mysql` is enabled by default, but you may need to enable others like `redis` or `pdo_pgsql`: + + ```yaml {configFile="app"} + applications: + myapp: + ... + runtime: + extensions: + - redis + - pdo_pgsql + ``` + See all the [available PHP extensions](/languages/php/extensions.html). + +3. Laravel requires an [encryption key](https://laravel.com/docs/master/encryption#gracefully-rotating-encryption-keys).
+ To generate the key locally, run `php artisan key:generate`. + Copy the key from your local `.env` file into `.environment` as follows: + + ```bash {configFile="env"} + export APP_KEY="base64:{{< variable "APP_KEY" >}}" + ``` + +4. Add and commit your changes: + + ```bash {location="Terminal"} + git add {{< vendor/configfile "app" >}} .environment + git commit -m "Add {{% vendor/name %}} configuration" + ``` + +## 2. Create your {{% vendor/name %}} project + +To create a project on {{% vendor/name %}}, run the following command from within the project's directory: + +```bash {location="Terminal"} +{{% vendor/cli %}} project:create --title {{< variable "PROJECT_TITLE" >}} --set-remote +``` + +The `--set-remote` flag sets the new project as the remote for this repository. + +{{< note title="Tip" >}} + +You can link any repository to an existing {{% vendor/name %}} project using the following command: + +```bash {location="Terminal"} +{{% vendor/cli %}} project:set-remote {{< variable "PROJECT_ID" >}} +``` + +{{< /note >}} + +## 3. Deploy your project + +To deploy your project, run the following command: + +```bash {location="Terminal"} +{{% vendor/cli %}} push +``` + +During deployment, the logs from the {{% vendor/name %}} API are displayed in your terminal so you can monitor progress. +To stop the display of the logs **without interrupting the deployment**, +use `CTRL+C` in your terminal. +To go back to displaying the logs, run `{{% vendor/cli %}} activity:log`. + +Congratulations, your first Laravel app has been deployed on {{% vendor/name %}}! + +{{< note title="Tip" theme="info" >}} + +Now that your app is deployed in production mode, +you can [set up a custom domain](http://localhost:53846/domains/steps.html). +{{< /note >}} + +## 4. Configure write access + +The {{% vendor/name %}} default configuration stipulates three writable folders in `{{< vendor/configfile "app" >}}`: + +- `"/.config"` +- `"bootstrap/cache"` +- `"storage"` + +If your application writes content outside of these default ones, +you can [set up mounts](/create-apps/app-reference.html#mounts). + +## 5. Make changes to your project + +Now that your project is deployed, you can start making changes to it. +For example, you might want to fix a bug or add a new feature. + +In your project, the main branch always represents the production environment. +Other branches are for developing new features, fixing bugs, or updating the infrastructure. + +To make changes to your project, follow these steps: + +1. Create a new environment (a Git branch) to make changes without impacting production: + + ```bash {location="Terminal"} + {{% vendor/cli %}} branch feat-a + ``` + + This command creates a new local `feat-a` Git branch based on the main Git branch, + and activates a related environment on {{% vendor/name %}}. + The new environment inherits the data (service data and assets) of its parent environment (the production environment here). + +2. Make changes to your project. + + For example, edit the `resources/views/welcome.blade.php` template and make the following visual changes: + + ```html {location="resources/views/welcome.blade.php"} + + - Laravel + + Laravel On {{% vendor/name %}} + + ``` + +3. Add and commit your changes: + + ```bash {location="Terminal"} + add . + git commit -a -m "Update title" + ``` + +4. Deploy your changes to the `feat-a` environment: + + ```bash {location="Terminal"} + {{% vendor/cli %}} deploy + ``` + + Note that each environment has its own domain name. + To view the domain name of your new environment, run the following command: + + ```bash {location="Terminal"} + {{% vendor/cli %}} url --primary + ``` + +5. Iterate by changing the code, committing, and deploying. + When satisfied with your changes, merge them to the main branch, deploy, + and remove the feature branch: + + ```bash {location="Terminal"} + git checkout main + git merge feat-a + {{% vendor/cli %}} environment:delete feat-a + git branch -d feat-a + {{% vendor/cli %}} deploy + ``` + + Note that deploying to production is fast because the image built for the `feat-a` environment is reused. + + For a long running branch, keep the code up-to-date with the main branch by using `git merge main` or `git rebase main`. + Also, keep the data in sync with the production environment by using `{{% vendor/cli %}} env:sync`. + +## 6. Optional: Use a third-party Git provider + +When you choose to use a third-party Git hosting service, +the {{% vendor/name %}} Git repository becomes a read-only mirror of the third-party repository. +All your changes take place in the third-party repository. + +Add an integration to your existing third-party repository: + +- [BitBucket](/integrations/source/bitbucket.md) +- [GitHub](/integrations/source/github.md) +- [GitLab](/integrations/source/gitlab.md) + +{{< guide-buttons previous="Back" next="Environment variables" nextLink="/get-started/stacks/laravel/environment-variables.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/laravel-horizon.md b/sites/upsun/src/get-started/stacks/laravel/laravel-horizon.md new file mode 100644 index 0000000000..81a69a138b --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/laravel-horizon.md @@ -0,0 +1,96 @@ +--- +title: "Handle queues with Horizon" +weight: -118 +description: | + Setting up Laravel Horizon +--- + +[Laravel Horizon](https://laravel.com/docs/master/horizon#main-content) provides an appealing dashboard and code-driven configuration +for your Laravel powered Redis queues. +Horizon allows you to easily monitor key metrics of your queue system, +such as job throughput, runtime, and job failures. + +## 1. Add Laravel Horizon + +{{% note theme="warning" %}} +This procedure assumes you have followed the steps on [how to configure Redis and queues](./setup-redis.html#using-redis-for-laravel-queues). +{{% /note %}} + +1. To add Laravel Horizon, run the following command: + + ```bash {location="Terminal"} + composer require laravel/horizon && php artisan horizon:install + ``` + +2. Add the `install` command to your `build` hook in your app configuration, so it's run on every deploy. + + ```yaml {configFile="app"} + applications: + myapp: + [...] + hooks: + build: | + set -eux + composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader --no-dev + php artisan horizon:install + ``` + +## 2. Create a worker to run Horizon + +To run Horizon on your project, you need to add a separate [worker](/create-apps/app-reference#workers). +To do so, use the following configuration: + +```yaml {configFile="app"} +applications: + [...] + {{< variable "APP_NAME" >}}: + [...] + workers: + horizon: + commands: + start: | + php artisan horizon +``` + +To enable the worker, push your changes to {{< vendor/name >}}: + +```bash {location="Terminal"} +git add . +git commit -m "Enable Laravel Horizon" +{{< vendor/cli >}} push +``` + +A new container is started automatically. +It will spawn the Horizon process after the next deploy. + +## 3. Access your Horizon dashboard + +If you have restricted access to Horizon in your `HorizonServiceProvider.php`, +log in to your app through the web. +Then, go to `/horizon` to access your Horizon dashboard. + +![Laravel Horizon Dashboard](/images/guides/laravel/horizon-dashboard.png "0.5") + +## 4. Optional: Customize Horizon + +Horizon handles jobs that are populated by the queue. +If you need to customize how Horizon works (queues, processes, etc.), +see the official [Laravel Horizon documentation](https://laravel.com/docs/master/horizon#main-content). + +{{< note title="Warning" theme="warning" >}} + +Web and worker containers don't share mount targets. +You can't share files between those containers using the filesystem. +To share data between containers, use [services](/add-services/_index.md). + +See more information on [workers](/create-apps/app-reference#workers). + +{{< /note >}} + +Note that you can customize the resources of your Horizon worker container from the {{% vendor/name %}} Console. + +![Laravel Horizon Resources](/images/guides/laravel/horizon-resources.png "0.5") + +For more information, see how to [configure resources](/manage-resources/adjust-resources.md). + +{{< guide-buttons previous="Back" next="Set up cron jobs" nextLink="/get-started/stacks/laravel/crons.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/laravel-telescope.md b/sites/upsun/src/get-started/stacks/laravel/laravel-telescope.md new file mode 100644 index 0000000000..d4d1208979 --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/laravel-telescope.md @@ -0,0 +1,77 @@ +--- +title: "Debug with Laravel Telescope" +weight: -87 +description: | + Setting up Laravel Telescope for debugging Laravel +--- + +Laravel Telescope complements your local Laravel development environment. +With Telescope, get insight into the requests coming into your app, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps, and more. + +To set up Laravel Telescope on your **non-production** environments, +follow these steps. + +## 1. Create the APP_DEBUG variable + +To add the `APP_DEBUG` & `TELESCOPE_ENABLED` variables on your project, run the following commands: + +```bash {location="Terminal"} +{{< vendor/cli >}} variable:create --level environment --name env:APP_DEBUG --value false +{{< vendor/cli >}} variable:create --level environment --name env:TELESCOPE_ENABLED --value false +``` + +Note that the default values for your main environment are set to `false`. +To override them on other non-production environments, run the following commands: + +```bash {location="Terminal"} +{{< vendor/cli >}} variable:update -e {{< variable "ENVIRONMENT" >}} --value true env:APP_DEBUG +{{< vendor/cli >}} variable:update -e {{< variable "ENVIRONMENT" >}} --value true env:TELESCOPE_ENABLED +``` + +## 2. Add Telescope to your project + +1. Run the following Composer command: + + ```bash {location="Terminal"} + composer require laravel/telescope && php artisan telescope:install + ``` + +2. Add the `install` command to your `build` hook in your app configuration, + so it's run on every deploy. + + ```yaml {configFile="app"} + applications: + myapp: + [...] + hooks: + build: | + set -eux + composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader --no-dev + php artisan telescope:install + ``` + +For more options and information on how to manage authentication for the dashboard, +see the [Laravel Telecope documentation](https://laravel.com/docs/master/telescope#installation). + +## 3. Deploy the new release + +To enable Telescope, push your changes to {{% vendor/name %}}: + +```bash {location="Terminal"} +git add . +git commit -m "Enable Laravel Horizon" +{{< vendor/cli >}} push +``` + +You can now access the `/telescope` endpoint of your app. + +![Laravel Horizon Dashboard](/images/guides/laravel/telescope-dashboard.png "0.5") + +{{< note theme="tip" >}} + +Telescope uses a gate defined in `TelescopeServiceProvider.php` to authorize access to the dashboard. +Check that the logic here matches your needs. + +{{< /note >}} + +{{< guide-buttons previous="Back" next="FAQ" nextLink="/get-started/stacks/laravel/faq.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/laravel/setup-redis.md b/sites/upsun/src/get-started/stacks/laravel/setup-redis.md new file mode 100644 index 0000000000..114280874a --- /dev/null +++ b/sites/upsun/src/get-started/stacks/laravel/setup-redis.md @@ -0,0 +1,97 @@ +--- +title: "Set up Redis" +weight: -119 +description: | + Setting up Redis for cache, sessions & queues +--- + +With Laravel, you can use Redis to handle session storage, cache storage, and queues. + +## 1. Add the Redis service + +1. [Add the service](/add-services.md#add-a-service) to your app configuration using the `services` top-level key: + + ```yaml {configFile="app"} + services: + [...] + redis: + type: redis:7.0 + ``` + +2. To connect the service to your app, add the following relationship: + + ```yaml {configFile="app"} + applications: + myapp: + [...] + relationships: + redis: "redis:redis" + + services: + [...] + redis: + type: redis:7.0 + ``` + +## 2. Configure your Redis service + +The [Redis](/add-services/redis) configuration is exposed via the following environment variables +(where `REDIS` is the upper-cased version of the key defined in the relationship): + +- `REDIS_URL`: The Redis URL +- `REDIS_HOST`: The Redis host +- `REDIS_PORT`: The Redis port +- `REDIS_SCHEME`: The Redis scheme + +If the relationship is named `redis`, Laravel automatically detects these variables and configure its own Redis driver the right way. +If not, you can map the variables in the `.environment` file. + +You can specify the Redis client in your `.environment` file: + +```bash {configFile="env"} +export REDIS_CLIENT="phpredis" +``` + +{{< note theme="warning" >}} + +If using `phpredis`, make sure you add `redis` in the list of PHP `runtime` extensions in your `{{< vendor/configfile "app" >}}`: + +```yaml {configFile="app"} +applications: + myapp: + [...] + runtime: + extensions: + - redis +``` + +{{< /note >}} + +## 3. Store the Laravel cache in Redis + +To enable cache storage in Redis, add the following environment variable to your `.environment` file: + +```bash {configFile="env"} +export CACHE_STORE="redis" +``` + +## 4. Store Laravel sessions in Redis + +Laravel relies on the `SESSION_DRIVER` variable to store sessions. Therefore, add the following environment variable to your `.environment` file: + +```bash {configFile="env"} +export SESSION_DRIVER="redis" +``` + +## 5. Use Redis for Laravel queues + +For a basic queueing system, configure the `QUEUE_CONNECTION` in your `.environment` file as follows: + +```bash {configFile="env"} +export QUEUE_CONNECTION="redis" +``` + +For more information, see the [Laravel Queues documentation](https://laravel.com/docs/master/queues) +and {{% vendor/name %}}'s [Horizon configuration page](./laravel-horizon). + +{{< guide-buttons previous="Back" next="Handle queues with Horizon" nextLink="/get-started/stacks/laravel/laravel-horizon.md" type="*" >}} \ No newline at end of file diff --git a/sites/upsun/src/get-started/stacks/symfony/_index.md b/sites/upsun/src/get-started/stacks/symfony/_index.md index 9d335d990f..90537626b1 100644 --- a/sites/upsun/src/get-started/stacks/symfony/_index.md +++ b/sites/upsun/src/get-started/stacks/symfony/_index.md @@ -2,7 +2,7 @@ title: Deploying Symfony on Upsun sidebarTitle: Symfony layout: single -weight: -65 +weight: -60 description: | Welcome to the Upsun documentation specific to the [Symfony](https://www.symfony.com/) framework on Upsun. It includes common reference materials useful for deploying Symfony, but also external community and blog resources that cover more advanced topics relevant for the framework. diff --git a/sites/upsun/src/languages/php/_index.md b/sites/upsun/src/languages/php/_index.md index 115cb88eb8..8fe64653e0 100644 --- a/sites/upsun/src/languages/php/_index.md +++ b/sites/upsun/src/languages/php/_index.md @@ -620,5 +620,5 @@ applications: All major PHP web frameworks can be deployed on {{% vendor/name %}}. See dedicated guides for deploying and working with them: -- [Laravel](/get-started/stacks/laravel.md) +- [Laravel](/get-started/stacks/laravel) - [Symfony](/get-started/stacks/symfony/_index.md) diff --git a/sites/upsun/static/images/guides/laravel/horizon-dashboard.png b/sites/upsun/static/images/guides/laravel/horizon-dashboard.png new file mode 100644 index 0000000000..7a42861533 Binary files /dev/null and b/sites/upsun/static/images/guides/laravel/horizon-dashboard.png differ diff --git a/sites/upsun/static/images/guides/laravel/horizon-resources.png b/sites/upsun/static/images/guides/laravel/horizon-resources.png new file mode 100644 index 0000000000..7ba06b38be Binary files /dev/null and b/sites/upsun/static/images/guides/laravel/horizon-resources.png differ diff --git a/sites/upsun/static/images/guides/laravel/telescope-dashboard.png b/sites/upsun/static/images/guides/laravel/telescope-dashboard.png new file mode 100644 index 0000000000..a2e303236d Binary files /dev/null and b/sites/upsun/static/images/guides/laravel/telescope-dashboard.png differ