diff --git a/apps/docs/content/frameworks/laravel.mdx b/apps/docs/content/frameworks/laravel.mdx index 42f11fdc..bdf8bdd6 100644 --- a/apps/docs/content/frameworks/laravel.mdx +++ b/apps/docs/content/frameworks/laravel.mdx @@ -1,414 +1,178 @@ ---- -title: Laravel -description: Laravel ---- - -import DocCardList from '@theme/DocCardList'; -import Icons from '@theme/Icon'; -import LargeCardList from '@site/src/components/LargeCardList'; -import LargeCard from '@site/src/components/LargeCard'; -import CustomCard from '@site/src/components/CustomCard'; +# Laravel on Zerops + import DeployButton from '@site/src/components/DeployButton'; -import { Dropdown, DropdownItem } from '/src/components/Dropdown'; - -[Laravel ↗](https://laravel.com) is a PHP framework for building robust, full-stack web applications. Whether you prefer pure PHP with Livewire or want to use Laravel with React/Vue using Inertia, Laravel provides a complete toolkit for production-ready applications for every developer. - - - This is a full-stack Laravel Jetstream application — an advanced starter kit — preconfigured with everything you need: mailpit for email testing, Valkey (Redis) for session management, object storage for files, and PostgreSQL as your database. - - - - - -## How to Start - - - - - - ------ - -## Laravel Recipes - -We have created some [Laravel recipes](https://github.com/orgs/zeropsio/repositories?q=Laravel) for you to import and get started fast with Laravel on Zerops. - -### Minimal Laravel Recipe - -A minimal setup for a Laravel application that includes a single service for the application and a PostgreSQL database. This basic configuration provides essential features like database migrations, environment variable configuration, and health check implementations, making it suitable for simple applications that need a solid foundation without additional complexity. - - - -```yml -#yamlPreprocessor=on -project: - name: laravel-minimal-devel - tags: - - zerops-recipe - - development +import CustomCardWithIcon from '@site/src/components/CustomCardWithIcon'; +import IconLaravel from '@theme/Icon/Laravel'; +import IconLaravelJetstream from '@theme/Icon/LaravelJetstream'; +import IconFilament from '@theme/Icon/Filament'; +import IconTwill from '@theme/Icon/Twill'; + +> Modern Laravel development demands infrastructure that doesn't get in your way. Zerops provides the foundation that lets you focus on building great apps, not wrestling with environment configuration or resource management. + +## Why Zerops for Laravel? + +Zerops implements what we call "transparent infrastructure" - you get enterprise-grade capabilities with development-friendly ergonomics. This means: + +- **Full system access** across all environments +- **Granular resource control** starting at 0.25GB RAM +- **True environment parity** from local to production +- **Zero-downtime deployments** by default + +*No artificial limitations, no framework-specific compromises - just solid infrastructure that lets Laravel do what it does best.* + +## Quick Start + +Choose a recipe that matches your needs and deploy with a single click. Each recipe sets up a complete environment with all necessary services preconfigured. + +All recipes include: +- **PHP 8.3 + Nginx** +- **PostgreSQL 16** +- **L3/L7 balancers** +- **Logging & metrics** + +
+
+ +
This is the most bare-bones example of Laravel app including core services + PostgreSQL.
+ + + +
+
+ +
This is a full-stack setup including Redis, Object Storage, and Mailpit.
+ + +
+
+ +
Admin panel optimized setup including Redis, Object Storage, and Mailpit.
+ + +
+
+ +
Content management focused setup including Redis, Object Storage, and Mailpit.
+ + +
+
+ +## Core Features + +### Native Service Discovery +Services within your project communicate seamlessly using internal hostnames: + +```php title=".env" +DB_HOST=${db_hostname} +REDIS_HOST=${cache_hostname} +``` + +*Environment variables are automatically injected and synchronized across all containers.* + +### Intelligent Scaling +Resources scale automatically in both directions based on actual usage: +```yaml +# Example scaling configuration services: - hostname: app - type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-minimal - enableSubdomainAccess: true - envSecrets: - APP_KEY: <@generateRandomString(<32>)> - APP_DEBUG: true - APP_ENV: development - - - hostname: db - type: postgresql@16 - mode: NON_HA - priority: 10 + minContainers: 2 + maxContainers: 6 + cpu: + min: 1 + max: 4 + ram: + min: 0.25 + max: 4 ``` - - +### Zero-Downtime Deployments +Deploy with confidence using our battle-tested pipeline: + +```yaml title="zerops.yml" +# zerops.yml +zerops: + - setup: app + build: + base: php@8.3 + buildCommands: + - composer install --no-dev --optimize-autoloader + deployFiles: ./ + cache: vendor + run: + base: php-nginx@8.3 + initCommands: + - php artisan config:cache + - php artisan route:cache + - php artisan migrate --force +``` - - -```yml -#yamlPreprocessor=on -project: - name: laravel-minimal-prod - corePackage: SERIOUS - tags: - - zerops-recipe - - development +### High Availability by Design +Every service can run in HA mode with automatic failover: +```yaml services: - - hostname: app - type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-minimal - enableSubdomainAccess: true - envSecrets: - APP_KEY: <@generateRandomString(<32>)> - APP_DEBUG: true - APP_ENV: development - - hostname: db type: postgresql@16 - mode: NON_HA - priority: 10 + mode: HA # Automatic primary-replica setup + + - hostname: cache + type: valkey@7.2 + mode: HA # Redis cluster configuration ``` - - -:::info -You can find the laravel minimal recipe at [zeropsio/recipe-laravel-minimal](https://github.com/zeropsio/recipe-laravel-minimal) on GitHub with the full [zerops.yml configuration](https://github.com/zeropsio/recipe-laravel-minimal/blob/main/zerops.yml). -::: +## Development Workflow +{/* ### Local Development */} +{/* Connect your local environment directly to remote services: */} -### Laravel Jetstream Recipe +{/* ```bash */} +{/* # Install Zerops CLI */} +{/* npm i -g @zerops/zcli */} -An Advanced Laravel application that includes Jetstream authentication, Redis for cache, queue, and session, Object Storage integration, Team management features, Local email testing with Mailpit, and Asset compilation with Vite. This makes it perfectly suitable for production of any size. +{/* # Login and connect to your project */} +{/* zcli login */} +{/* zcli connect my-laravel-project */} - - -```yml -#yamlPreprocessor=on -project: - name: laravel-jetstream-devel - tags: - - zerops-recipe - - development +{/* # Your local .env now works with remote services */} +{/* php artisan serve */} +{/* ``` */} -services: - - hostname: app - type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-jetstream - enableSubdomainAccess: true - envSecrets: - APP_NAME: ZeropsLaravelJetstreamDev - APP_DEBUG: true - APP_ENV: development - APP_KEY: <@generateRandomString(<32>)> +### Deployment Options +Choose the workflow that fits your team: - - hostname: db - type: postgresql@16 - mode: NON_HA - priority: 10 +1. **GitHub/GitLab Integration** + - Automatic deployments on push/merge + - Branch-specific environments + - Build caching and artifacts - - hostname: redis - type: valkey@7.2 - mode: NON_HA - priority: 10 - - - hostname: storage - type: object-storage - objectStorageSize: 2 - objectStoragePolicy: public-read - priority: 10 - - - hostname: mailpit - type: go@1 - buildFromGit: https://github.com/zeropsio/recipe-mailpit - enableSubdomainAccess: true -``` - - - - - -```yml -#yamlPreprocessor=on -project: - name: laravel-jetstream-prod - corePackage: SERIOUS - tags: - - zerops-recipe - - production +2. **CLI-Driven Pipeline** + ```bash + # Deploy from your terminal + zcli push + ``` -services: - - hostname: app - type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-jetstream - enableSubdomainAccess: true - minContainers: 2 - envSecrets: - APP_NAME: ZeropsLaravelJetstreamProd - APP_DEBUG: false - APP_ENV: production - APP_KEY: <@generateRandomString(<32>)> +3. **Manual Triggers** + - Deploy specific versions + - Roll back to previous states + - Test deployment configurations - - hostname: db - type: postgresql@16 - mode: HA - priority: 10 +{/* ## Next Steps */} - - hostname: redis - type: valkey@7.2 - mode: HA - priority: 10 - - - hostname: storage - type: object-storage - objectStorageSize: 2 - objectStoragePolicy: public-read - priority: 10 -``` - - - -:::info -You can find the laravel jetstream recipe at [zeropsio/recipe-laravel-jetstream](https://github.com/zeropsio/recipe-laravel-jetstream) on GitHub with the full [zerops.yml configuration](https://github.com/zeropsio/recipe-laravel-jetstream/blob/main/zerops.yml). -::: - ---- - - - -{" "} - - - -## When in Doubt, Reach Out - -Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out. - -In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord. - -Have you build something that others might find useful? Don't hesitate to share your knowledge! - - - -## Popular Guides - - +{/* - [Environment Variables & Secrets](/laravel/env-variables) */} +{/* - [Database Migrations](/laravel/migrations) */} +{/* - [Redis Configuration](/laravel/redis) */} +{/* - [SMTP Setup](/laravel/smtp) */} +{/* - [Backup Strategies](/laravel/backups) */} +{/* - [Log Management](/laravel/logging) */} +{/* - [Advanced Scaling](/laravel/scaling) */} + +{/* ## Resources */} + +{/* - [GitHub Example Repository](https://github.com/zeropsio/laravel-example) */} +{/* - [Laravel Recipe Reference](/recipes/laravel) */} +{/* - [CLI Documentation](/cli/overview) */} +{/* - [API Reference](/api/overview) */} + +*Need help? Join our [Discord community](https://discord.gg/zerops) or check out our [getting started guides](/getting-started).* \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/backups.mdx b/apps/docs/content/frameworks/laravel/backups.mdx deleted file mode 100644 index 03d435fd..00000000 --- a/apps/docs/content/frameworks/laravel/backups.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Backups in Your Laravel Project -description: Learn How You Can Work with Backups in Postgres Service on Zerops ---- - -import Image from '/src/components/Image'; - -Zerops automatically handles backups for your Laravel project's PostgreSQL database. This guide explains how backups work and how to manage them effectively. - -

- Laravel PostgreSQL Backups -

- -1. Navigate to your project -2. Go to your PostgreSQL service -3. Go to the "Backups List & Configuration" Pages -4. Here you have multiple options to setup backup frequency like Every monday at midnight, Everyday at midnight, Every Hour, Custom Cron and Disable. -5. You can also manually create a backup and download it. -6. You can also delete old backups. - -## Backup Overview - -Your PostgreSQL database is automatically backed up and stored securely in Zerops' S3 storage. There are some limits to keep in mind: - -### Storage Limits - - - - - - - - - - - - - - - - - - -
PackageStorage Limit
Lightweight Package5 GB
Serious Package25 GB
- -### Retention Policy - - - - - - - - - - - - - - - - - - - - - - -
Policy TypeLimit
Maximum Backups100 per service
Retention Period31 days maximum
Backup ScheduleDaily at midnight UTC
\ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/build-deployments.mdx b/apps/docs/content/frameworks/laravel/build-deployments.mdx deleted file mode 100644 index 443513b9..00000000 --- a/apps/docs/content/frameworks/laravel/build-deployments.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Build & Deployments -description: Learn How to Build and Run Your Laravel Application on Zerops ---- - -Deploying your application to zerops requires a `zerops.yml` file at the root of your project. This file tells Zerops how to install, build, run and deploy your application. - -## Build & Runtime - -You can define commands and settings for both your build and runtime environments in your `zerops.yml` file. - -### Build Environment - -The build environment is the environment where your application is built. It is the environment where your `deployFiles` are deployed and then `buildCommands` are executed on your specified `base` and `os`. - -```yml -zerops: - - setup: app - build: - base: - - php@8.4 - os: alpine - buildCommands: - - composer install --ignore-platform-reqs - deployFiles: ./ - cache: - - vendor - - composer.lock - deploy: - readinessCheck: - httpGet: - port: 80 - path: /up -``` - -### Runtime Environment - -The runtime environment is the environment where your application is running. It is the environment where your built files are deployed. - -```yml - run: - base: php-nginx@8.4 - os: alpine - siteConfigPath: site.conf.tmpl - envVariables: - APP_URL: ${zeropsSubdomain} - DB_CONNECTION: pgsql - DB_DATABASE: db - DB_HOST: db - DB_USERNAME: ${db_user} - DB_PASSWORD: ${db_password} - DB_PORT: 5432 - initCommands: - - php artisan view:cache - - php artisan config:cache - - php artisan route:cache - - sudo -E -u zerops -- zsc execOnce ${appVersionId} -- php artisan migrate --force - - php artisan optimize - healthCheck: - httpGet: - port: 80 - path: /up -``` - -The `zsc execOnce` is a command by Zerops Setup Control (ZSC) CLI tool. This comes pre-installed in all runtime and build containers. -It provides essential container management capabilities, including dynamic scaling, technology stack -modifications, and synchronized command execution. It ensures single-execution of critical commands (such as database migrations) across high-availability -setups. - - -## How to deploy your application? - -To deploy your application, you can either push to the repository or use the Zerops CLI. - -### Deploying from GitHub or GitLab - -To deploy your application from GitHub or GitLab, you need to connect your repository to your Zerops service from the service's Pipeline & CI/CD settings. - -- [Github integration](/references/github-integration) -- [Gitlab integration](/references/gitlab-integration) - -The deployment can be triggered either by: - -- **Pushing to a specified branch**: If you push to a branch, it will trigger a deployment. -- **Using a tag**: If you commit with the configured tag, it will trigger a deployment. - - -### Deploying with Zerops CLI - -When you have a `zerops.yml` file, you can deploy your codebase to Zerops by running `zcli push`. This will trigger the build pipeline followed by deployment. -There are many other features available in the Zerops CLI - you can read more about them at [references/cli](/references/cli). - -Any changes to your `zerops.yml` file require redeployment of your application, either by using `zcli push` or by pushing to your connected repository. - -:::info -While deployments are handled through `zcli push` or repository triggers, you can also access your service directly via SSH. Learn more about SSH access [here](/references/ssh). -::: \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/create-project.mdx b/apps/docs/content/frameworks/laravel/create-project.mdx deleted file mode 100644 index 8cc7d4e0..00000000 --- a/apps/docs/content/frameworks/laravel/create-project.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Create Zerops Project -description: Creating a Zerops Project for Laravel for Development or Production ---- - -import Image from '/src/components/Image'; -import { Dropdown, DropdownItem } from '/src/components/Dropdown'; - -Creating a project in Zerops is the first step to deploying your Laravel application where you can also add different services to use with your Laravel application. - -You can create a project using either the Zerops GUI or [zCLI](/references/cli). - -Create a Zerops project - - -Zerops offers two core packages for Zerops projects: Lightweight for small scale projects and development and Serious for production environments. - -## Small Scale Projects - -For development or small-scale projects, use the Lightweight Core Package. You can create a project by importing the following Yaml: - -```yml -project: - name: laravel-development - # You don't need to specify the corePackage, it's set to LIGHTWEIGHT by default - corePackage: LIGHTWEIGHT - tags: - - zerops-recipe - - development -``` - -### Lightweight Package Features - -- Single container architecture -- 100 hours of build time on performant build containers -- 5 GB space for automatic, encrypted backups -- 1 TB of egress - -## Larger Scale Projects - -For production deployments or larger projects, use the Serious Core Package. You can create a project by importing the following Yaml: - -```yml -project: - name: laravel-production - # You need to specify the corePackage as SERIOUS as it's default as LIGHTWEIGHT - corePackage: SERIOUS - tags: - - zerops-recipe - - production -``` - -### Serious Package Features - -- Highly available core services (L3 balancer with firewall, logger, statistics service) -- Highly available HTTP routing & load balancer with SSL termination and automatic certificate generation -- Proxy / load balancers for managed services -- Unique IPv6 IP address -- 150 hours of build time on performant build containers -- 25 GB space for automatic, encrypted backups -- 3 TB of egress - - -As you've created a Zerops Project, you can [create a Php Nginx service](/frameworks/laravel/create-service) for your Laravel application. - - - diff --git a/apps/docs/content/frameworks/laravel/create-service.mdx b/apps/docs/content/frameworks/laravel/create-service.mdx deleted file mode 100644 index e3effd18..00000000 --- a/apps/docs/content/frameworks/laravel/create-service.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Create PHP Nginx Service -description: Create a PHP Nginx Service for Laravel Frontend ---- - -import Image from '/src/components/Image'; -import data from '@site/static/data.json'; -import UnorderedList from '@site/src/components/UnorderedList'; -import CustomCard from '@site/src/components/CustomCard'; -import { Dropdown, DropdownItem } from '/src/components/Dropdown'; - -The Php Nginx service contains the Nginx web server optimized for your static content. Php Nginx service is highly scalable and customisable to suit both development and production. - -## Add Service Using GUI - -- Go to the project's page and choose **Add new service** in the left menu of the **Services** Page. -- Choose PHP Nginx service, set your preferred hostname (your service name), environment variables and auto scaling configuration. - -Add a new service - -- Set your preferred hostname(your service name) - Enter a unique service hostname like "app","cache", "gui" etc -:::caution -The hostname is fixed after the service is created. It can't be changed later. -::: - -### Set Secret Env Variables - -Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start. - -Setting the secret environment variables is optional. You can set them later in Zerops GUI. - -:::info -Read more about [Different Types of Environment Variables](/frameworks/laravel/env-variables). -::: - -### Set Auto Scaling Configuration - -Zerops allows you to configure automatic vertical and horizontal scaling for PHP Nginx services. Vertical scaling means increasing or decreasing the hardware resources (CPU, RAM and disk) of a PHP Nginx container based on your defined thresholds. Horizontal scaling adds or removes whole containers according to your configuration. - -:::info -Read more about [Automatic scaling and High Availability](/features/scaling-ha). -::: - -

- Automatic Scaling -

- -## Add Service Using YAML - -If you want to import a service to an existing project, you can use Zerops GUI or [zCLI](/references/cli/commands#service). - -- Go to the project's page and choose **Import services** in the left menu on the **Services** page. -- Then add a new Php Nginx service: - -```yml -#yamlPreprocessor=on -services: - - hostname: app - type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-minimal - enableSubdomainAccess: true - envSecrets: - APP_KEY: <@generateRandomString(<32>)> - APP_DEBUG: true - APP_ENV: development -``` - - - - - -```yml -#yamlPreprocessor=on -project: - name: laravel-minimal-devel - tags: - - zerops-recipe - - development - -services: - - hostname: app - type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-minimal - enableSubdomainAccess: true - envSecrets: - APP_KEY: <@generateRandomString(<32>)> - APP_DEBUG: true - APP_ENV: development - - - hostname: db - type: postgresql@16 - mode: NON_HA - priority: 10 -``` - - - - - -If you want to generate a random strings, secrets, etc. you need to use `#yamlPreprocessor=on` line at the beginning of your import YAML script and read more about how to setup [env variables](/frameworks/laravel/env-variables). - -:::info -If you want to add a PostgreSQL Database service to your project, you can use the following YAML: - -```yml -services: - - hostname: db - type: postgresql@16 - mode: HA -``` -::: diff --git a/apps/docs/content/frameworks/laravel/cron.mdx b/apps/docs/content/frameworks/laravel/cron.mdx index 1fcb86bd..55e408cf 100644 --- a/apps/docs/content/frameworks/laravel/cron.mdx +++ b/apps/docs/content/frameworks/laravel/cron.mdx @@ -1,13 +1,15 @@ --- -title: Schedule Jobs & CRON -description: Learn How to Configure and Manage CRON Jobs in Your Zerops Laravel Application +title: Scheduled Tasks and CRON Jobs +description: Learn how to configure and manage scheduled tasks in your Zerops Laravel applications using CRON --- -Zerops provides a convenient way to configure cron jobs directly in your `zerops.yml` file. These scheduled tasks can be configured to run on single or multiple containers with flexible timing options. +Zerops provides a convenient way for managing scheduled tasks through CRON jobs, configured directly in your `zerops.yml` file. These tasks can be scheduled to run on single or multiple containers with granular timing control. ## Basic Configuration -Cron jobs are defined in the `run.crontab` section of your `zerops.yml`. Each job requires at least a `command` and `timing` parameter. +Cron jobs are defined in the `run.crontab` section of your `zerops.yml`. Each job requires two essential parameters: +- **command**: The command to execute +- **timing**: The CRON schedule expression ```yaml run: @@ -16,14 +18,13 @@ run: timing: "0 * * * *" ``` -This basic example writes the current date to a log file every hour. +This example logs the current timestamp every hour. -:::info -If you want to see the full list of parameters and configuration examples for cron jobs, you can read at [zerops-yml/cron](/zerops-yml/cron). +:::tip Detailed Configuration +For comprehensive configuration options and examples, refer to our [CRON configuration guide](/zerops-yml/cron). ::: -## Common Use Cases - +## Common Implementation Patterns ### Laravel Scheduler To run Laravel's scheduler, configure it to execute every minute: @@ -36,7 +37,7 @@ run: ``` ### Cleanup Tasks -Run maintenance tasks on all containers: +Execute maintenance tasks on all containers: ```yaml run: @@ -47,7 +48,7 @@ run: ``` ### Multiple Jobs -You can define multiple cron jobs in the same configuration: +Configure multiple scheduled tasks within a single service: ```yaml run: @@ -67,23 +68,21 @@ run: ## Best Practices -1. **Log Output**: Consider logging the output of your cron jobs for debugging: +1. **Log Output**: Implement comprehensive logging for debugging and monitoring: ```yaml command: "php artisan schedule:run >> /var/log/scheduler.log 2>&1" ``` -2. **Working Directory**: Always specify `workingDir` for Laravel commands to ensure they run from the correct location. +2. **Working Directory**: Always specify `workingDir` for Laravel commands to ensure they are executed from the correct location. -3. **Container Selection**: Use `allContainers: true` carefully, as it might cause duplicate operations in a multi-container setup. +3. **Container Selection**: Use `allContainers: true` carefully to avoid duplicate operations in a multi-container setup. -4. **Timing Considerations**: Avoid running resource-intensive tasks during peak hours. +4. **Timing Considerations**: Schedule intensive tasks during off-peak hours. ## Monitoring -You can monitor your cron jobs through Laravel's built-in logging system for artisan commands. Might be a good idea to use [Supervisor](https://laravel.com/docs/5.1/queues#supervisor-configuration) for Laravel queues. +Enable detailed scheduler [logging](/frameworks/laravel/logs) in your `.env`: -For detailed logs of Laravel scheduled tasks, consider enabling scheduler logging in your `.env`: ``` LOG_CHANNEL=daily -``` - +``` \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/env-variables.mdx b/apps/docs/content/frameworks/laravel/env-variables.mdx index 8059e7cb..e91e6e6f 100644 --- a/apps/docs/content/frameworks/laravel/env-variables.mdx +++ b/apps/docs/content/frameworks/laravel/env-variables.mdx @@ -1,428 +1,181 @@ --- -title: Environment Variables +title: Environment Variables in Zerops for Laravel description: Learn How to Manage Environment Variables in Your Laravel Application on Zerops --- import Image from '/src/components/Image'; import { Dropdown, DropdownItem } from '/src/components/Dropdown'; -Zerops manages environment variables without requiring manual `.env` files. This enables running applications across different environments (development, staging, production) while keeping environment-specific configurations isolated from your code. +Zerops manages environment variables without requiring manual `.env` files, enabling application deployment across different environments (development, staging, production) while keeping environment-specific configurations isolated from your code. - - - -#### basic build & runtime variables -```yml -zerops: - - setup: app - build: - base: php@8.4 - os: alpine - envVariables: - APP_DEBUG: true - APP_ENV: development - DB_CONNECTION: ${RUNTIME_DB_CONNECTION} -``` +Read more about how [environment variables](/features/env-variables) work in Zerops. -Basic build and runtime variables are defined in your [zerops.yml file](/zerops-yml/specification). Use these for build-time configurations, runtime settings that should be version controlled, and default values that remain consistent across environments. These variables require a redeployment when modified. +## Laravel Environment Variables in Zerops -When you need to update build or runtime variables, modify your [zerops.yml file](/zerops-yml/specification) and redeploy your application to Zerops. +### Secret Variables +Some Laravel variables contain sensitive information that should never be exposed as plain text. Manage these using Zerops Secret Variables by: +* Creating and managing them through the Zerops GUI +* Defining them in a configuration file when importing a project or service (allows [automatic generation](#automatic-generation-during-import)) +When importing a project or service, you can define secret variables directly in your import configuration: ```yml -zerops: - - setup: app - run: - base: php-nginx@8.4 - os: alpine - envVariables: - DB_CONNECTION: pgsql -``` - -#### secret variables - -Secret variables, managed through the Zerops GUI, are ideal for sensitive data like API keys and passwords. These can be modified without redeploying your application. Learn more about [Adding Environment Variables using Zerops GUI](#using-zerops-gui). - - - - -## Environment Variables for Laravel - -### Build & Runtime Variables - -You can set basic build & runtime variables in your [zerops.yml file](/zerops-yml/specification) and make sure they're not secrets. - - -#### Database - -You can use use reference environment variables from other services. - -example: `db_password`, `db_user`, `db_host`, `db_database`, `db_port` (from `db` service). - - -```yml -zerops: - - setup: app - run: - base: php-nginx@8.4 - os: alpine - siteConfigPath: site.conf.tmpl - envVariables: - DB_CONNECTION: pgsql - DB_DATABASE: db - DB_HOST: db - DB_USERNAME: ${db_user} - DB_PASSWORD: ${db_password} - DB_PORT: 5432 +services: + - hostname: app + type: php-nginx@8.4 + envSecrets: + APP_KEY: your-secret-key ``` -:::info -If you want to use Redis, read more at [laravel/redis](/frameworks/laravel/redis). +:::tip +Secret variables can be updated at any time without requiring application redeployment. ::: - -## Generate Environment Variables - -Generate environment variables for your zerops service using the `envSecrets` while importing to your Zerops project. - +#### Automatic Generation During Import +If you prefer to have certain secrets **generated automatically**, you can use the [yaml preprocessor](/references/importyml/pre-processor). This is optional and only available during import: ```yml #yamlPreprocessor=on services: - hostname: app type: php-nginx@8.4 - buildFromGit: https://github.com/zeropsio/recipe-laravel-minimal - enableSubdomainAccess: true envSecrets: APP_KEY: <@generateRandomString(<32>)> - APP_DEBUG: true - APP_ENV: development ``` -:::caution -You can only generate environment variables for your zerops service using the `#yamlPreprocessor=on` with `<@generateRandomString(<32>)>`. Learn more about [yamlPreprocessor](/references/importyml/pre-processor). -::: - - -## Adding Environment Variables - -### Using Zerops GUI +### Runtime Variables +These variables are typically environment-specific but not sensitive. Variables that reference secrets can be safely added in `zerops.yml` as they do not contain actual sensitive values. -In your Zerops service you can set secret variables at environment variables page: - -- Scroll to the **Secret variables** section. -- Click on the **Add secret variable** button. -- Set variable key and value. - -You can edit or delete env variables that you've created by hovering over the row and clicking on the menu on the right side of each row. - -

- Environment Variables Secrets -

- -The changes you've made to environment variables will be automatically applied to all containers of your project's services. - -:::caution -You need to **restart** the runtime service after you save the changes in env variables. The PHP process running in the container receives the list env variables only when it starts. Update of the env variables while the PHP process is running does not affect your application. +:::note +Changes to runtime variables require application redeployment to take effect. ::: -### Build Environment Variables using zerops.yml +Below is a complete working example of `envVariables` in `zerops.yml` (sourced from [Laravel Jetstream recipe](https://github.com/zeropsio/recipe-laravel-jetstream/blob/main/zerops.yml): -To set basic env variables for the build environment, add the `envVariables` attribute to the build section in your `zerops.yml`. - -```yml -zerops: - # define hostname of your service - - setup: app - build: - base: php@8.4 - os: alpine - # OPTIONAL. Defines the env variables for the build environment: - envVariables: - APP_DEBUG: true - APP_ENV: development - # ==== how to build your application ==== - run: - base: php-nginx@8.4 - os: alpine - siteConfigPath: site.conf.tmpl + + +```yml title="zerops.yml" +run: + envVariables: + APP_LOCALE: en + APP_FAKER_LOCALE: en_US + APP_FALLBACK_LOCALE: en + APP_MAINTENANCE_DRIVER: file + APP_MAINTENANCE_STORE: database + APP_TIMEZONE: UTC + APP_URL: ${zeropsSubdomain} # References generated variable + ASSET_URL: ${APP_URL} + VITE_APP_NAME: ${APP_NAME} + + # PostgreSQL connection settings + DB_CONNECTION: pgsql + DB_DATABASE: db + DB_HOST: db # References database service hostname + DB_PASSWORD: ${db_password} # References database password + DB_PORT: 5432 + DB_USERNAME: ${db_user} # References database user + + # S3-compatible object storage settings + AWS_ACCESS_KEY_ID: ${storage_accessKeyId} + AWS_REGION: us-east-1 + AWS_BUCKET: ${storage_bucketName} # References bucket name of service 'storage' + AWS_ENDPOINT: ${storage_apiUrl} + AWS_SECRET_ACCESS_KEY: ${storage_secretAccessKey} # Safely references secret + AWS_URL: ${storage_apiUrl}/${storage_bucketName} + AWS_USE_PATH_STYLE_ENDPOINT: true + FILESYSTEM_DISK: s3 + + # Logging Configuration + LOG_CHANNEL: syslog + LOG_LEVEL: debug + LOG_STACK: single + + # SMTP settings for email delivery + MAIL_FROM_ADDRESS: hello@example.com + MAIL_FROM_NAME: ZeropsLaravel + MAIL_HOST: mailpit # References mail service hostname + MAIL_MAILER: smtp + MAIL_PORT: 1025 + + # Redis-based caching and session management + BROADCAST_CONNECTION: redis + CACHE_PREFIX: cache + CACHE_STORE: redis + QUEUE_CONNECTION: redis + REDIS_CLIENT: phpredis + REDIS_HOST: valkey # References Redis service hostname + REDIS_PORT: 6379 + SESSION_DRIVER: redis + SESSION_ENCRYPT: false + SESSION_LIFETIME: 120 + SESSION_PATH: / + + # Security Configuration + BCRYPT_ROUNDS: 12 + TRUSTED_PROXIES: "*" ``` + + -When you need to update a value of an existing env variable or change the set of build or runtime env variables, update your `zerops.yml` and redeploy your application to Zerops. - -### Runtime Environment Variables using zerops.yml - -To set basic env variables for the runtime environment, add the `envVariables` attribute to the runtime section in your `zerops.yml`. +Let's look at variable configurations that may need additional context and where to find detailed implementation guides: +#### Application Configuration +Core application settings that define your Laravel app's identity, URL structure, and environment parameters. Reference environment variables from the same service. ```yml -zerops: - # define hostname of your service - - setup: app - build: - base: php@8.4 - os: alpine - # ==== how to build your application ==== - run: - base: php-nginx@8.4 - os: alpine - siteConfigPath: site.conf.tmpl - # OPTIONAL. Defines the env variables for the runtime environment: - envVariables: - DB_CONNECTION: pgsql - DB_DATABASE: db - DB_HOST: db - DB_USERNAME: ${db_user} - DB_PASSWORD: ${db_password} - DB_PORT: 5432 +APP_URL: ${zeropsSubdomain} # zeropsSubdomain variable is system generated +ASSET_URL: ${APP_URL} +VITE_APP_NAME: ${APP_NAME} # APP_NAME variable was created during import (envSecrets) ``` -When you need to update a value of an existing env variable or change the set of build or runtime env variables, update your `zerops.yml` and redeploy your application to Zerops. - - - - Environment variable names must start with a letter or underscore, followed by any combination of letters, numbers, or underscores (matching the pattern `[a-zA-Z_]+[a-zA-Z0-9_]*`). - -While keys are case-sensitive, each variable name must be unique within a service, regardless of its case. - -For variable values, Zerops only accepts ASCII characters, and end-of-line characters are not permitted. +#### Database Configuration +Essential database connection parameters that securely reference your PostgreSQL service `db` by hostname and its variables - `password` and `user`. -These restrictions apply uniformly across all environment variable types in Zerops, whether they're secret, build, or runtime variables. +It is safe to store `DB_PASSWORD` in `envVariables` by reference as it does not contain the sensitive value itself. ```yml -APP_NAME -database_url -API_KEY_123 -_INTERNAL_VALUE +DB_HOST: db +DB_PASSWORD: ${db_password} +DB_USERNAME: ${db_user} ``` - - -## Generated Environment Variables - -Zerops creates several helper variables when a PHP service is created, e.g. `hostname`, `PATH`. Some helper variables are read-only (`hostname`), others are editable (`PATH`). Generated variables cannot be deleted. - -Generated env variables are listed on the **Environment variables** page. Scroll to the **Generated variables** section. - -

- image -

- -## How to read Environment Variables from your PHP app +Read more about [database management](/frameworks/laravel/migrations) for Laravel in Zerops. -To access the local environment variable i.e. the variable set to this PHP service in your app, use: - -```sh -getenv('YOUR_VARIABLE_KEY_HERE'); +#### Storage Configuration +S3-compatible object storage settings that enable efficient file handling and asset management in your Laravel application. Reference variables of Object storage service called `storage`. +```yml +AWS_ACCESS_KEY_ID: ${storage_accessKeyId} +AWS_REGION: us-east-1 +AWS_BUCKET: ${storage_bucketName} +AWS_ENDPOINT: ${storage_apiUrl} +AWS_SECRET_ACCESS_KEY: ${storage_secretAccessKey} +AWS_URL: ${storage_apiUrl}/${storage_bucketName} +AWS_USE_PATH_STYLE_ENDPOINT: true +FILESYSTEM_DISK: s3 ``` +Read more about [object storage](/object-storage/overview) in Zerops. -## How to read Environment Variables of another service - -All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore. +#### Logging Configuration +System monitoring and debugging configuration that determines how your application tracks events and errors. - - - - - - - - - - - - - - - - - - - - -
ServiceVariableReference Key
mariadb1username`${mariadb1_user}`
mariadb2password`${mariadb2_password}`
+Learn how to properly [configure logging](/frameworks/laravel/logs) for Laravel in Zerops. -### Usage - -```yaml -zerops: - - setup: app - build: - base: php@8.4 - envVariables: - DB_USERNAME: ${mariadb2_user} - DB_PASSWORD: ${mariadb2_password} +#### Mail Configuration +SMTP server settings that enable your application to send emails through a dedicated mail service. Reference service `mailpit` by hostname. ``` - -## How to read Runtime Environment Variables in the Build Environment - -You can use runtime env variables in the build environment using the `RUNTIME_` prefix. This rule applies both for basic and secret runtime variables. - -```yml -zerops: - - setup: app - build: - base: php@8.4 - os: alpine - envVariables: - APP_DEBUG: true - APP_ENV: development - DB_CONNECTION: ${RUNTIME_DB_CONNECTION} -zerops: - - setup: app - build: - base: - - php@8.4 - os: alpine - envVariables: - APP_DEBUG: true - APP_ENV: development - DB_PASSWORD: ${RUNTIME_DB_PASSWORD} - buildCommands: - - composer install --ignore-platform-reqs - deployFiles: ./ - cache: - - vendor - - composer.lock - deploy: - readinessCheck: - httpGet: - port: 80 - path: /up - run: - base: php-nginx@8.4 - os: alpine - siteConfigPath: site.conf.tmpl - envVariables: - - DB_PASSWORD: ${RUNTIME_DB_PASSWORD} - - initCommands: - - php artisan view:cache - - php artisan config:cache - - php artisan route:cache - - sudo -E -u zerops -- zsc execOnce ${appVersionId} -- php artisan migrate --force - - php artisan optimize - healthCheck: - httpGet: - port: 80 - path: /up +MAIL_HOST: mailpit ``` +Learn how to properly [configure SMTP](/frameworks/laravel/smtp) for Laravel in Zerops. -### Runtime Environment Variables - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable NameExample Value
`APP_URL`https://myapp.zerops.io
`DB_CONNECTION`pgsql
`REDIS_HOST`redis.internal
`API_KEY`secret_key_123
- -### Build Environment References - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable NameExample Value
`RUNTIME_APP_URL`https://myapp.zerops.io
`RUNTIME_DB_CONNECTION`pgsql
`RUNTIME_REDIS_HOST`redis.internal
`RUNTIME_API_KEY`secret_key_123
+#### Cache and Session +Redis-based configuration for handling application caching, queues, and session management to optimize performance. Reference service `valkey` by hostname. +``` +REDIS_HOST: valkey +``` +Learn how to properly [configure cache, queue & session management](/frameworks/laravel/redis) for Laravel in Zerops. :::tip -This prefix system allows you to access runtime configuration values during the build process, which is useful for tasks like asset compilation or configuration file generation. -::: - -## Basic and Secret Environment Variables with the Same Key - -If you create a secret env variable and a basic runtime env variable with the same key, Zerops saves the basic runtime env variable from your zerops.yml and ignores the secret env variable. - -If you create a basic build env variable and a runtime env variable with the same key, Zerops saves both because the build and runtime environments have separate sets of env variables. - - -## Referencing other env variables - -You can reference another variable of the same service using `${key}` in your variable value. You can even reference a variable from a different service using `${hostname_key}`. The referenced variable doesn't need to exist when you are entering your variable. - -### Reference a local variable in another variable value - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable keyVariable valueComputed variable value
id1234512345
hostnameappapp
name`${id}-${hostname}`12345-app
- -### Reference a variable of another project service - -Let's say your project contains two PostgreSQL services `dbtest` and `dbprod`. Both services have a `connectionString` variable. Then you can create a `dbConnectionString` env variable in your PHP runtime and set `${dbtest_connectionString}` as the variable value. Zerops will fill in the value of the `connectionString` variable of the `dbtest` service. - -When you change the `dbConnectionString` value to `${dbprod_connectionString}`, Zerops will fill in the value of the `connectionString` variable of the `dbprod` service. - -:::caution -When you change the value of the `connectionString` variable in the service `dbtest` and commit the changes you need to **restart** the PHP service. The PHP process running in the container receives the list env variables only when it starts. Update of the env variables while the PHP process is running does not affect your application. -::: +For automatic execution with each deploy, add these commands to the `initCommands` section of your `zerops.yml` file. +```yml title="zerops.yml" + initCommands: + - php artisan view:cache + - php artisan config:cache + - php artisan route:cache +``` +::: \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/introduction.mdx b/apps/docs/content/frameworks/laravel/introduction.mdx new file mode 100644 index 00000000..5646948a --- /dev/null +++ b/apps/docs/content/frameworks/laravel/introduction.mdx @@ -0,0 +1,434 @@ +--- +title: How To Deploy Laravel on Zerops with Apache and PostgreSQL +--- + +import DeployButton from '@site/src/components/DeployButton'; +import CustomCard from '@site/src/components/CustomCard'; +import IconLaravel from '@theme/Icon/Laravel'; + + + Deploy the same Laravel setup as in this tutorial with a single click. All you need is a Zerops account. + + + + +## Introduction + +In this tutorial, you'll learn how to deploy a Laravel application on Zerops. We'll configure a complete environment using Apache as the web server and PostgreSQL as the database. + +By using Zerops' built-in VPN functionality, you’ll be able to securely connect to your PostgreSQL database directly from your local environment without needing to install PostgreSQL locally. This setup allows you to use your favorite database tools and perform Laravel migrations while working with a PostgreSQL database hosted on Zerops. + +By the end of this tutorial, you will: +- Have a fresh Laravel installation running locally +- Set up a Zerops project with Apache and PostgreSQL +- Configure zero-downtime deployment with environment variables +- Deploy a production-ready Laravel application accessible via a Zerops subdomain +- Set up secure VPN access to your PostgreSQL database + +## Prerequisites +This tutorial assumes you have: +* PHP, Composer, git installed on your machine +* [Zerops account](https://app.zerops.io/signup) + +:::tip +New Zerops accounts receive $15 in free credits for testing. After verifying your account with a $10 initial payment, you'll get an additional $50 in credits. +::: + +## Step 1 — Creating a New Laravel Project + +Let's start by creating a fresh Laravel project: + +```bash +composer create-project laravel/laravel zerops-laravel +cd zerops-laravel +``` + +:::note +Instead of setting up a local database, we'll later configure your local Laravel to connect directly to the PostgreSQL database in Zerops through a secure VPN connection. +::: + +Now, let's verify everything works locally. Start Laravel's development server: + +```bash +php artisan serve +``` + +Visit http://localhost:8000 in your browser. You should see Laravel's welcome page. + +:::tip +While we're using Laravel's built-in server for simplicity, you can use any local development setup you prefer (Valet, Sail, XAMPP, etc.). +::: + +If you see the welcome page, great! Your local setup is working correctly. + +## Step 2 — Setting Up Your Zerops Project + +### Setting up zcli + +First, we'll need the Zerops Command Line Interface (zcli). Follow this article to [install and log into zcli](/references/cli) with your **Personal access token**. + +### Creating Project Configuration + +When you create a project in Zerops, you're getting much more than just a collection of services. Let's look at what happens behind the scenes and how to configure it. + +#### Production-Ready Infrastructure and Network Security + +When you create a project in Zerops, you get a production-grade infrastructure that eliminates common development headaches. Avoid the 'it works on my machine' issues – your team will develop in environments identical to production. + +Each project runs in its own isolated network with enterprise-level security features automatically configured: +- A smart load balancer handles traffic distribution and security +- Every service gets automatic SSL/TLS certificate management +- Internal services communicate securely using simple hostnames (like 'db' or 'app') +- The entire infrastructure is accessible through a secure VPN + +What makes this special is how it combines security with simplicity. You can: +- Connect to your databases from local tools with full security +- Let team members access services without complex firewall rules +- Run local development against production-identical services +- Deploy changes knowing they'll work exactly as they did in development + +Best of all, this infrastructure requires zero configuration from you – it's all handled automatically when you create your project. You can learn more about infrastructure features in documentation section [Project & Services Structure](https://docs.zerops.io/features/infrastructure). + +#### Project Configuration File + +Let's create our project definition in YAML. This approach provides clear, reproducible infrastructure configuration that can be version controlled. Later in this tutorial, we'll also show how to achieve the same using the GUI. + +Create a new file in your project root called `zerops-project-import.yml` with the following content: + +```yaml title="zerops-project-import.yml" +#yamlPreprocessor=on +project: + name: laravel-zerops + tags: + - zerops-tutorial # tag for easy filtering (optional) + +services: + - hostname: app + type: php-apache@8.4 + envSecrets: + # yamlPreprocessor feat: generates a random 32 char and stores it + APP_KEY: <@generateRandomString(<32>)> + + - hostname: db + type: postgresql@16 + mode: HA # High Availability mode for robust production setup +``` + +:::note +The `#yamlPreprocessor=on` directive enables Zerops' [YAML preprocessing](/references/importyml/pre-processor) for this import file, allowing us to use dynamic values and built-in functions like `generateRandomString`. +::: + +#### Automatic Resource Management + +One of Zerops' most powerful features is its [intelligent autoscaling system](/features/scaling-ha). You don't need to specify fixed resource allocations because Zerops automatically: +- Scales resources (CPU, RAM, Disk) up and down based on actual usage +- Maintains minimum required resources to optimize costs +- Handles vertical and horizontal scaling automatically +- Manages disk space dynamically (a unique feature in the industry) + +See current ranges for [horizontal](/php/how-to/scaling#horizontal-auto-scaling) and [vertical](/php/how-to/scaling#vertical-auto-scaling) scaling of PHP services. + +#### High-Availability Database + +By setting `mode: HA` for the PostgreSQL service, we get: +- A database cluster distributed across ***3 physical servers*** +- Automatic failover and data replication +- Enhanced performance through load distribution +- Production-grade reliability + +Through Zerops VPN, you can securely access this database setup directly from your local machine, ensuring your development environment matches production exactly. + +Configuring a production-grade HA database cluster usually demands DevOps expertise for replication, failover, and load balancing. With Zerops, this is automated and you get this enterprise-level setup automatically. This means you can develop against the same robust database infrastructure that you'll use in production, eliminating environment discrepancies and ensuring your code works consistently across all stages of development. + +Now create the project by running: +```bash +zcli project project-import zerops-project-import.yml +``` +:::tip Team Collaboration Tip +This declarative approach to infrastructure configuration provides significant advantages for team development: +- New team members can quickly create identical development environments +- Infrastructure configuration is transparent and easily reviewable +- Setup is deterministic and reproducible across all environments +- Changes to infrastructure can be version-controlled alongside your code +::: + +### Alternative: Creating Project via GUI + +You can also create and configure your project through the Zerops dashboard: + +1. Log into your [Zerops Dashboard](https://app.zerops.io) +2. Click **Add new project** +3. Enter a project name (e.g., "laravel-zerops") and click **Create project** + +Then add the required services: + +1. **PHP + Apache Service:** + - Click **Add Service** and select **PHP+Apache** + - Set hostname to "app" + - Keep all other settings as default + +2. **PostgreSQL Service:** + - Click **Add Service** and select **PostgreSQL** + - Set hostname to "db" + - Keep all other settings as default + +## Step 3 — Configuring Your Application + +Create a `zerops.yml` configuration file in your project root: + +```yaml title="zerops.yml" +zerops: + - setup: app + build: + base: + - php@8.4 + buildCommands: + - composer install --ignore-platform-reqs + deployFiles: ./ + cache: + - vendor + - composer.lock + deploy: + readinessCheck: + httpGet: + port: 80 + path: /up + run: + base: php-apache@8.4 + envVariables: + APP_NAME: "Laravel Zerops Demo" + APP_DEBUG: false + APP_ENV: production + APP_URL: ${zeropsSubdomain} + DB_CONNECTION: pgsql + DB_HOST: db + DB_PORT: 5432 + DB_DATABASE: db + DB_USERNAME: ${db_user} + DB_PASSWORD: ${db_password} + LOG_CHANNEL: stack + LOG_LEVEL: debug + SESSION_DRIVER: database + + initCommands: + - php artisan config:cache + - php artisan route:cache + - sudo -E -u zerops -- zsc execOnce ${appVersionId} -- php artisan migrate --force + - php artisan optimize + healthCheck: + httpGet: + port: 80 + path: /up +``` + +Let's break down some important parts of this configuration: + +### Health Checks + +The health check configuration ensures your application is running correctly: +```yaml + readinessCheck: + httpGet: + port: 80 + path: /up + ... + healthCheck: + httpGet: + port: 80 + path: /up +``` + +Zerops uses these health checks to: +- Verify new deployments before routing traffic (readinessCheck) +- Monitor running containers (healthCheck) +- Automatically restart unhealthy containers +- Ensure zero-downtime deployments + +By default, latest version of Laravel responds with a 200 OK status on the `/up` endpoint, so no additional configuration is needed. + +### Environment Variables + +Zerops provides several built-in variables that you can use in your configuration: + +```yaml +APP_URL: ${zeropsSubdomain} # Automatically set to your app's Zerops URL +DB_USERNAME: ${db_user} # Database credentials auto-injected +DB_PASSWORD: ${db_password} # Securely managed by Zerops +``` + +These values are automatically injected by Zerops: +- `${zeropsSubdomain}` - Your application's Zerops URL +- `${db_user}` and `${db_password}` - Secure database credentials + +Learn more about [environment variables](/features/env-variables) in Zerops. + +### Safe Database Migrations +```yaml +sudo -E -u zerops -- zsc execOnce ${appVersionId} -- php artisan migrate --force +``` +This special command ensures your database migrations run exactly once, even when running multiple containers. It's crucial for preventing duplicate migrations during scaling. + + +## Step 4 — Deploying Your Application + +Now comes the exciting part - deploying your application to Zerops! + +### Deploying Your Code + +Initialize git in your project directory: +```bash +git init +``` + +:::note +Git is required to track changes for deployment. You don't need to commit but initializing git helps Zerops manage the deployment files. +::: + +Push your code to Zerops: +```bash +zcli push +``` + +You'll go through an interactive selection process: + +1. First, you'll see a list of your projects: +``` +Please, select a project +| ID | NAME | ORG NAME | STATUS | +|--------------------------|---------------------|-----------------------|--------| +| jrkERI7FTrZn7jwcTnACCA | laravel-zerops | ORGANIZATION_NAME | ACTIVE | +``` +Select your project from the list. + +2. Then, you'll select the service: +``` +INFO Selected project: laravel-zerops +SELECT Please, select a service + +| ID | NAME | STATUS | +|--------------------------|---------|--------| +| 7pinFB1ZSIeGz16OIi4GuQ | app | ACTIVE | +| cD2fDBetS0KPQAcIsnH8OA | db | ACTIVE | +``` +Select the "app" service. + +3. The deployment will proceed with output like: +``` +INFO Selected project: laravel-zerops +INFO Selected service: app +INFO creating package +INFO File zerops.yml found. Path: /path/to/zerops.yml +DONE package uploaded +INFO package created +INFO deploying service +DONE Push finished +``` + +### Monitoring the Deployment + +1. Go to the [Zerops Dashboard](https://app.zerops.io) +2. In the top-left corner, you'll see a circle with **running process** text +3. Click it to see the build progress overview +4. Click **Open pipeline detail** button to view the detailed build process + +You'll see the deployment progress with timing for each step: +- Initializing build container +- Running build commands from zerops.yml +- Creating app version and upgrading PHP+Apache service + +The entire process usually takes less than a minute to complete. + +## Step 5 — Verifying Your Deployment + +Once the deployment completes, let's verify everything works: + +1. Go to your project's app service +2. Click on **Public access & internal ports** +3. Find the **Public Access through zerops.app Subdomain** section +4. Toggle **Enable Zerops Subdomain Access** +5. Click the generated URL (e.g., https://app-xxx.prg1.zerops.app) to view your application + +:::note +The Zerops subdomain is perfect for testing and development, but for production, you should set up your own domain under **Public Access through Your Domains**. See [detailed guide](/features/access) about public access. +::: + +### Testing Database Connectivity + +Let's create a quick route to test database connectivity. Add this to your `routes/web.php`: + +```php +Route::get('/db-test', function () { + session()->save(); + return 'Current number of active sessions in database: ' . Illuminate\Support\Facades\DB::table('sessions')->count(); +}); +``` + +Deploy this change: +```bash +zcli push +``` + +Visit your-app-url/db-test to verify database connectivity. + +## Accessing Your Database Locally + +Once your application is deployed, you might want to access the database directly from your local machine. Zerops makes this easy with VPN access. + +### Setting up VPN Access + +1. Start the VPN connection: +```bash +zcli vpn up +``` + +:::note +Now you can access your services directly with hostname. Try http://app.zerops/ to verify connectivity. +::: + +2. Select your project when prompted + +That's it! You now have direct access to all services in your project. + +### Connecting to Database + +To get your database credentials: +1. Go to the PostgreSQL service in your project +2. Click **Access details** button +3. Here you'll find all connection details including hostname, port, user, and password + +Update your local `.env` file with these credentials: + +```ini +DB_CONNECTION=pgsql +DB_HOST=db.zerops +DB_PORT=5432 +DB_DATABASE=db +DB_USERNAME=db +DB_PASSWORD=[password from Access details] +``` + +Now you can use your favorite database management tool or run artisan commands while working with the database in Zerops - no local PostgreSQL installation needed! + +## Next Steps + +Now that your Laravel application is running on Zerops, consider: + +1. Setting up a custom domain +2. Implementing basic CI/CD pipelines implementing [GitHub](https://docs.zerops.io/references/github-integration) or [GitLab](https://docs.zerops.io/references/gitlab-integration) integration +3. Setting up [object storage](https://docs.zerops.io/object-storage/overview) + +## Conclusion + +Congratulations! 🎉 You've successfully deployed a Laravel application on Zerops with Apache and PostgreSQL. Your application is now running in a production-ready environment with automated builds and deployments. + +### Additional Resources + +- [Laravel Documentation](https://laravel.com/docs) +- [Laravel Recipe Repository](https://github.com/zeropsio/recipe-laravel-minimal) +- [zcli Documentation](https://github.com/zeropsio/zcli) + +### Need Help? + +- Join the [Zerops Discord server](https://docs.zerops.io/discord) +- Check out the [Zerops Blog](https://zerops.io/blog) +- Follow [@zeropsio](https://twitter.com/zeropsio) on Twitter \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/local-development.mdx b/apps/docs/content/frameworks/laravel/local-development.mdx new file mode 100644 index 00000000..e69de29b diff --git a/apps/docs/content/frameworks/laravel/logs.mdx b/apps/docs/content/frameworks/laravel/logs.mdx index e84b6123..e9f8c359 100644 --- a/apps/docs/content/frameworks/laravel/logs.mdx +++ b/apps/docs/content/frameworks/laravel/logs.mdx @@ -1,97 +1,72 @@ --- -title: Access Logs in Your Laravel Project +title: Laravel Logging description: Learn How to Configure and Access Logs for Your Laravel Application on Zerops --- import Image from '/src/components/Image'; +import { Dropdown, DropdownItem } from '/src/components/Dropdown'; -Zerops provides comprehensive logging capabilities for your Laravel application through three different log types: +Zerops provides comprehensive logging capabilities for Laravel applications using its distributed logging architecture. This guide shows you how to set up and optimize Laravel logging on Zerops, ensuring your application logs are properly captured and accessible. -- [build log](#build-log) -- [prepare runtime log](#prepare-runtime-log) -- [runtime log](#runtime-log) +## Accessing Logs -## How to Access Logs +Learn how to [access and view your logs](/php/how-to/logs) in Zerops. -### Build Log +## Configuration -#### Zerops GUI +### Zerops Environment Variables -To access a build log in Zerops GUI: -1. Go to the Service detail -2. Choose **Service dashboard & runtime containers** in the left menu -3. Open the pipeline detail of an application version -4. Click on **Show build log** +Laravel logging in Zerops is configured through environment variables, such as: -The **Show build log** button is available only if the build pipeline was triggered for the service by zCLI or by Github/Gitlab Integration. -The commands inside Build log are specified in `buildCommands` in [zerops.yml](/zerops-yml/specification). +- `LOG_CHANNEL`: Specifies which logging channel to use (e.g., 'syslog', 'stack') +- `LOG_STACK`: When using the stack channel, defines which channels to include +- `LOG_LEVEL`: Sets the minimum log level to capture (e.g., 'debug', 'info', 'error') -#### zCLI - -To access a build log in Zerops CLI use: - -```sh -zcli service log --showBuildLogs +```yml title="zerops.yml" +zerops: + - setup: app + run: + envVariables: + LOG_CHANNEL: syslog + LOG_LEVEL: debug + LOG_STACK: single ``` -Read more about the [zcli service log](/references/cli/access-logs) command. - -### Prepare Runtime Log - -#### Zerops GUI - -To access a prepare runtime log in Zerops GUI: -1. Go to the service detail -2. Choose **Service dashboard & runtime containers** in the left menu -3. Open the pipeline detail of an application version -4. Click on **Prepare runtime log** - -The **Show prepare runtime log** button is available only if the build pipeline was triggered for the service by zCLI or by Github/Gitlab Integration. -The commands inside Prepare runtime log are specified in `prepareCommands` in [zerops.yml](/zerops-yml/specification). - -#### zCLI - -_Prepare runtime log is currently not supported in zCLI._ - -### Runtime Log - -#### Zerops GUI - -To access a runtime log in Zerops GUI: -1. Go to the service detail -2. Choose **Runtime log** in the left menu - -

- Laravel Runtime Logs -

- -Each runtime container has its own log. If your service has multiple containers, select the container in the log header. +:::tip Available Log Channels +Laravel supports several logging channels out of the box: +- **stack**: Aggregates multiple logging channels into a single channel +- **single**: Writes logs to a single file (storage/logs/laravel.log) +- **daily**: Creates daily rotating log files +- **syslog**: Writes to system log (recommended for Zerops) +- **stderr**: Writes to PHP's standard error output stream +- **errorlog**: Uses PHP's error_log function +- **slack**: Sends log messages to Slack +- **papertrail**: Sends logs to Papertrail +- **mongodb**: Stores logs in MongoDB (requires additional package) +::: -You can filter log records by: -- Minimum severity level -- Time period +To use multiple logging channels, [configure](#laravel-configuration) the stack channel: -#### zCLI +```yml +LOG_CHANNEL: stack +LOG_STACK: syslog,daily +``` -To access the log of the runtime containers in Zerops CLI use: +This configuration logs to both syslog (for Zerops) and daily files (for local access). -```sh -zcli service log -``` +:::tip +Using appropriate log levels makes it easier to filter and find relevant messages in the Zerops GUI. +::: -Read more about the [zcli service log](/references/cli/access-logs) command. +### Laravel Configuration -## Laravel Logging Configuration +While Zerops is configured through environment variables, these variables are interpreted by Laravel's logging system. By default, Laravel includes a logging configuration that works out of the box - you don't need to modify anything. -Your Laravel application's `config/logging.php` defines how logs are handled: +If you're curious about the underlying configuration or need to customize it beyond environment variables, here's what Laravel's logging configuration typically looks like: -```php + + +```php title="config/logging.php" + -:::tip Available Log Channels -Laravel supports several logging channels out of the box: -- **stack**: Aggregates multiple logging channels into a single channel -- **single**: Writes logs to a single file (storage/logs/laravel.log) -- **daily**: Creates daily rotating log files -- **syslog**: Writes to system log (recommended for Zerops) -- **stderr**: Writes to PHP's standard error output stream -- **errorlog**: Uses PHP's error_log function -- **slack**: Sends log messages to Slack -- **papertrail**: Sends logs to Papertrail -- **mongodb**: Stores logs in MongoDB (requires additional package) -::: - -### Using Logs in Your Code +### Using Logs Laravel provides several ways to write log messages: @@ -187,33 +151,4 @@ logger($message); // defaults to info level // With context data Log::info('User failed to login.', ['id' => $user->id]); -``` - -### Zerops Environment Configuration - -For optimal logging in Zerops, use these environment variables in your `zerops.yml`: - -```yml -zerops: - - setup: app - run: - envVariables: - LOG_CHANNEL: syslog - LOG_LEVEL: debug - LOG_STACK: single -``` - -### Using Multiple Channels - -To use multiple logging channels, configure the stack channel: - -```yml -LOG_CHANNEL: stack -LOG_STACK: syslog -``` - -This will log to both syslog (for Zerops) and daily files (for local access). - -:::tip -Use appropriate log levels to make it easier to filter and find relevant log messages in Zerops GUI. -::: +``` \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/migrations.mdx b/apps/docs/content/frameworks/laravel/migrations.mdx index afd639cd..0d4896f9 100644 --- a/apps/docs/content/frameworks/laravel/migrations.mdx +++ b/apps/docs/content/frameworks/laravel/migrations.mdx @@ -1,25 +1,42 @@ --- -title: Database Migrations in Laravel -description: Learn How to Manage and Run Database Migrations for Your Laravel Application on Zerops +title: Database Version Control with Migrations +description: Learn how to track, version, and manage database schema changes alongside your application updates using Laravel migrations. --- import Image from '/src/components/Image'; -:::note -This guide assumes you're using PostgreSQL, which is the recommended database system on Zerops. While Laravel supports multiple database systems, the examples in this guide are specifically for PostgreSQL. +Database migrations are **version control** for your database schema, allowing you to evolve your database structure alongside your application versions. Each migration represents a specific version change in your application's database schema, ensuring your database structure stays synchronized with your codebase as your application evolves. + +This guide covers how to implement and manage these version-based database changes on Zerops, focusing on PostgreSQL as the recommended database system. + +## Environment Configuration + +Configure your database connection in your environment variables: + +```yaml +zerops: + - setup: app + run: + envVariables: + DB_CONNECTION: pgsql + DB_HOST: ${db_hostname} + DB_PORT: 5432 + DB_DATABASE: myapp + DB_USERNAME: ${db_user} + DB_PASSWORD: ${db_password} +``` + +:::warning Backup your data +Before running migrations in production, it's strongly recommended to back up your database. Zerops provides automated daily backups - see our [backup documentation](/features/backup) for details. ::: ## Running Migrations ### Automatic Migrations -:::info Configuration Reference -Here you can find some part of `zerops.yml`. For the complete configuration options including service setup, environment variables, and deployment settings, see the [zerops.yml reference guide](/zerops-yml/specification). -::: - -To automatically run migrations during deployment, add the migration command to your `zerops.yml`: +The most reliable way to manage migrations in your deployment pipeline is through automatic execution. Configure this in your `zerops.yml`: -```yaml:zerops.yml +```yaml title="zerops.yml" zerops: - setup: app run: @@ -28,42 +45,42 @@ zerops: ``` :::caution -The `--force` flag is required when running migrations in production to prevent accidental data loss. +When running automatic migrations in production, the `--force` flag is necessary to bypass Laravel's safety prompt. Without this flag, Laravel asks for confirmation to help prevent accidental data loss. ::: ### Manual Migrations -You can also run migrations by connecting to Zerops VPN and then SSHing into your service: +For development and troubleshooting purposes, you can execute migrations manually through SSH: ```bash # Connect to your zerops project zcli vpn up -# SSH into your service with it's hostname (app) +# SSH into your service using it's hostname (app) ssh app -# If you're on MacOS you should use the following command instead +# For MacOS users ssh app.zerops ``` ## Migration Commands -Common migration commands you can use: +Essential migration commands for your workflow: ```bash -# Create a new migration +# Create a new migration file with timestamp php artisan make:migration create_users_table -# Run pending migrations +# Execute all pending migrations php artisan migrate -# Rollback the last migration operation +# Revert the most recent migration operation php artisan migrate:rollback -# Rollback all migrations and run them again +# Reset and rerun all migrations (warning: destroys existing data) php artisan migrate:fresh -# Show migration status +# Display current migration status php artisan migrate:status ``` @@ -71,7 +88,7 @@ php artisan migrate:status ### Migration Structure -```php:database/migrations/2024_03_20_create_users_table.php +```php {title="database/migrations/create_users_table.php"} id(); - $table->string('name'); - $table->string('email')->unique(); - $table->timestamp('email_verified_at')->nullable(); - $table->string('password'); - $table->rememberToken(); - $table->timestamps(); + $table->id(); // Auto-incrementing primary key + $table->string('name'); // User's full name + $table->string('email')->unique(); // Unique email address + $table->timestamp('email_verified_at')->nullable(); // Email verification timestamp + $table->string('password'); // Hashed password + $table->rememberToken(); // Remember me token + $table->timestamps(); // Created_at and updated_at timestamps }); } + /** + * Reverse the migrations. + * Removes the users table completely. + */ public function down() { Schema::dropIfExists('users'); @@ -102,22 +127,23 @@ return new class extends Migration ### Safe Migration Practices -1. **Always Include Down Method** +1. **Implement Reversible Changes** ```php public function down() { - // Reverse the changes made in up() + // Always provide a way to undo migration changes Schema::table('users', function (Blueprint $table) { $table->dropColumn('new_column'); }); } ``` -2. **Use Foreign Keys Properly** +2. **Use Foreign Key Contraints** ```php public function up() { Schema::table('posts', function (Blueprint $table) { + // Create relationship with cascading delete $table->foreignId('user_id') ->constrained() ->onDelete('cascade'); @@ -125,45 +151,31 @@ public function up() } ``` -3. **Handle Large Tables** +3. **Handle Large Tables Efficiently** ```php public function up() { + // Step 1: Add nullable column to prevent blocking operations Schema::table('large_table', function (Blueprint $table) { - $table->string('new_column')->nullable(); // Allow null first + $table->string('new_column')->nullable(); }); - - // Update data in chunks - DB::table('large_table')->orderBy('id')->chunk(1000, function ($records) { - foreach ($records as $record) { - DB::table('large_table') - ->where('id', $record->id) - ->update(['new_column' => 'default_value']); - } + + // Step 2: Update data in manageable chunks + DB::table('large_table') + ->orderBy('id') + ->chunk(1000, function ($records) { + foreach ($records as $record) { + DB::table('large_table') + ->where('id', $record->id) + ->update(['new_column' => 'default_value']); + } }); } ``` -## Environment Configuration - -Configure your database connection in your environment variables: - -```yaml -zerops: - - setup: app - run: - envVariables: - DB_CONNECTION: pgsql - DB_HOST: ${db_hostname} - DB_PORT: 5432 - DB_DATABASE: myapp - DB_USERNAME: ${db_user} - DB_PASSWORD: ${db_password} -``` - ## Testing Migrations -### Create Test Database +### Create a Test Database Add a testing connection to your `config/database.php`: @@ -177,20 +189,23 @@ Add a testing connection to your `config/database.php`: ], ``` -### Migration Testing Example +### Migration Test Example -Add a migration test file at `tests/Unit/MigrationTest.php`: +Create a test file at `tests/Unit/MigrationTest.php`: ```php +/** + * Test migration execution and schema verification + */ public function test_migrations_can_be_run() { - // Run migrations + // Execute all migrations Artisan::call('migrate'); - // Assert the table exists + // Verify table creation $this->assertTrue(Schema::hasTable('users')); - - // Assert columns exist + + // Verify column structure $this->assertTrue(Schema::hasColumns('users', [ 'id', 'name', 'email', 'password' ])); @@ -198,18 +213,18 @@ public function test_migrations_can_be_run() ``` :::tip Migration Tips -- Always backup your database before running migrations in production -- Use transactions for complex migrations -- Test migrations thoroughly in development -- Consider using seeders for initial data -- Monitor migration execution time for large tables +* Always create a backup before running migrations in production +* Use database transactions for complex migrations +* Thoroughly test migrations in development environment +* Implement seeders for initial data population +* Monitor execution time for migrations on large tables ::: ## Troubleshooting -Common migration issues and solutions: +Common migration issues and their solutions: -1. **Migration Timeout** while running migrations in [zerops.yml](/zerops-yml/specification): +1. **Migration Timeout** Configure longer timeout in [zerops.yml](/zerops-yml/specification): ```yaml zerops: - setup: app @@ -218,19 +233,24 @@ zerops: - php artisan migrate --force --timeout=1000 ``` -2. **Lock Timeout** in `config/database.php`: +2. **Database Lock Timeout** Adjust PDO settings in `config/database.php`: ```php 'pgsql' => [ // ... 'options' => [ - PDO::ATTR_LOCK_TIMEOUT => 1000 + PDO::ATTR_LOCK_TIMEOUT => 1000 // Milliseconds ] ], ``` 3. **Reset Migration State** Commands: ```bash +# Reset all migrations php artisan migrate:reset + +# Re-run all migrations php artisan migrate ``` +## Additional Resources +* [Laravel Migration Documentation](https://laravel.com/docs/11.x/migrations) diff --git a/apps/docs/content/frameworks/laravel/public-access.mdx b/apps/docs/content/frameworks/laravel/public-access.mdx deleted file mode 100644 index 47da052d..00000000 --- a/apps/docs/content/frameworks/laravel/public-access.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Public Access for Laravel Applications -description: Learn How to Configure Public Access for Your Laravel Application Using Zerops Subdomains or Custom Domains ---- - -import Image from '/src/components/Image'; - -Firstly, make sure your zerops.yml is configured correctly with a readiness check and health check. - -```yaml -zerops: - - setup: app - build: - base: - - php@8.4 - os: alpine - deploy: - readinessCheck: - httpGet: - port: 80 - path: /up - run: - base: php-nginx@8.4 - os: alpine - healthCheck: - httpGet: - port: 80 - path: /up -``` - -After your zerops.yml is configured correctly, you can enable public access for your application. - - -## Public Access Options - -There are two ways to make your Laravel application publicly accessible on Zerops: -1. Using a Zerops subdomain -2. Using your own custom domain - -## Zerops Subdomain Access - -### Enable During Project Import - -You can enable the Zerops subdomain while importing your project by adding the `enableSubdomainAccess` flag: - -```yaml -project: - name: laravel-minimal-devel - -services: - - hostname: app - type: php-nginx@8.4 - enableSubdomainAccess: true -``` - -### Enable via Zerops GUI - -You can enable public access at any time through the Zerops dashboard: - -

- Enabling public access through Zerops GUI -

- -## Custom Domain Setup - -### 1. Add Domain in Zerops GUI - -Add your custom domain through the service's public access & internal ports page and you'll receive a DNS records to configure in your domain registrar: - -

- Adding custom domain in Zerops GUI -

- - - -### 2. Configure your DNS - -Choose one of the following configurations based on your needs: - -#### Root Domain (example.com) - - - - - - - - - - - - - - - - - - - - - - - - - -
Record TypeHostValue/Target
A@34.120.10.15
AAAA@2600:1900:4150:68f::1
CNAME(enables www subdomain)www@
- -#### Subdomain (docs.example.com) - - - - - - - - - - - - - - - - - - - - -
Record TypeHostValue/Target
Adocs34.120.10.15
AAAAdocs2600:1900:4150:68f::1
- -:::info -You can choose to use only IPv4 (A record) by requesting a unique IPv4 address in Zerops. -::: - -### 3. DNS Propagation - -After configuring your DNS records, you'll need to wait for the changes to propagate globally. This typically takes 15-60 minutes, but can take up to 48 hours in some cases. - -You can monitor the propagation status using [whatsmydns.net](https://www.whatsmydns.net/). - diff --git a/apps/docs/content/frameworks/laravel/redis.mdx b/apps/docs/content/frameworks/laravel/redis.mdx index 5fbc06e9..10cb96e0 100644 --- a/apps/docs/content/frameworks/laravel/redis.mdx +++ b/apps/docs/content/frameworks/laravel/redis.mdx @@ -1,28 +1,26 @@ --- -title: Using Redis with Laravel +title: Cache, Queue & Session Management with Redis description: Learn How to Configure and Use Redis for Caching, Queues, and Sessions in Your Laravel Application on Zerops --- import Image from '/src/components/Image'; -# Redis Integration with Laravel +Redis is a powerful in-memory data structure store serving as a database, cache, message broker, and queue. This guide walks you through Redis integration with your Laravel application on Zerops for high-performance caching, session management, and queue processing. -Redis is a powerful in-memory data structure store that can be used as a database, cache, message broker, and queue. This guide will help you integrate Redis with your Laravel application on Zerops, enabling high-performance caching, session management, and queue processing. +Zerops provides [Valkey](https://valkey.io), an open-source Redis alternative that delivers high-performance key/value storage with full Redis compatibility. Valkey supports all common Redis use cases — from caching and message queues to primary database functionality. ## Adding Redis Service -Zerops provides Valkey, an open source Redis alternative which is a high-performance key/value datastore that's fully compatible with Redis. Valkey supports all common Redis use cases including caching, message queues, and can even serve as a primary database. - -Before using Valkey(Redis) features with Laravel, you'll need to add Valkey as a service to your Zerops project. The service configuration defines the version, availability mode. +To use Valkey (Redis) features with Laravel, first either import Valkey as a service to your Zerops project ```yml services: - - hostname: redis + - hostname: valkey type: valkey@7.2 - mode: NON_HA # or HA for high availability + mode: NON_HA # use HA in production ``` -You can also add the Valkey service to your project manually from the Zerops GUI. +or add the Valkey service to your project manually from the Zerops GUI. :::tip High Availability Mode -For production environments, it's recommended to use `HA` mode. This ensures automatic failover in case of node failure and provides data replication across multiple nodes. High availability mode significantly improves reliability and uptime while offering better handling of network partitions. +For production environments, we recommend using `HA` mode. This configuration: +* Ensures automatic failover during node failures +* Provides data replication across multiple nodes +* Improves reliability and uptime ::: ## Environment Configuration ### Basic Redis Settings -The environment variables configure how your Laravel application connects to and utilizes Redis. These settings control various aspects of Redis integration, from basic connectivity to specific feature configurations. +Environment variables control how your Laravel application connects to and uses Redis. Below are the core settings grouped by functionality: ```yml zerops: @@ -55,7 +56,7 @@ zerops: envVariables: # Redis Connection Settings REDIS_CLIENT: phpredis # PHP Redis client for better performance - REDIS_HOST: redis # Internal hostname of Redis service + REDIS_HOST: valkey # Internal hostname of Valkey service REDIS_PORT: 6379 # Standard Redis port number # Cache Configuration @@ -77,9 +78,9 @@ zerops: ### Redis Caching -Laravel's cache system provides a unified API across various cache backends. This configuration sets up Redis as your application's primary cache store, enabling fast and reliable data caching. You can also set up a custom cache connection in the `config/cache.php` file. +Laravel's cache system offers a unified API across different cache backends. The following configuration establishes Redis as your primary cache store for fast, reliable data caching: -```php +```php title="config/cache.php" 'default' => env('CACHE_STORE', 'database'), 'stores' => [ @@ -97,7 +98,7 @@ Laravel's cache system provides a unified API across various cache backends. Thi Using Redis for session storage provides better performance than file-based sessions and enables seamless session sharing across multiple application servers. You can also set up a custom session connection in the `config/session.php` file. -```php +```php title="config/session.php" 'driver' => env('SESSION_DRIVER', 'redis'), 'lifetime' => env('SESSION_LIFETIME', 120), 'encrypt' => env('SESSION_ENCRYPT', false), @@ -107,7 +108,7 @@ Using Redis for session storage provides better performance than file-based sess Redis queues offer a robust solution for handling background jobs in Laravel. This configuration sets up Redis as your queue backend with retry policies and connection settings. You can also set up a custom queue connection in the `config/queue.php` file. -```php +```php title="config/queue.php" 'default' => env('QUEUE_CONNECTION', 'redis'), 'connections' => [ @@ -121,6 +122,24 @@ Redis queues offer a robust solution for handling background jobs in Laravel. Th ], ``` +Consider using [Supervisor](https://laravel.com/docs/5.1/queues#supervisor-configuration) for managing Laravel queues in production. + +### Performance Optimization +Configure your Redis connection pool for optimal performance: +```php +'redis' => [ + 'client' => env('REDIS_CLIENT', 'phpredis'), + 'options' => [ + 'cluster' => env('REDIS_CLUSTER', 'redis'), + 'prefix' => env('REDIS_PREFIX', ''), + 'pool' => [ + 'max_connections' => 50, + 'timeout' => 30, + ], + ], +], +``` + ## Working with Redis Features ### Cache Operations Examples @@ -151,4 +170,4 @@ session(['key' => 'value']); // Retrieve data from the session with optional default $value = session('key'); -``` +``` \ No newline at end of file diff --git a/apps/docs/content/frameworks/laravel/smtp.mdx b/apps/docs/content/frameworks/laravel/smtp.mdx index 08144a07..7b7205da 100644 --- a/apps/docs/content/frameworks/laravel/smtp.mdx +++ b/apps/docs/content/frameworks/laravel/smtp.mdx @@ -4,53 +4,38 @@ description: Learn How to Configure SMTP for Sending Emails in Your Laravel Appl --- import Image from '/src/components/Image'; +import { Dropdown, DropdownItem } from '/src/components/Dropdown'; -## Development Setup with Mailpit +# SMTP Configuration for Laravel on Zerops -For development environments, Zerops provides Mailpit for testing emails. Add this to your project import configuration: - -```yml -services: - - hostname: mailpit - type: go@1 - buildFromGit: https://github.com/zeropsio/recipe-mailpit - enableSubdomainAccess: true -``` - -Configure your Laravel service to use Mailpit: - -```yml -zerops: - - setup: app - run: - envVariables: - MAIL_MAILER: smtp - MAIL_HOST: mailpit - MAIL_PORT: 1025 - MAIL_FROM_ADDRESS: hello@example.com - MAIL_FROM_NAME: ZeropsLaravel -``` - -:::tip -Enable `enableSubdomainAccess` to access the Mailpit web interface for viewing sent emails. +:::warning Important Security Note +By default, SMTP ports are blocked by Zerops firewall for security reasons. To use external SMTP services, please [contact Zerops support](mailto:support@zerops.io) to have the necessary ports opened for your project. +Include in your request: +* Detailed explanation of your use case +* Specific ports and protocols needed +* Project ID and Organization ID from your Zerops Dashboard ::: -## Laravel Application Setup +## Production Configuration + +### Laravel Mail Configuration -### Mail Configuration File +Laravel comes with a default mail configuration in `config/mail.php`. You typically don't need to modify this file as all settings can be controlled through environment variables. -Laravel's default `config/mail.php` provides multiple mailer configurations: +The default configuration supports multiple mailer types and reads all sensitive information from your environment. In this example -```php:config/mail.php + + +```php title="config/mail.php" return [ - 'default' => env('MAIL_MAILER', 'log'), + 'default' => env('MAIL_MAILER', 'smtp'), 'mailers' => [ 'smtp' => [ 'transport' => 'smtp', 'url' => env('MAIL_URL'), 'host' => env('MAIL_HOST', '127.0.0.1'), - 'port' => env('MAIL_PORT', 2525), + 'port' => env('MAIL_PORT', 587), 'encryption' => env('MAIL_ENCRYPTION', 'tls'), 'username' => env('MAIL_USERNAME'), 'password' => env('MAIL_PASSWORD'), @@ -66,11 +51,6 @@ return [ 'transport' => 'postmark', ], - 'log' => [ - 'transport' => 'log', - 'channel' => env('MAIL_LOG_CHANNEL'), - ], - 'failover' => [ 'transport' => 'failover', 'mailers' => [ @@ -87,45 +67,55 @@ return [ ]; ``` -:::tip Available Transports -Laravel supports multiple mail transports: -- "smtp" - Standard SMTP server -- "sendmail" - Server's sendmail -- "mailgun" - Mailgun API -- "ses" - Amazon SES -- "postmark" - Postmark -- "log" - Log messages for testing -- "array" - Store in array for testing -- "failover" - Fallback to next mailer if one fails -- "roundrobin" - Rotate between multiple mailers +:::tip Available Mail Transports +Laravel supports multiple mail transport options: +- 'smtp' - Standard SMTP server +- 'sendmail' - Server's sendmail +- 'mailgun' - Mailgun API +- 'ses' - Amazon SES +- 'postmark' - Postmark +- 'log' - Log messages for testing +- 'array' - Store in array for testing +- 'failover' - Fallback to next mailer if one fails +- 'roundrobin' - Rotate between multiple mailers ::: + + -### Sending Emails +### Environment Configuration -Basic example of sending an email: +Configure your Laravel service with the required mail variables. The following example shows SMTP configuration, but most settings are common across different mail transports: -```php -use Illuminate\Support\Facades\Mail; -use App\Mail\WelcomeEmail; +```yml title="zerops.yml" +zerops: + - setup: app + run: + envVariables: + MAIL_MAILER: smtp + MAIL_FROM_ADDRESS: noreply@yourdomain.com + MAIL_FROM_NAME: YourApp + MAIL_HOST: your-smtp-host + MAIL_PORT: 587 + MAIL_USERNAME: your-username + MAIL_PASSWORD: your-password + MAIL_ENCRYPTION: tls +``` -// Send immediately -Mail::to($user->email)->send(new WelcomeEmail($user)); +If using other mail transports, you might need additional environment variables. Refer to Laravel's Mail documentation for transport-specific configuration. -// Send using queue -Mail::to($user->email)->queue(new WelcomeEmail($user)); -``` +## Implementing Email Functionality ### Creating Mail Classes -Generate a new mail class: +Generate a new mail class using Artisan: ```bash php artisan make:mail WelcomeEmail ``` -Example mail class: - -```php:app/Mail/WelcomeEmail.php + + +```php title="app/Mail/WelcomeEmail.php" + ### Email Template -Create a blade template for your email: +Create a blade template for your email content: -```php:resources/views/emails/welcome.blade.php +```php title="resources/views/emails/welcome.blade.php" # Welcome {{ $user->name }} @@ -168,11 +160,34 @@ Thanks,
 ``` -## Queue Configuration for Emails +### Sending Emails + +You can send emails either immediately or using a queue: -When using Redis for queues, your email configuration will work automatically with the following settings: +```php +use Illuminate\Support\Facades\Mail; +use App\Mail\WelcomeEmail; + +// Send immediately +Mail::to($user->email)->send(new WelcomeEmail($user)); + +// Send using queue +Mail::to($user->email)->queue(new WelcomeEmail($user)); +``` + +## Queue Configuration +For production environments, it's recommended to use a queue system for sending emails to prevent request timeouts and improve application performance. Zerops provides Valkey, an open-source Redis-compatible service that's perfect for handling email queues. +First, add the Valkey service to your project: ```yml +services: + - hostname: redis + type: valkey@7.2 + mode: NON_HA # use HA for high availability in production +``` + +Configure your Laravel service to use Redis for queues: +```yml title="zerops.yml" zerops: - setup: app run: @@ -181,9 +196,65 @@ zerops: QUEUE_CONNECTION: redis REDIS_HOST: redis REDIS_PORT: 6379 - REDIS_CLIENT: phpredis + REDIS_CLIENT: phpredis # PHP Redis client for better performance # Mail Configuration + MAIL_MAILER: smtp + MAIL_HOST: your-smtp-host.com + MAIL_PORT: 587 + MAIL_USERNAME: your-username + MAIL_PASSWORD: your-password + MAIL_ENCRYPTION: tls + MAIL_FROM_ADDRESS: noreply@yourdomain.com + MAIL_FROM_NAME: YourApp +``` + +You can customize the queue behavior in your `config/queue.php`: + + + + +```php title="config/queue.php" +phpCopy'default' => env('QUEUE_CONNECTION', 'redis'), + +'connections' => [ + 'redis' => [ + 'driver' => 'redis', + 'connection' => 'default', + 'queue' => 'default', + 'retry_after' => 90, // Retry failed jobs after 90 seconds + 'block_for' => null, // Don't block when no jobs available + ], +], +``` + + + +## Development Environment + +For local development and testing, Zerops provides a Mailpit service that allows you to catch and inspect all outgoing emails. + +### Setting up Mailpit + +Add this to your project import configuration or import the service separately: + +```yml +services: + - hostname: mailpit + type: go@1 + buildFromGit: https://github.com/zeropsio/recipe-mailpit + enableSubdomainAccess: true +``` + +See [Mailpit recipe repo](https://github.com/zeropsio/recipe-mailpit) for reference. + +Configure your Laravel service to use Mailpit for development: + +```yml +zerops: + - setup: app + run: + envVariables: MAIL_MAILER: smtp MAIL_HOST: mailpit MAIL_PORT: 1025 @@ -191,10 +262,16 @@ zerops: MAIL_FROM_NAME: ZeropsLaravel ``` -:::tip Best Practices -- Use Mailpit for development email testing -- Configure Redis for queued email sending -- Set proper environment variables for each environment -- Monitor email delivery through Mailpit interface +:::tip +Enable `enableSubdomainAccess` to access the Mailpit web interface where you can view all emails during development. ::: +## Best Practices + +- Use queue for sending emails in production to prevent request timeouts +- Configure proper timeouts for SMTP connections +- Use environment variables for all mail settings +- Implement proper error handling for failed email deliveries +- Test email templates across different email clients +- Monitor email delivery rates and bounce rates +- Use Mailpit in development to catch and debug emails \ No newline at end of file diff --git a/apps/docs/content/references/vpn.mdx b/apps/docs/content/references/vpn.mdx index 4e41bf8a..eb7e1360 100644 --- a/apps/docs/content/references/vpn.mdx +++ b/apps/docs/content/references/vpn.mdx @@ -92,5 +92,5 @@ utilizes cryptography. It helps us create a secure tunnel that uses UDP for transmitting traffic. We use public/private key pairs for authorization. -Inside Zerops project runs a Wireguard server and zCLI(Zerops Command Line Interface) works as +Inside Zerops project runs a Wireguard server and zCLI (Zerops Command Line Interface) works as a Wireguard client which helps you to interact with your zerops project if you're authorized. diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index 2c5c43d5..b6c67878 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -1,11 +1,11 @@ --- -title: Using Zerops Setup Control(Zsc) +title: Using Zerops Setup Control (zsc) description: Interacting with zerops containers by connecting to the project network via zcli vpn with wireguard. --- import Image from '/src/components/Image'; -Zerops Setup Control(Zsc) is a cli tool / helper installed to all containers, runtime and build, +Zerops Setup Control (zsc) is a cli tool / helper installed to all containers, runtime and build, which allows some direct modifications, like triggering scaling from inside the container, adding new technologies, making sure that commands (like migration) run only once (even when staring some high available setup with 3 containers) diff --git a/apps/docs/docusaurus.config.js b/apps/docs/docusaurus.config.js index 0ca092eb..9362be65 100644 --- a/apps/docs/docusaurus.config.js +++ b/apps/docs/docusaurus.config.js @@ -87,7 +87,31 @@ const config = { }, prism: { defaultLanguage: "ts", - additionalLanguages: ["bash", "json"], + additionalLanguages: [ + "bash", // For CLI commands + "json", // Already included + "php", // For PHP & Apache/nginx + "yaml", // For config files + "sql", // For PostgreSQL/MariaDB + "nginx", // For nginx configs + "go", // For Go code + "java", // For Java code + "python", // For Python code + "rust", // For Rust code + "typescript", // For Node.js/Deno + "javascript", // For Node.js/Bun + "csharp", // For .NET + "elixir", // For Elixir + "ruby", // Common in web development + "toml", // Common for Rust configs + "properties", // For various config files + "groovy", // For Java-related builds + "hcl", // For infrastructure configs + "diff", // For showing changes + "scss", // For static sites + "css", // For static sites + "http", // For API examples + ], plugins: ["line-numbers", "show-language"], theme: { ...prismThemes.vsDark, diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js index bef0598d..f426d494 100644 --- a/apps/docs/sidebars.js +++ b/apps/docs/sidebars.js @@ -114,201 +114,6 @@ module.exports = { }, className: 'homepage-sidebar-item service-sidebar-item', }, - // { - // type: 'category', - // label: 'Perfectly suited for', - // collapsible: false, - // customProps: { - // sidebar_is_group_headline: true, - // }, - // items: [ - // { - // type: "html", - // value: "Perfectly suited for", - // customProps: { - // sidebar_is_group_divider: true, - // }, - // className: "homepage-sidebar-item", - // }, - // { - // type: "category", - // label: "Nest.js", - // link: { - // type: "doc", - // id: "frameworks/nestjs/index", - // }, - // customProps: { - // sidebar_icon: "nestjs", - // }, - // className: "homepage-sidebar-item", - // items: [ - // { - // type: "doc", - // id: "frameworks/nestjs/index", - // label: "Overview & quickstart", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/log", - // label: "Setup & access logs", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/template", - // label: "Create templates with import & seed", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/env-variables", - // label: "Utilize environment variables", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/migration", - // label: "Migration & upgrades", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/backups", - // label: "Backups", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/scaling", - // label: "Optimize scaling", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/scaling", - // label: "High availability, when, how, why", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/cron", - // label: "CRON / Scheduled jobs", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/mails", - // label: "SMPT & sending emails", - // }, - // { - // type: "doc", - // id: "frameworks/nestjs/routing", - // label: "Public access from domain, IP, subdomain", - // }, - // ], - // }, - // { - // type: "category", - // label: "Laravel", - // link: { - // type: "doc", - // id: "frameworks/laravel/index", - // }, - // customProps: { - // sidebar_icon: "laravel", - // }, - // className: "homepage-sidebar-item", - // items: [ - // { - // type: "doc", - // id: "frameworks/laravel/examples", - // label: "Examples", - // customProps: { - // exclude_from_doc_list: false, - // }, - // }, - // ], - // }, - // { - // type: "category", - // label: "Gingonic", - // link: { - // type: "doc", - // id: "frameworks/gingonic/index", - // }, - // customProps: { - // sidebar_icon: "gingonic", - // }, - // className: "homepage-sidebar-item", - // items: [ - // { - // type: "doc", - // id: "frameworks/gingonic/examples", - // label: "Examples", - // customProps: { - // exclude_from_doc_list: false, - // }, - // }, - // ], - // }, - // { - // type: "category", - // label: "Nette", - // link: { - // type: "doc", - // id: "frameworks/nette/index", - // }, - // customProps: { - // sidebar_icon: "nette", - // }, - // className: "homepage-sidebar-item", - // items: [ - // { - // type: "doc", - // id: "frameworks/nette/examples", - // label: "Examples", - // customProps: { - // exclude_from_doc_list: false, - // }, - // }, - // ], - // }, - // { - // type: "category", - // label: "Strapi", - // link: { - // type: "doc", - // id: "frameworks/strapi/index", - // }, - // customProps: { - // sidebar_icon: "strapi", - // }, - // className: "homepage-sidebar-item", - // items: [ - // { - // type: "doc", - // id: "frameworks/strapi/examples", - // label: "Examples", - // customProps: { - // exclude_from_doc_list: false, - // }, - // }, - // ], - // }, - // { - // type: "category", - // label: "Medusa", - // link: { - // type: "doc", - // id: "frameworks/medusa/index", - // }, - // customProps: { - // sidebar_icon: "medusa", - // }, - // className: "homepage-sidebar-item", - // items: [ - // { - // type: "doc", - // id: "frameworks/medusa/examples", - // label: "Examples", - // customProps: { - // exclude_from_doc_list: false, - // }, - // }, - // ], - // }, { type: 'html', value: 'All Supported Services', @@ -2716,38 +2521,16 @@ module.exports = { }, }, { - type: 'category', - label: 'Initial Setup', - collapsible: false, + type: 'doc', + id: 'frameworks/laravel/introduction', + label: 'Quickstart Guide', customProps: { - sidebar_is_group_headline: true, + sidebar_icon: 'rocket-launch', }, - items: [ - { - type: 'doc', - id: 'frameworks/laravel/create-project', - label: 'Create Project', - }, - { - type: 'doc', - id: 'frameworks/laravel/create-service', - label: 'Create PHP Nginx service', - }, - { - type: 'doc', - id: 'frameworks/laravel/build-deployments', - label: 'Build & Deployments', - }, - { - type: 'doc', - id: 'frameworks/laravel/env-variables', - label: 'Environment Variables', - }, - ], }, { type: 'category', - label: 'Advanced', + label: 'Features', collapsible: false, customProps: { sidebar_is_group_headline: true, @@ -2755,49 +2538,39 @@ module.exports = { items: [ { type: 'doc', - id: 'frameworks/laravel/cron', - label: 'Schedule Jobs & CRON', + id: 'frameworks/laravel/env-variables', + label: 'Environment Variables', }, +// { +// type: 'doc', +// id: 'frameworks/laravel/local-development', +// label: 'Local Development', +// }, { type: 'doc', - id: 'frameworks/laravel/redis', - label: 'Manage Redis', + id: 'frameworks/laravel/migrations', + label: 'Database Migrations', }, { type: 'doc', - id: 'frameworks/laravel/smtp', - label: 'SMTP Configuration', + id: 'frameworks/laravel/redis', + label: 'Cache & Queue with Redis', }, { type: 'doc', - id: 'frameworks/laravel/migrations', - label: 'Database Migrations', + id: 'frameworks/laravel/cron', + label: 'Schedule Jobs & CRON', }, - ], - }, - { - type: 'category', - label: 'Good to know', - collapsible: false, - customProps: { - sidebar_is_group_headline: true, - }, - items: [ { type: 'doc', - id: 'frameworks/laravel/public-access', - label: 'Manage Public Access', + id: 'frameworks/laravel/smtp', + label: 'SMTP Configuration', }, { type: 'doc', id: 'frameworks/laravel/logs', - label: 'Access logs', + label: 'Logs', }, - { - type: 'doc', - id: 'frameworks/laravel/backups', - label: 'Database Backups', - }, ], }, { diff --git a/apps/docs/src/components/CustomCardWithIcon/index.tsx b/apps/docs/src/components/CustomCardWithIcon/index.tsx new file mode 100644 index 00000000..c816ced4 --- /dev/null +++ b/apps/docs/src/components/CustomCardWithIcon/index.tsx @@ -0,0 +1,32 @@ +import React from 'react'; + +interface CustomCardWithIconProps { + icon: React.ComponentType>; + title: string; + children: React.ReactNode; + iconProps?: React.SVGProps; +} + +const CustomCardWithIcon: React.FC = ({ + title, + children, + icon: Icon, + iconProps = { + width: 20, + height: 20 + } +}) => { + return ( +
+ + + + + {title} + {children} + +
+ ); +}; + +export default CustomCardWithIcon; \ No newline at end of file diff --git a/apps/docs/src/css/custom.css b/apps/docs/src/css/custom.css index a93c9ded..859f4bea 100644 --- a/apps/docs/src/css/custom.css +++ b/apps/docs/src/css/custom.css @@ -177,6 +177,10 @@ html[data-theme='dark'] { height: 20px; } +.height-100 { + height: 100%; +} + html[data-theme='dark'] .docsearch-btn { background: #27282d !important; color: rgba(82, 82, 91, 1) !important; diff --git a/apps/docs/src/theme/Icon/Filament/index.tsx b/apps/docs/src/theme/Icon/Filament/index.tsx new file mode 100644 index 00000000..87e4f7dd --- /dev/null +++ b/apps/docs/src/theme/Icon/Filament/index.tsx @@ -0,0 +1,19 @@ +import { IconProps } from '@medusajs/icons/dist/types'; +import clsx from 'clsx'; +import React from 'react'; + +const IconFilament = (props: IconProps) => { + return ( + + + + ); +}; + +export default IconFilament; diff --git a/apps/docs/src/theme/Icon/Laravel copy/index.tsx b/apps/docs/src/theme/Icon/Laravel copy/index.tsx deleted file mode 100644 index a07dc8a5..00000000 --- a/apps/docs/src/theme/Icon/Laravel copy/index.tsx +++ /dev/null @@ -1,32 +0,0 @@ -import { IconProps } from '@medusajs/icons/dist/types'; -import clsx from 'clsx'; -import React from 'react'; - -const IconLaravel = (props: IconProps) => { - return ( - - - - - ); -}; - -export default IconLaravel; diff --git a/apps/docs/src/theme/Icon/Laravel/index.tsx b/apps/docs/src/theme/Icon/Laravel/index.tsx index a07dc8a5..aa12cb09 100644 --- a/apps/docs/src/theme/Icon/Laravel/index.tsx +++ b/apps/docs/src/theme/Icon/Laravel/index.tsx @@ -5,26 +5,15 @@ import React from 'react'; const IconLaravel = (props: IconProps) => { return ( - - + width={props.width || 20} + height={props.height || 20} + viewBox="0 0 256 264" + {...props} + preserveAspectRatio="xMidYMid" + className={clsx('text-ui-fg-subtle', props.className)}> + ); }; diff --git a/apps/docs/src/theme/Icon/LaravelJetstream/index.tsx b/apps/docs/src/theme/Icon/LaravelJetstream/index.tsx new file mode 100644 index 00000000..f8817e1a --- /dev/null +++ b/apps/docs/src/theme/Icon/LaravelJetstream/index.tsx @@ -0,0 +1,24 @@ +import { IconProps } from '@medusajs/icons/dist/types'; +import clsx from 'clsx'; +import React from 'react'; + +const IconLaravelJetstream = (props: IconProps) => { + return ( + + + + + + + ); +}; + +export default IconLaravelJetstream; diff --git a/apps/docs/src/theme/Icon/Twill/index.tsx b/apps/docs/src/theme/Icon/Twill/index.tsx new file mode 100644 index 00000000..2512cbf3 --- /dev/null +++ b/apps/docs/src/theme/Icon/Twill/index.tsx @@ -0,0 +1,20 @@ +import { IconProps } from '@medusajs/icons/dist/types'; +import clsx from 'clsx'; +import React from 'react'; + +const IconTwill = (props: IconProps) => { + return ( + + + + + + ); +}; + +export default IconTwill;